Shop skin

The landing page in the look of the OpenTicket shop, so visitors coming from a shop recognise where they are. BotProt runs in the middle of it. The shop is styled per whitelabel, and so is the skin: its stylesheet, name and logo come from the whitelabel you set.

Using it

Load skins/shop.js next to botprot.js (see Loading a skin). Then createBotProtShopSkin loads the skin and resolves to the options for createBotProt. Pass the shop's GUID as the identifier to both, and to the skin the shop's whitelabel and your own show:

<div id="botprot"></div>

<script type="module">
  // OT is window.OpenTicket, once botprot.js and skins/shop.js are loaded.
  const identifier = 'your-shop-guid';

  const skin = await OT.createBotProtShopSkin(identifier, {
      whitelabel: 'openticket.tech',
      show: () => document.getElementById('botprot'),
  });
  const token = await OT.createBotProt(identifier, skin);
</script>

The skin wraps itself around three of your options. They work as they do when you roll your own:

The skin ignores any other options for createBotProt, such as returnUrl. Add those next to the skin, not in it:

const token = await OT.createBotProt(identifier, {
    ...skin,
    returnUrl: '/checkout',
});

Use the playground and test the skin with your own identifier and options.

How it works

From the first call to the token, in order:

  1. createBotProtShopSkin loads what the skin needs, such as stylesheets, shop settings and texts. It waits at most 3 seconds for those before it resolves; anything that arrives later updates the skin in place. Without an identifier, a whitelabel or a show, it fails right away with a config failure: it calls your fail, then rejects.
  2. You pass the result to createBotProt. When BotProt shows its first step, the skin calls your show and renders into its element. BotProt renders each step into the skin, until it has a final token.
  3. Success. The skin removes itself, then calls your final(token), and createBotProt resolves to the token. When BotProt has a token without showing a step, such as after a refresh, your show is never called.
  4. Failure. The skin switches to its failure view, with a "Try again" button that reloads the page, then calls your fail, and createBotProt rejects. When BotProt fails before showing a step, there is no skin to switch: only your fail is called.

What it shows

From top to bottom, centred and at most 30rem wide:

The skin builds this once. Later updates, such as a translation that arrives late or another language, only change the texts around the step. You have no control over the contents of the step coming from BotProt itself, this is by design.

Failures

When BotProt fails, the skin hides the step and shows its own translated failure text with a "Try again" button that reloads the page. It does not show BotProt's message. That still reaches your fail, for logging or your own handling.

Options

Next to show, final and fail (see Using it), the skin takes these options. Only whitelabel is required:

const skin = await OT.createBotProtShopSkin(identifier, {
    whitelabel: 'openticket.tech',
    locale: 'nl_NL',
    show,
});
Option Default
whitelabel Required The shop's whitelabel, by its domain, such as 'openticket.tech'. The skin loads its stylesheet, name and logo.
locale Detected The language, such as 'nl_NL'. Ignored when it is not supported. See Localization.

The other options are URLs, which only differ per environment, such as staging. Production needs none of them.

Option Default
whitelabelsUrlhttps://cdn.openticket.tech/whitelabels/
shopApiUrlhttps://shop.api.openticket.tech/
shopSettingsUrlhttps://tweaks.s3.amazonaws.com/static/
translationsUrlhttps://translations.openticket.tech/combinations/shop/
flagsUrlhttps://cdn.openticket.tech/localization/latest/flags/

Shop settings

The skin reads these fields from the shop's settings: the values set in the dashboard, on the Shop > Styling page.

Field Default
theme light light, dark, or dynamic to follow the visitor's system setting.
style None The shop's colours and other design values. See Styling.

Styling

The skin renders straight into your page, without a shadow DOM, so your page's styles reach it as well. To keep the two apart, everything the skin adds has a data-ot-botprot="v1" attribute and ot-botprot-* prefixed classes. The skin's own CSS only applies under .ot-botprot[data-ot-botprot="v1"]. The v1 changes when the markup does.

The skin's root element is the .ot-botprot inside your element. On it:

To change the skin from your page, override its --ot-* custom properties:

Property Default
--ot-shop-background The whitelabel's secondary background The background of the whole skin.
--ot-shop-color The whitelabel's primary foreground The text colour.
--ot-card-border-radius 0.75rem The corners of the card.
--ot-card-padding 1.25rem The space inside the card.

The skin adds its CSS to the page after yours, so a selector of the same weight loses. Start the selector with your element to increase specificity, here #botprot:

#botprot .ot-botprot {
    --ot-shop-color: red;
    --ot-shop-background: transparent;
}

For a different look altogether, Roll your own skin.

Localization

The skin uses the first of these that is a supported language:

  1. the locale option;
  2. the locale query parameter of the page, such as ?locale=nl_NL;
  3. the language the visitor last chose in the shop;
  4. the browser's languages, in the visitor's order;
  5. en_GB, or else the first supported language.

nl_NL and nl-NL both match nl_NL exactly. A language without a region, such as nl, matches the first supported nl_*.

When the shop settings allow it and there is more than one language, the footer has a language switcher. The visitor's choice is stored in localStorage under @openticket:localization:locale, the same key the shop uses. A visitor who picks Dutch here sees the shop in Dutch as well, and the other way around. The skin sets lang on its root element.

Key Built-in English
botprot.lobby.titleVerification
botprot.lobby.headingComplete a few steps to verify you're human
botprot.lobby.subtitleThis ensures that everyone gets a fair chance to buy tickets.
botprot.lobby.powered_byPowered by
botprot.lobby.locale_switchChoose your language
botprot.lobby.fail.headingSomething went wrong
botprot.lobby.fail.subtitleWe could not verify you. Please try again.
botprot.lobby.fail.retryTry again