@shelf/ssp-sdk

ShelfSSPSDK

The ShelfSSPSDK is a JavaScript library that allows you to easily integrate and interact with the ShelfSSP iframe-based Single-Page Application. It provides methods for initializing the ShelfSSP iframe, constructing URLs, tracking URL changes, handling events, and sending messages to the ShelfSSP.

Install

npm install @shelf/ssp-sdk

or

yarn add @shelf/ssp-sdk

As script

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@shelf/ssp-sdk@:tag-version:/lib/integration.self-service-portal.min.js"></script>

Usage

To use the ShelfSSPSDK, import it into your JavaScript or TypeScript file:

import { ShelfSSPSDK } from '@shelf/ssp-sdk';

Initialize the ShelfSSP iframe

To initialize the ShelfSSP iframe, use the initialize method:

ShelfSSPSDK.initialize({
  element: document.getElementById('shelf-ssp-container'),
  sspURL: 'https://example.com/ssp',
  lang: 'en',
  slug: 'product',
  searchParams: { category: 'electronics', brand: 'apple' },
  onReady: () => {
    console.log('ShelfSSP is ready');
  }
});

The initialize method takes an object with the following properties:

• element (HTMLElement): The DOM element where the ShelfSSP iframe will be appended.
• sspURL (string): The base URL of the ShelfSSP.
• lang (string): The language parameter for the ShelfSSP URL.
• slug (string): The slug parameter for the ShelfSSP URL.
• searchParams (Record<string, string>): Additional query parameters for the ShelfSSP URL.
• onReady (optional function): A callback function that will be called when the ShelfSSP iframe is loaded and ready.

Handle events from the ShelfSSP

To handle events sent from the ShelfSSP, use the on method:

ShelfSSPSDK.on('event', (data) => {
  console.log('Received event:', data);
});

The on method takes an event name and a callback function. The callback function will be called whenever an event with the specified name is received from the ShelfSSP.

Send messages to the ShelfSSP

To send messages to the ShelfSSP, use the postMessage method:

ShelfSSPSDK.postMessage('action', { payload: 'data' })
  .then((response) => {
    console.log('Received response:', response);
  });

The postMessage method takes a message type and an optional payload. It returns a promise that resolves with the response from the ShelfSSP.

Close the ShelfSSP iframe

To close the ShelfSSP iframe, use the close method:

ShelfSSPSDK.close();

The close method removes the ShelfSSP iframe from the DOM.

CommunicationChannel

The CommunicationChannel class is a utility class that provides methods for initializing and interacting with a communication channel using the structured-channel library.

Usage

To use the CommunicationChannel class, import it into your JavaScript or TypeScript file:

import { CommunicationChannel } from '@shelf/sdk-ssp';

Initialize the Communication Channel

Before using the communication channel, you need to initialize it by calling the init method:

await CommunicationChannel.init();

The init method establishes a connection with the structured-channel and prepares the communication channel for sending and receiving messages.

Send Messages

To send messages through the communication channel, use the send method:

await CommunicationChannel.send('action', { payload: 'data' });

The send method takes a message type and an optional payload. It sends the message through the communication channel and returns a promise that resolves with the response from the other end of the channel.

Handle Events

To handle events received through the communication channel, use the on method:

CommunicationChannel.on('event', (data) => {
  // Handle the event data
});

The on method takes an event name and a callback function. The callback function will be called whenever an event with the specified name is received through the communication channel.

Stop Handling Events

To stop handling events for a specific event name, use the off method:

CommunicationChannel.off('event', callback);

The off method removes the specified callback function from the event listeners for the given event name.

MIT © Shelf