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:
-
showis 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. final(token)is called after the skin has removed itself.-
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:
-
createBotProtShopSkinloads 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 ashow, it fails right away with aconfigfailure: it calls yourfail, then rejects. -
You pass the result to
createBotProt. When BotProt shows its first step, the skin calls yourshowand renders into its element. BotProt renders each step into the skin, until it has a final token. -
Success. The skin removes itself, then calls your
final(token), andcreateBotProtresolves to the token. When BotProt has a token without showing a step, such as after a refresh, yourshowis never called. -
Failure. The skin switches to its failure view, with a "Try again" button that
reloads the page, then calls your
fail, andcreateBotProtrejects. When BotProt fails before showing a step, there is no skin to switch: only yourfailis 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,
});
| 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 |
|---|---|
whitelabelsUrl | https://cdn.openticket.tech/whitelabels/ |
shopApiUrl | https://shop.api.openticket.tech/ |
shopSettingsUrl | https://tweaks.s3.amazonaws.com/static/ |
translationsUrl | https://translations.openticket.tech/combinations/shop/ |
flagsUrl | https://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:
-
is-lightoris-dark, from thethemeshop setting. Adynamictheme picks one from the visitor's system setting whenever the skin renders. -
The
styleshop setting, as custom properties in itsstyleattribute. 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:
| 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:
- the
localeoption; - the
localequery parameter of the page, such as?locale=nl_NL; - the language the visitor last chose in the shop;
- the browser's languages, in the visitor's order;
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.title | Verification |
botprot.lobby.heading | Complete a few steps to verify you're human |
botprot.lobby.subtitle | This ensures that everyone gets a fair chance to buy tickets. |
botprot.lobby.powered_by | Powered by |
botprot.lobby.locale_switch | Choose your language |
botprot.lobby.fail.heading | Something went wrong |
botprot.lobby.fail.subtitle | We could not verify you. Please try again. |
botprot.lobby.fail.retry | Try again |