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

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

#### Initialize the ShelfSSP iframe

To initialize the `ShelfSSP` iframe, use the initialize method:

```ecmascript 6
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: `ecmascript 6 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:
```ecmascript 6
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: `ecmascript 6 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:
```ecmascript 6
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: `ecmascript 6 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:
```ecmascript 6
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: `ecmascript 6 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:
```ecmascript 6
CommunicationChannel.off('event', callback);

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

MIT © Shelf