Skip to main content

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. The message is 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 skinShop skinRoll your own
Scriptskins/reference.jsskins/shop.jsNone
IdentifierThe shop's GUIDThe shop's GUIDThe shop's GUID
Required optionsNonewhitelabel, showNone
Optional optionsNonefinal, fail, localeshow, final, fail
Renders inA dialog over the pageYour elementYour element
Looks likeA plain white dialogThe shop, in the whitelabel's styleYour page
On failureBotProt's message, in the dialogIts own failure text and a "Try again" buttonWhatever your fail does
On finalCloses and removes the dialogRemoves its content. Your element stays: remove it in finalYour 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.