Widget API reference

The SDK is available as window.onebox.widget. Its features are grouped in two modules: core, for the order and the widget state, and viewer, for the venue map.

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

init(options)void: Starts the widget, or changes its session. See init() options.
getModule(name)object: Returns the module core or viewer. Throws an error for any other name.
listModules()string[]: Names of the available modules.

Listening to events

Each event method receives a callback:

core.onOrderChange((order) => console.log(order));

Each event keeps one callback: registering a new one replaces the previous one, and passing null removes it.
Callbacks can be registered before or after init(). They receive the events that happen from then on.
Methods do not return a value: their result reaches you through the events.

Core module

Events

`onOrderChange`

The order changed: the buyer added or removed seats, applied a promotion, or the widget loaded an existing order. It receives the order.

core.onOrderChange((order) => console.log(order.id, order.items.length, order.price.final));

`onOrderExpired`

The reservation expired and the selected seats were released. It receives no value.

`onError`

A request of the widget failed. It receives the error response:

statusnumber: HTTP status code.
urlstring: URL of the failed request.
error.codestring: Error code, such as SESSION_NOT_FOUND or CHANNEL_NOT_FOUND.
error.messagestring: Description of the error.

`onDialogStateChange`

A dialog of the widget opened or closed. Use it, for example, to pause your own overlays.

isOpenboolean: Whether a dialog is open.

Methods

setLanguage(lang)void: Changes the language, as es, en-GB or ca-ES-valencia. It must be one of the channel's languages.
refreshOrder()void: Loads the order again, for example after your backend changed it.
removeSeats()void: Removes all the seats from the order.
deleteOrder()void: Deletes the order and releases its seats.

Viewer module

The viewer events fire on venues with a seating map.

onElementClickViewElement: The buyer clicked an element of the map. It receives the view element.
onElementMouseInViewElement: The pointer entered an element of the map.
onElementMouseOutvoid: The pointer left an element of the map. It receives no value.

viewer.onElementClick((element) => {
  if (element.type === 'seat') {
    console.log(`${element.seat.sector_name}, row ${element.seat.row_name}, seat ${element.seat.seat_name}`);
  }
});

Models

Order

The order is the buyer's cart, with the same structure as the order of the Distribution API. These are the fields you will use most; ignore the ones you do not need, as new fields can be added.

idstring: Order identifier. Use it to complete the purchase with the Distribution API.
status.typestring: Status of the order. While the buyer is selecting seats, BASKET.
status.expires_in.datestring: When the reservation expires, in ISO 8601.
itemsarray: Seats and products in the order.
items[].typestring: SEAT or PRODUCT.
items[].allocationobject: Where the seat is: event, session, venue, sector, row, seat and price_type, each with its id and name.
items[].rateobject: Rate of the seat, with its id and name.
items[].priceobject: Price of the item.
items[].promotionsarray: Promotions applied to the item.
price.finalnumber: Total to pay.
price.basenumber: Price of the items, before fees.
price.currencystring: Currency, as an ISO 4217 code.
promotionsarray: Promotions applied to the order.
language_codestring: Language of the order.

ViewElement

An element of the venue map: a link to another view, a seat, a non-numbered zone or an area. type says which one, and the matching property carries its data.

{
  type: 'link' | 'seat' | 'nnz' | 'area';
  link?: ViewLink;
  seat?: ViewSeat;
  nnz?: ViewNnz;
  area?: ViewArea;
}

ViewLinkA link to another view of the venue, such as a zone of a stadium.

{
  view_id: string;
  ref_id: string;
  name: string;
  code?: string;
  availability?: {
    total?: number;
    available?: number;
  };
  price?: {
    min: { base: number; basePromoted?: number; promoName?: string };
    max?: { base: number; basePromoted?: number; promoName?: string };
  };
  pricezones?: { id: number; name: string }[];
}

ViewSeatA numbered seat.

{
  id: number;
  code?: string;
  status?: 'AVAILABLE' | 'OCCUPIED' | 'UNAVAILABLE';
  type?: 'PRIMARY' | 'SECONDARY';
  sector_name?: string;
  row_name?: string;
  row_order?: number;
  seat_name?: string;
  seat_order?: number;
  pricezone?: { id: number; name: string; color: string; description?: string };
  price?: {
    base: number;
    basePromoted?: number;
    total?: number;
    totalPromoted?: number;
    promoName?: string;
    charges?: number;
    original?: number;
  };
  visibility?: 'NORMAL' | 'REDUCED' | 'SIDE' | 'NONE';
  accessibility?: 'NORMAL' | 'DISABILITY';
  rate?: { id?: number; name?: string };
  dynamicPriceName?: string;
}

ViewNnzA non-numbered zone, where buyers choose a number of tickets instead of seats.

{
  id: string;
  code: string;
  order?: number;
  sector_name: string;
  availability?: { type: 'BOUNDED' | 'UNBOUNDED'; total: number; available: number };
  pricezone?: { id: number; name: string; color: string; description?: string };
  price?: {
    base: number;
    basePromoted?: number;
    total?: number;
    totalPromoted?: number;
    promoName?: string;
    charges?: number;
    original?: number;
  };
  visibility?: 'NORMAL' | 'REDUCED' | 'SIDE' | 'NONE';
  accessibility?: 'NORMAL' | 'DISABILITY';
  dynamicPriceName?: string;
}

ViewAreaAn area of the venue.

{
  id: string;
  code: string;
  sector_name: string;
  order?: number;
  availability?: { type: 'BOUNDED' | 'UNBOUNDED'; total: number; available: number };
  pricezone?: { id: number; name: string; color: string; description?: string };
  price?: {
    base: number;
    basePromoted?: number;
    total?: number;
    totalPromoted?: number;
    promoName?: string;
    charges?: number;
    original?: number;
  };
  visibility?: 'NORMAL' | 'REDUCED' | 'SIDE' | 'NONE';
  accessibility?: 'NORMAL' | 'DISABILITY';
}

Widget​

Listening to events​

Core module​

Events​

onOrderChange​

onOrderExpired​

onError​

onDialogStateChange​

Methods​

Viewer module​

Models​

Order​

ViewElement​

Widget