Quick Start

The v2 Flipbook JavaScript API allows for streamlined interaction with iframed flipbooks using cross-origin communications available in modern browsers.

Overview

Note:

The legacy v2 JS API is now superseded by v3 Flipbook JS API.

The v2 Flipbook JavaScript API uses the window.postMessage API for two-way communications between the parent window and one or more flipbooks embedded in the parent window inside <iframe> elements.

For this to work, you will need to include the API script on your page. Please refer to this help article on how to obtain the iPaper Flipbook JavaScript API script from the admin. The generated code will look something as follow:

<!-- Start of async iPaper Flipbook API script -->
<script>
(function(i,P,a,p,e,r){if(i.getElementById(a=a+'-'+e))return;
r=i.querySelector(P).parentNode.appendChild(i.createElement(P));
r.id=a;r.async=1;r.src=p+'/'+e+'.js'})
(document,'script','ipaper-api','<ApiBaseUrl>','<ApiSecret>');
</script>
<!-- End of async iPaper Flipbook API script -->

Note:

Both <ApiBaseUrl> and <ApiSecret> in the snippet above will be substituted with partner and license-dependent configurations and be automatically populated, when you retrieve the API script from the admin.

Minimal config setup

Most of our customers use our API to interact with a single instance of a flipbook on their page. A frictionless, minimal config setup is therefore implemented—meaning that for use-cases involving single flipbooks iframed on a single page, no additional configuation or markup changes are required. While the setup will automatically attempt to identify the first iframed flipbook on the page, we do still reccommend adding the data-ipaper attribute to the iframe to ensure the most reliable detection:

<iframe src="https://demo.ipaper.io" data-ipaper></iframe>

Note: If you are using multiple flipbooks, additional configuration is required: please refer to the Multiple flipbooks section for further information.

Interacting with iframed flipbook

The embedded script will call the iPaperInit() method that is defined globally in the parent window, and you can then interact with the iframed flipbook via the iPaperAPI instance created by default:

<!doctype html>
<html>
<head>
    <title>Example Flipbook JS API use</title>

    <!-- Start of async iPaper Flipbook API script -->
    <!-- NOTE: The entire code snippet below can be obtained directly from the Admin. Refer to our help article for further information. -->
    <script>
    (function(i,P,a,p,e,r){if(i.getElementById(a=a+'-'+e))return;
    r=i.querySelector(P).parentNode.appendChild(i.createElement(P));
    r.id=a;r.async=1;r.src=p+'/'+e+'.js'})
    (document,'script','ipaper-api','<ApiBaseUrl>','<ApiSecret>');
    </script>
    <!-- End of async iPaper Flipbook API script -->
    
    <script>
        function iPaperInit() {
            // Define a callback for the `onSpreadChange` event
            // `iPaperAPI` is the default first instance of the API
            iPaperAPI.onSpreadChange = function(data) {
                console.log(data);
            }

            // Navigate to page 4 when a button is clicked
            document.getElementById('page-4-button').addEventListener('click', function() {
                iPaperAPI.goToPage(4);
            });
        }
    </script>
</head>
<body>
    <iframe src="https://demo.ipaper.io" style="width: 100%; height: 400px;" data-ipaper></iframe>
    <button type="button" id="page-4-button">Go to page 4</button>
</body>
</html>

The iPaperAPI object exposes several methods that can be grouped into two categories: magic event callbacks and magic commands.

  • Events happen on the flipbook and are emitted to the parent window, which trigger magic callbacks. An example of a flipbook event is the onSpreadChange event. Read more about how to listen to these events and react to them accordingly.

  • Commands are instructions issued from the parent window to the flipbook, done via invoking magic commands. An example of a flipbook command is the goToPage method. Read more about how to issue commands to instruct your iframed flipbook to perform specified actions.

As an alternative to using the iPaperInit function like in the snippet above, you can also use an event listener for iPaperInit instead:

<!doctype html>
<html>
<head>
    <title>Example Flipbook JS API use</title>

    <!-- Start of async iPaper Flipbook API script -->
    <!-- NOTE: The entire code snippet below can be obtained directly from the Admin. Refer to our help article for further information. -->
    <script>
    (function(i,P,a,p,e,r){if(i.getElementById(a=a+'-'+e))return;
    r=i.querySelector(P).parentNode.appendChild(i.createElement(P));
    r.id=a;r.async=1;r.src=p+'/'+e+'.js'})
    (document,'script','ipaper-api','<ApiBaseUrl>','<ApiSecret>');
    </script>
    <!-- End of async iPaper Flipbook API script -->
    
    <script>
        document.addEventListener('iPaperInit', function() {
            // Define a callback for the `onSpreadChange` event
            // `iPaperAPI` is the default first instance of the API
            iPaperAPI.onSpreadChange = function(data) {
                console.log(data);
            }

            // Navigate to page 4 when a button is clicked
            document.getElementById('page-4-button').addEventListener('click', function() {
                iPaperAPI.goToPage(4);
            });
        });
    </script>
</head>
<body>
    <iframe src="https://demo.ipaper.io" style="width: 100%; height: 400px;" data-ipaper></iframe>
    <button type="button" id="page-4-button">Go to page 4</button>
</body>
</html>

Multiple flipbooks

In the event that multiple flipbooks are to be embedded via <iframe> on the same page, some additional configuration is required. Refer to the Multiple Flipbooks section for further implementation details.

PreviousLegacy Javascript API (v2)NextCommands

Last updated