Skip to main content

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'),
final: () => document.getElementById('botprot').remove(),
});
const token = await OT.createBotProt(identifier, skin);
</script>

The skin wraps itself around three of your options. They behave just like when you roll your own:

  • show is required. It is called when BotProt shows its first step, and must return an element in the document. The skin replaces its content, so a placeholder can stay there until then. When and how the element appears on your page is up to you. show is also called for steps that finish by themselves, so the skin can show for a moment on a shop without steps the visitor solves. Reveal the element late, as in The element.
  • final(token) is called after the skin has removed its content. Your element stays in the page, empty: remove or hide it here.
  • fail(message, code, error) is called after the skin has switched to its failure view.

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. It rejects right away without an identifier, a whitelabel or a show.
  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. Your element stays; removing it is up to you. 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:

  • A title, "Verification".
  • A card with:
    • the shop heading. For a shop that sells a single event, that is a date block, the event's name, its start and end, and its location. For any other shop, a shop icon and the shop's name. When neither is known, the heading is left out;
    • a heading and a subtitle that tell the visitor what is going on;
    • the BotProt step, at most 400px wide.
  • A footer with "Powered by" with a logo and the language switcher.

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,
});
OptionDefault
whitelabelRequiredThe shop's whitelabel, by its domain, such as 'openticket.tech'. The skin loads its stylesheet, name and logo.
localeDetectedThe language, such as 'nl_NL'. Ignored when it is not supported. See Localization.

Shop settings​

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

FieldDefault
themelightlight, dark, or dynamic to follow the visitor's system setting.
styleNoneThe 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:

  • is-light or is-dark, from the theme shop setting. A dynamic theme picks one from the visitor's system setting whenever the skin renders.
  • The style shop setting, as custom properties in its style attribute. Nested values become one property, so { "color": { "brand": "#e00" } } becomes --ot-color-brand: #e00. Inline, these win over any CSS on your page.

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

PropertyDefault
--ot-shop-backgroundThe whitelabel's secondary backgroundThe background of the whole skin.
--ot-shop-colorThe whitelabel's primary foregroundThe text colour.
--ot-card-border-radius0.75remThe corners of the card.
--ot-card-padding1.25remThe 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.

KeyBuilt-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