Expivi IFrame API specification

Description

The Expivi iFrame API is a wrapper around the window.postMessage(target: Window) functionality, as such it allows us to send message from an Expivi iFrame to the host page. It also allows the host page to send message back to the Expivi iFrame.

This way we can achieve a tightly-knit application while still keeping a separation of concerns.

Initialization

To initialize the Expivi iFrame Api you will need to instantiate it. This can be done as follows:

const frameId = 'expivi-iframe-id';
const targetFrame = document.getElementById(frameId);
window.xpv.iFrameService = new ExpiviIFrameService(targetFrame.contentWindow);

This will ensure that your page begins listening to the Expivi iFrame. Then, once the Expivi iFrame has initialized itself on our side, we will fire off the "ready" event. You can listen to this via a promise, using the following code:

window.xpv.iFrameService.isReady().then(() => {
    // the Expivi iFrame is now ready to receive messages.
});

Interactions

iFrame interactions using the querystring

Loading a certain "configurator state" can be done through the following querystring parameters.

// provided by Expivi
`${iframe-source}?preset-id=${some-preset-id}`

 // saved product id (made via saving a configuration)
`${iframe-source}?cpi=${some-configured-product-index}`

When both, a preset-id and a cpi have been provided, the cpi takes precedence.

Expivi allows you to hide certain agreed upon parts of the page. This works by specifying the following querystring parameter:

`${iframe-source}?hide-element={some-element-id}&hide-element={some-other-element-id}&hide-element=...`

Any element that has the data-hideable-id attribute can be hidden by using the attribute value. e.g.

<div id="some-div-that-isnt-hideable">You can't hide me</div>
<div data-hideable-id="42">But you can hide me!</div>
<span data-hideable-id="20">And you can also hide me.</span>

User logged in or out

Expivi can change its visuals when your user logs in and out to your system, to facilitate this you will have to send an event whenever the user is logged in or out. This event can be caught be Expivi once the ready event above has been fired by the iframe.

window.xpv.iFrameService.userHasLoggedIn();
window.xpv.iFrameService.userHasLoggedOut();

Note: The default user state for expivi is the logged out state. When a user is logged in you should start of by calling the userHasLoggedIn() command. We do not remember state between reloads, in order to stay compliant with privacy laws and browser specifics.

Add To Cart

Expivi can send an event when our 'add to cart' button has been pressed. This event can be captured with a callback, that can be set as follows:

const someHandlerFunction = (xpvEvent) => { /* does some work */ };
window.xpv.iFrameService.setEventListener('v1.add-to-cart', someHandlerFunction);

The xpvEvent in this case is the following object:

{
    cpi: number;
    products: [
        {
            sku: string,
            thumbnail: string, // a base64 encoded image
        },
        // if you use a multi product viewer,
        // this array will contain more than one element
    ];
}

Save Current Configured Product

Expivi can save a user their current configuration for later usage. This action fires an event off to the parent frame, which can then handle this situation.

const someHandlerFunction = (xpvEvent) => { /* does some work */ };
window.xpv.iFrameService.setEventListener('v1.save-current-config', someHandlerFunction);

The xpvEvent in this case looks like the following object:

{
    cpi: number;
    thumbnail: string; // a base64 encoded image
}

Before Image Upload

Expivi can send an event before opening an image upload. This event can be used to create a modal to show the terms of service of uploaded images. The handler should return true or false depending on if the user should be allowed to start uploading. You can capture this event like so:

{
    const someHandlerFunction = () => allowedToUpload; // allowed to upload is a boolean
    window.xpv.iFrameService.setEventListener('v1.before-image-upload', someHandlerFunction);
}