Skip to main content

Get started with the Widget SDK

This guide embeds the widget in a page, listens to the cart and hands it over to your checkout. Check the requirements first: in particular, your domain must be allowed in the sales channel.

1. Load the SDK​

Add the script to the <head> of your page. It must be loaded with type="module".

<script type="module" src="https://widget.oneboxtds.com/widget-sdk-v1.js"></script>

Use https://widget.oneboxtds.net/widget-sdk-v1.js in the test environment. The SDK is available as window.onebox.widget once the page's DOMContentLoaded event has fired.

2. Place the widget element​

Add the seat selection element where you want the widget to appear. Its attributes control what it shows; see Configuration.

<ob-widget-seats-selection with-summary with-summary-promos></ob-widget-seats-selection>

The element adapts to its width: from 700 px it shows the venue map and the summary side by side, and below that one above the other.

3. Initialise it​

Call init() with the sales channel and the session to sell:

window.addEventListener('DOMContentLoaded', () => {
  onebox.widget.init({
    channelId: 1752,
    sessionId: 509945,
    lang: 'en-GB',
  });
});

See all the init() options.

4. Listen to the cart​

Register listeners on the widget modules to follow what the buyer does. The most important one is onOrderChange, which receives the order every time the cart changes:

const core = onebox.widget.getModule('core');

core.onOrderChange((order) => {
  const seats = order.items.length;
  document.querySelector('#checkout-button').disabled = seats === 0;
});

core.onOrderExpired(() => {
  alert('Your reservation has expired. Please select your seats again.');
});

All the events and methods are listed in the API reference.

5. Complete the purchase​

When the buyer clicks your checkout button, send the order id to your backend and complete the purchase with the Distribution API, from Step 4 of the purchase flow: attendee and buyer data, pre-confirmation, payment and confirmation.

let currentOrder;
core.onOrderChange((order) => { currentOrder = order; });

document.querySelector('#checkout-button').addEventListener('click', () => {
  // Your backend continues the purchase with the Distribution API, using this id.
  window.location.href = `/checkout?order=${currentOrder.id}`;
});

The seats stay reserved for the buyer until the order expires: check order.status.expires_in to show the remaining time.

Full example​

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Choose your seats</title>
    <script type="module" src="https://widget.oneboxtds.com/widget-sdk-v1.js"></script>
    <script>
      window.addEventListener('DOMContentLoaded', () => {
        const core = onebox.widget.getModule('core');
        let currentOrder;

        core.onOrderChange((order) => {
          currentOrder = order;
          document.querySelector('#checkout-button').disabled = order.items.length === 0;
        });
        core.onError((error) => console.error('Widget error', error));

        document.querySelector('#checkout-button').addEventListener('click', () => {
          window.location.href = `/checkout?order=${currentOrder.id}`;
        });

        onebox.widget.init({ channelId: 1752, sessionId: 509945, lang: 'en-GB' });
      });
    </script>
  </head>
  <body>
    <ob-widget-seats-selection with-summary with-summary-promos></ob-widget-seats-selection>
    <button id="checkout-button" disabled>Checkout</button>
  </body>
</html>

Change the session or the language​

Call init() again to show another session. The new options are merged with the previous ones, but channelId and sessionId are always required:

onebox.widget.init({ channelId: 1752, sessionId: 509946 });

To change only the language, use setLanguage():

onebox.widget.getModule('core').setLanguage('es-ES');

Resume a cart​

The widget remembers the buyer's cart in their browser, so reloading the page keeps the selected seats. To resume a specific order instead, for example after the buyer comes back from your checkout, pass its id as orderId:

onebox.widget.init({ channelId: 1752, sessionId: 509945, orderId: 'b3f0c9d2a8e14f6b9c7d5e3a1f2b4c6d' });

Add releaseBasketItems: true to empty that order when the widget starts.