# Migration guide

## 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](https://docs.ipaper.io/commands-and-events/publication#getdetails)
* The ability to execute a search directly via [search.query](https://docs.ipaper.io/commands-and-events/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](https://docs.ipaper.io/advanced-usage#multiple-embedded-flipbooks).

### 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](https://docs.ipaper.io/getting-started#setting-up-the-api-in-custom-scripting).

## 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:

{% code title="Example of V2 API embed script" %}

```html
<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>
```

{% endcode %}

The new embed script for V3 can be seen below:

{% code title="New V3 API embed script" %}

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

{% endcode %}

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:

<pre class="language-html" data-title="Example V2 initialization"><code class="lang-html">&#x3C;iframe src="https://demo.ipaper.io">&#x3C;/iframe>

&#x3C;script>
<strong>    function iPaperInit() {
</strong><strong>        // Your API commands and events here
</strong><strong>    }
</strong>&#x3C;/script>
</code></pre>

Or something like this:

{% code title="Example V2 initialization via event listener" %}

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

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

{% endcode %}

You will now need this instead:

{% code title="Example V3 initialization" %}

```html
<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>
```

{% endcode %}

{% hint style="info" %}
**Note:**

This way of instantiating the API will only work for V3 and later.
{% endhint %}

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.](https://docs.ipaper.io/flipbook-javascript-api/advanced-usage)

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.

{% hint style="danger" %}
**Note:**

[Command triggers](https://docs.ipaper.io/legacy-javascript-api-v2/advanced-usage#event-listeners-and-command-triggers) are no longer supported with V3. Any usage of these will have to be updated.
{% endhint %}

### `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:

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

You will now need something like this instead:

<pre class="language-javascript"><code class="lang-javascript">myApiInstance.updateConfig({
    preventAction: {
        basketClick: true,
        itemAdd: true
<strong>    }
</strong>});
</code></pre>

`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:

```javascript
myApiInstance.paging.goToPage(4);
```

### `goToPreviousPage`

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

```javascript
myApiInstance.paging.goToPrevPage();
```

### `goToNextPage`

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

```javascript
myApiInstance.paging.goToNextPage();
```

### `addItem`

{% hint style="warning" %}
**Be aware:**

The `productID` property has been renamed `productId` in V3.
{% endhint %}

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

```javascript
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:

```javascript
// 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:

```javascript
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](https://docs.ipaper.io/flipbook-javascript-api/commands-and-events).

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.

{% hint style="danger" %}
**Note:**

[Event listeners](https://docs.ipaper.io/legacy-javascript-api-v2/advanced-usage#event-listeners-and-command-triggers) are no longer supported with V3. Any usage of these will have to be updated.
{% endhint %}

### `onPageElementClick`

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

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

### `onSpreadChange`

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

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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:

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ipaper.io/flipbook-javascript-api/migration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.