Migration guide

This page will help you through the process of migrating an existing V2 implementation to the new V3 Flipbook JavaScript API. The new V3 API contains all the features from V2 as well as new ones.

Why you should consider migrating

New commands & events

The V3 JS API comes with new functionality that could be useful to you. In addition, more functionality will be added over time, which won't be the case with V2.

Some of the new functionality in V3 include:

• The ability to check the current state of paging, basket, search, and table of contents

• The ability to explicitly close or open basket, search, and table of contents

• The ability to retrieve the details of the flipbook via publication.getDetails

• The ability to execute a search directly via search.query

Improved stability and performance

The way the V3 JS API has been built improves both stability and general performance of commands and events. Another thing that has been particularly streamlined and improved is the initialization process.

Better integration with multiple flipbooks

Due to the improvements made to the initialization process, it is now much easier to work with pages containing multiple embedded flipbooks. For more on this, see this page.

The API can now be used via Custom Scripting

Unlike the V2 JS API, the V3 JS API can be used directly inside Custom Scripting with feature parity to when used externally. For how to get started with this, see this page.

Step 1: Migrate API initialization

Updating the API embed script

To migrate to the new V3 API, you will need to update the API embed script on your page. Your current embed script should look something like this:

Example of V2 API embed 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>

The new embed script for V3 can be seen below:

New V3 API embed script

<script src='https://cdn.ipaper.io/flipbooks/api/v3/latest.js'></script>

Once you have the added the new embed script, simply remove/delete the old one from the page.

Updating existing script to initialize API instance

The way of initializing the API has changed a bit in V3. Instead of relying on an automatic process of detecting the iframe containing a flipbook and instantiating the API with this iframe, you will now need to instantiate the API manually by passing in the iframe and an API version as parameters.

So, where you previously may have had something like this:

Example V2 initialization

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

<script>
    function iPaperInit() {
        // Your API commands and events here
    }
</script>

Or something like this:

Example V2 initialization via event listener

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

<script>
    document.addEventListener('iPaperInit', function() {
        // Your API commands and events here
    });
</script>

You will now need this instead:

Example V3 initialization

<iframe src="https://demo.ipaper.io" id="myFlipbook"></iframe>

<script>
    /* 
    Locate the iframe you want the API to be instantiated on. 
    This could be done multiple different ways, but for this example we will rely
    on the iframe having a unique ID.
    */
    const myIframe = document.getElementById('myFlipbook');
    
    // Create a new V3 API instance with the iframe
    const myApiInstance = iPaperJsApi(myIframe, 3);
</script>

Note:

This way of instantiating the API will only work for V3 and later.

Once this has been done, you can use/access API commands and events directly on the created instance variable (FX. myApiInstance.basket.open()).

Are you using multiple embedded flipbooks on the same page?

The change to initialization will also make it much easier to work with pages containing multiple embedded Flipbooks. For more on how to create multiple API instances on the same page, see here.

If you are currently using the V2 way of having multiple embedded flipbooks, you will need to update this to be done in the new V3 way, as can be seen in the link above. The V2 way is not supported in V3.

Step 2: Migrate API commands

API commands generally work the same in V3 as they did in V2. They have, however, been split into more detailed categories, and some have been renamed or altered slightly. Below, you can see the V2 API commands and their V3 equivalents.

Note:

Command triggers are no longer supported with V3. Any usage of these will have to be updated.

updateEventSettings

This command has been changed a bit in V3. It has been converted to be a more universal command for updating an API instance's configuration.

So, where you may have had something like this before:

iPaperAPI.updateEventSettings({
    onBasketClick: { preventDefault: true },
    onItemAdd: { preventDefault: true }
});

You will now need something like this instead:

myApiInstance.updateConfig({
    preventAction: {
        basketClick: true,
        itemAdd: true
    }
});

basketClick is equivalent to V2's onBasketClick and itemAdd is equivalent to onItemAdd.

goToPage

The location for this command has been changed. It can now be accessed with:

myApiInstance.paging.goToPage(4);

goToPreviousPage

The location and naming for this command has been changed. It can now be accessed with:

myApiInstance.paging.goToPrevPage();

goToNextPage

The location for this command has been changed. It can now be accessed with:

myApiInstance.paging.goToNextPage();

addItem

Be aware:

The productID property has been renamed productId in V3.

The location and naming for this command has been changed. It can now be accessed with:

myApiInstance.basket.addProduct({
    title: 'My product',
    description: 'Product description',
    productId: 'PROD-25B',
    price: '29.95',
    originPage: 6,
    quantity: 1
});

getCookieConsent

The location and naming for this command has been changed. It can now be accessed with:

// You can either await the result of the command
const result = await myApiInstance.consent.get();

// OR pass a callback
myApiInstance.consent.get((result) => {
    // YOUR CODE HERE
});

updateCookieConsent

The location and naming for this command has been changed. It can now be accessed with:

myApiInstance.consent.set({
    allowPerformanceCookies: true, 
    allowFunctionalCookies: true, 
    allowAdvertisingCookies: true
});

Step 3: Migrate API events

In V3, events have been streamlined and updated to run as subscriptions. This makes it easier to add and remove these on demand. For more on this, see this page.

Apart from this change, API events generally work the same in V3 as they did in V2. They have, however, been split into more detailed categories, and some have been renamed. Below, you can see the V2 API events and their V3 equivalents.

Note:

Event listeners are no longer supported with V3. Any usage of these will have to be updated.

onPageElementClick

The location for this event has been changed. It can now be subscribed to using:

myApiInstance.publication.onPageElementClick((result) => {
    // YOUR CALLBACK CODE HERE
});

onSpreadChange

The location for this event has been changed. It can now be subscribed to using:

myApiInstance.publication.onSpreadChange((result) => {
    // YOUR CALLBACK CODE HERE
});

However, while this command is available in V3, we recommend that you consider upgrading to/using the new paging.onChange event instead.

onBasketClick

The location and naming for this event has been changed. It can now be subscribed to using:

myApiInstance.basket.onToggled(() => {
    // YOUR CALLBACK CODE HERE
});

onItemAdd

The location and naming for this event has been changed. It can now be subscribed to using:

myApiInstance.basket.onProductAdd((product) => {
    // YOUR CALLBACK CODE HERE
});

onCookieConsentShown

The location and naming for this event has been changed. It can now be subscribed to using:

myApiInstance.consent.onShow(() => {
    // YOUR CALLBACK CODE HERE
});

onCookieConsentUpdate

The location and naming for this event has been changed. It can now be subscribed to using:

myApiInstance.consent.onChange((result) => {
    // YOUR CALLBACK CODE HERE
});