Introduction
BotProt renders its steps into an element on your page. A skin decides where that element is, and what visitors see around it while BotProt verifies them, when it succeeds and when it fails.
What a skin is
A BotProt step on its own is a bare task or loading state, without context. A skin puts it somewhere on your page and handles the end of the check. It cleans up after a token, and tells the visitor when something went wrong.
A barebones skin has a show() call that provides an element to render its steps into. Without one, BotProt
renders into a plain element at the bottom of the page. Some other options of
createBotProt are:
final(token)runs once the visitor is verified.fail(message, code, error)runs when BotProt cannot finish. Themessageis safe to show to visitors as-is.
There are three ways to get these options:
// OT is window.OpenTicket, once botprot.js and the skin are loaded (see Loading a skin).
// Reference skin: BotProt in a dialog, nothing to set up.
const token = await OT.createBotProt(identifier, OT.createBotProtReferenceSkin());
// Shop skin: the landing page in the look of the shop, in your element.
const skin = await OT.createBotProtShopSkin(identifier, { whitelabel: 'openticket.tech', show, final, fail });
const token = await OT.createBotProt(identifier, skin);
// Roll your own: no skin, your own element and callbacks.
const token = await OT.createBotProt(identifier, { show, final, fail });
Choosing a skin
| Reference skin | Shop skin | Roll your own | |
|---|---|---|---|
| Script | skins/reference.js | skins/shop.js | None |
| Identifier | The shop's GUID | The shop's GUID | The shop's GUID |
| Required options | None | whitelabel, show | None |
| Optional options | None | final, fail, locale | show, final, fail |
| Renders in | A dialog over the page | Your element | Your element |
| Looks like | A plain white dialog | The shop, in the whitelabel's style | Your page |
| On failure | BotProt's message, in the dialog | Its own failure text and a "Try again" button | Whatever your fail does |
| On final | Closes and removes the dialog | Removes its content. Your element stays: remove it in final | Your element stays: remove it in final |
returnUrl, redirect and the storage options work the same with all three. Pass them to createBotProt next to
the skin's options.
- You only need the token, and the shop has no steps the visitor solves. Use no skin and no options, see the smallest integration.
- You want BotProt working without any effort. Use the reference skin.
- Your visitors come from a shop. Use the shop skin, so they recognise where they are.
- BotProt has to fit into your own design. Roll your own. You pick the element, write the texts and decide what happens after a token or a failure.
Loading a skin
botprot.js only adds createBotProt. Each skin is a script of its own, next to botprot.js at skins/{name}.js, so
a page only loads the skin it uses. Its types are next to it, at skins/{name}.d.ts.
Roll your own needs no skin script at all.
A skin adds its function to window.OpenTicket, named createBotProt{Name}Skin, and then fires
BotProt:Skin:{name}:Ready on the document, with the global as its detail. That works like
BotProt:Client:Ready for botprot.js. The scripts can load in any order, so wait for both:
<script src="https://lobby.openticket.tech/botprot.js"></script>
<script src="https://lobby.openticket.tech/skins/reference.js"></script>
<script>
// Resolves with window.OpenTicket once it has `member`, now or when `event` fires.
function ready(member, event) {
return new Promise((resolve) => {
if (window.OpenTicket?.[member]) {
resolve(window.OpenTicket);
} else {
document.addEventListener(event, (e) => resolve(e.detail), { once: true });
}
});
}
Promise.all([
ready('createBotProt', 'BotProt:Client:Ready'),
ready('createBotProtReferenceSkin', 'BotProt:Skin:reference:Ready'),
]).then(async ([OT]) => {
const token = await OT.createBotProt('your-shop-guid', OT.createBotProtReferenceSkin());
// Verified: continue with the token.
});
</script>
Load each skin once. A skin's function cannot be redefined, so a second copy of the same script throws an error.
Reference skin
If you want the most basic BotProt on your page. Load skins/reference.js next to botprot.js.
createBotProtReferenceSkin() takes no arguments and returns the options createBotProt needs:
const token = await OT.createBotProt(identifier, OT.createBotProtReferenceSkin());
// Verified: continue with the token.
What it does:
- It opens a modal dialog over your page right away, and BotProt renders its steps inside it. Call it at the moment you start BotProt, not before.
- The dialog opens even when the visitor has nothing to solve, so it can show for a moment and close again. To avoid that, roll your own and reveal the element late.
- Visitors cannot dismiss the dialog with Esc.
- Once the visitor is verified, it closes the dialog and removes it from the page.
- When BotProt fails, it replaces the dialog's content with BotProt's message. The dialog stays open, so visitors need to reload the page to try again.
- It loads nothing else.
The dialog is a <dialog class="ot-botprot-dialog">, at most 400px wide, white, rounded and with a shadow. BotProt
renders into #ot-botprot-dialog__content inside it. The skin's styles have zero specificity, so any rule on your
page for .ot-botprot-dialog wins:
/* Any selector beats the skin's own styles. */
.ot-botprot-dialog {
width: min(560px, calc(100vw - 2rem));
border-radius: 0;
font-family: inherit;
}
If you want anything else custom, you can always opt to roll your own.