Skip to main content

API Library

npm badge

Expivi offers a library to ease the use of iframes with custom integrations for customers.

The library is open-source and available on npm and bitbucket.

It is a wrapper around the window.postMessage API found in modern browsers. This makes interacting with the configurator inside an iframe from your website much easier.

Installation​

You can either install the library using npm with the following command. After installation be sure to include dist/xpv-iframe-api.min.js from the node_modules in your HTML.

install-npm.sh
npm install @expivi/iframe-client

Or via a script tag directly in your HTML.

install-script.html
<script src="https://cdn.jsdelivr.net/npm/@expivi/iframe-client@latest/dist/xpv-iframe-api.min.js"></script>

The ExpiviIFrameService class should now be available on your website's window object.

Initializing​

The ExpiviIFrameService class needs to be initialized with a Window object, that can be the contentWindow of an iframe or window.parent if you are the iframe communicating with a host page.

On the host page, query the Expivi iframe on your website, and pass its contentWindow to the ExpiviIFrameService class.

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

Events​

The API Library has a few events that can be used to customize the experience and/or do custom integrations with your website.

Events work bidirectional, any side (host or iframe) can send any of the events to one another. But this only works if listeners are implemented on the receiving side.

When an event is sent with ExpiviIFrameService.sendMessage a promise is returned if the sender expects a response. If you do not pass a uuid as the third parameter, the message is sent with the status pending to the receiver, "pending" a response from the receiver. If you do pass a uuid, the message will be sent as finished, making it more like a notification.

The promise that is returned will only resolve if the receiver sends a new message to the sender with the same message type and uuid combination.

Any value returned from your event listener is used as the payload for the response to any pending events.

event-example.js
// Host page
const result = await window.xpv.iFrameService.sendMessage('v1.save-current-config');

// iFrame page
window.xpv.iFrameService.setEventListener('v1.save-current-config', () => {
    return { foo: 'bar' };
});

// Host page
console.log(result); // { foo: 'bar' }
warning

The payloads described on this page are specific to Expivi's embed page. The library does not define any payload structure for any of the events.

Ready​

The ready event allows you to wait for Expivi to be ready to use. Use this event to execute some logic as soon as Expivi is ready with initializing.

ready-event.js
await window.xpv.iFrameService.isReady();
// or
window.xpv.iFrameService.setEventListener('v1.ready', () => {
    // Ready to use.
});

Add to Cart​

The add-to-cart event is triggered when the 'add to cart' button is pressed on the embed page.

add-to-cart.js
window.xpv.iFrameService.setEventListener('v1.add-to-cart', () => {
    // Do some work.
});

The add to cart event does not include any data. It serves as a trigger for the host page.

Save Configuration​

Save configuration can be requested by the host page. Send an event to the iframe, and it will respond with the configuration.

save-configuration-request.js
const configuration = await window.xpv.iFrameService.sendMessage('v1.save-current-config');

The object of the SaveConfiguration event includes the complete Expivi product configuration as per window.expivi.saveConfiguration.

This event accepts arguments for the saveCofinguration function in the form of an array.

save-configuration-request-arguments.js
const configuration = await window.xpv.iFrameService.sendMessage('v1.save-current-config', [512, 512, 'ACTIVE_CAMERA', 'image/png', { include_keys: true }]);
note

This is specific to Expivi's embed page, these arguments are not supported on any other page.

Price Changed​

The price-changed updates every time the price has been changed by the configurator.

price-changed.js
window.xpv.iFrameService.setEventListener('v1.price-changed', price => {
    // Do some work.
});

The event receives a float which is the price of the products in the currency that the product is configured with.

The embed page also responds to v1.price-changed events with the current price.

price-changed-ping.js
const price = await window.xpv.iFrameService.sendMessage('v1.price-changed');

Before Image Upload​

warning

This hook is not implemented on the embed page

The before image upload hook is triggered when a user uploads any image in the configuration. This event can be used to create a modal to show the terms of service when uploading images.

The handler should return true or false depending on whether the user is allowed to upload images.

before-image-upload.ts
window.xpv.iFrameService.setEventListener('v1.before-image-upload', async() => {
    // Return true or false based on whether the image should be allowed to be uploaded.
    try {
        await consentFormConfirm();

        return true;
    } catch (e) {
        return false;
    }
});

Example​

This is an example of how the communication between a host and the iframe works.

https://jsfiddle.net/syvkwun9/1/