Roll your own
No skin at all. You pass your own element and callbacks to createBotProt, and
BotProt fits into your page the way you design it.
Example
<div id="botprot">Loading…</div>
<script type="module">
// OT is window.OpenTicket, once botprot.js is ready (see Usage).
const container = document.getElementById('botprot');
const token = await OT.createBotProt(identifier, {
show: () => container,
final: () => {
container.remove();
},
fail: (message) => {
container.textContent = message;
},
});
</script>
-
showreturns the element BotProt renders its steps into. It must be in the document. -
finalruns once the visitor is verified. BotProt is done with the element, and leaves cleaning it up to you. -
failruns when BotProt cannot finish. Itsmessageis safe to show to visitors as-is.
The identifier must be a non-empty string; anything else fails right away, with the code
'config'. So does a returnUrl that is not a valid URL (see
Redirects).
All options
Rolling your own starts with show; all other options are optional.
| Option | When | Default |
|---|---|---|
show() |
Once, at the first step | Provide your own |
final(token) |
Once, when the visitor is verified | Nothing |
fail(message, code, error) |
Once, when BotProt cannot finish | Nothing |
redirect(url) |
When a step sends the visitor elsewhere | window.location.assign(url) |
returnUrl |
At the start | The current page |
retrieveToken(key),
storeToken(key, value, expiresAt)
|
During the run, to keep it across a refresh or a redirect | localStorage |
createBotProt also resolves to the token, and rejects with the same error
fail gets. When you await it, final and
fail are only needed for what happens to the element.
The playground shows the documentation of each option, as
it is in botprot.d.ts, and lets you try them.
How a run goes
One call to createBotProt is one run:
-
BotProt starts a session. When this visitor needs no check, the run is done right away: BotProt
calls final without calling
show. Otherwise it callsshowand renders the first step. Some steps finish by themselves, without the visitor doing anything; thenfinalfollows shortly aftershow. - Otherwise it fetches the first step.
- It renders the step into your element, replacing what was there.
- The visitor completes the step, and BotProt fetches the next one, until it has a final token.
-
At the end, BotProt calls
finaland resolves, or callsfailand rejects. Note: A step can also send the visitor elsewhere. - The final token is what the run is for: send it along with your requests to our API, such as the Shop API.
Only one run is active per page. Calling createBotProt again cancels the
previous run, which then rejects with an AbortError.
BotProt calls your callbacks but never depends on them. An error thrown in final
or fail is logged in the console, and the run ends as it would have.
The element
BotProt calls show() once, when it has the first step to render. Your element can
wait until then, as in the dialog example below.
-
It must return an
HTMLElementthat is in the document. A step's scripts look up their elements in the document. Anything else, or ashow()that throws, fails. - Each step replaces all children of the element. Placeholder content, such as "Loading…", disappears at the first step.
-
BotProt never removes your element. Each step replaces its content, and after the run BotProt leaves it as is. Tidying it up is up to the implementer. Achieveable with
finalandfail.
Some steps finish by themselves, without the visitor doing anything. To keep such a step from flashing by, keep the element hidden at first, and reveal it only when the step takes longer:
const container = document.getElementById('botprot');
// The 2.5x median duration of a transient final.
const NOMINAL_DELAY_MS = 800;
container.style.visibility = 'hidden';
let reveal;
const token = await OT.createBotProt(identifier, {
show: () => {
// Hidden, but still laid out, so the step renders into it as usual.
reveal = setTimeout(() => {
container.style.visibility = '';
}, NOMINAL_DELAY_MS);
return container;
},
final: () => {
clearTimeout(reveal);
container.remove();
},
fail: (message) => {
clearTimeout(reveal);
container.style.visibility = '';
container.textContent = message;
},
});
Hide it with visibility or opacity, not display: none: an
element that is not displayed is not rendered at all, so a step's scripts may not work, for example
because the step's size is 0, or its iframe does not load. The 1.5 seconds is an example; pick a
delay a little longer than such a step usually takes.
Success
BotProt calls final(token) once, right before createBotProt resolves
to the same token. Tidy up the element there, for example by removing it. Then continue with
the token, such as sending it along with the order.
Failures
fail(message, code, error) runs once, right before createBotProt
rejects with the same error:
messageis written for visitors and safe to show as-is.codetells failures apart, if you want to handle some differently.-
erroris for developers:error.messagesays what went wrong, for logs and error reports.
| Code | Means | Message | Retry |
|---|---|---|---|
config |
This page is set up incorrectly, such as no identifier, an invalid returnUrl, or a show that returns nothing |
Something went wrong during verification. Please try again. | After fixing the page |
network |
BotProt could not be reached, or took longer than 15 seconds | We could not reach the verification service. Please check your connection and try again. | Yes |
status |
BotProt responded with an error status | Something went wrong during verification. Please try again. | Yes |
response |
BotProt responded with something unusable | Something went wrong during verification. Please try again. | Yes |
rejected |
BotProt concluded the visitor is unwanted | We could not verify that you are not a bot. | No |
limit |
The visitor used up their attempts | Too many attempts. Please try again later. | Later |
unexpected |
Anything else | Something went wrong during verification. Please try again. | Yes |
To retry, call createBotProt again. Each call starts a fresh run:
const container = document.getElementById('botprot');
function start() {
OT.createBotProt(identifier, {
show: () => container,
// A retry can need no check at all, and then never calls show: clear the failure here.
final: () => container.replaceChildren(),
fail: (message, code) => {
container.replaceChildren(message);
// Retrying does not help when BotProt concluded the visitor is a bot.
if (code !== 'rejected') {
const retry = document.createElement('button');
retry.type = 'button';
retry.textContent = 'Try again';
retry.addEventListener('click', start);
container.append(retry);
}
},
}).then((token) => {
// Verified: continue with the token.
}, () => {
// fail already told the visitor, and the error is in the console.
});
}
start();
Redirects
A step can send the visitor to another site, such as a waiting room. BotProt then calls
redirect(url), which defaults to window.location.assign(url).
Pass your own to save state first, or to leave the page another way. A redirect
that throws fails with 'config'.
After a redirect, createBotProt neither resolves nor rejects: it waits while the
page goes away.
When the visitor is done there, BotProt sends them back to returnUrl.
By default, that is the page the run started on (window.location.href). A
relative URL resolves against the current page. A value that is not a valid URL fails right
away with 'config'.
OT.createBotProt(identifier, {
show: () => container,
// Save what the visitor would lose, then leave the page.
redirect: (url) => {
saveBasket();
window.location.assign(url);
},
// Come back to the checkout, not to the page BotProt started on.
returnUrl: '/checkout',
});
BotProt adds a botprot_next parameter to the return URL. On that page, call
createBotProt again with the same identifier and options, and the run automatically
continues where it left off.
Refresh and persistence
BotProt stores how far the run got, per identifier, until its token expires. When the visitor
refreshes the page or comes back from a redirect, calling createBotProt again with
the same identifier continues from there, instead of starting over.
-
By default, BotProt uses
localStorage, underBotProt:Token:Last:{identifier}andBotProt:Token:Queries:{identifier}. -
To store it elsewhere, such as in a cookie, pass both
retrieveToken(key)andstoreToken(key, value, expiresAt). One without the other is not used. An emptyvaluemeans forget the key, andretrieveTokenreturnsnullwhen nothing is stored. -
A failure forgets the stored run, so trying again starts over. The exception is
network: then trying again continues where the visitor was. - A final token stays stored until it expires, and a new run for the same identifier resolves to it right away. BotProt only forgets it when it starts again after it has expired. On a shared device, such as a point of sale, or after a successful order, clear it yourself.
From the reference skin
The reference skin is a good start for a skin of your own. This is the same idea in plain JavaScript, ready to copy and change. The example below improves on the reference skin in two ways:
- The dialog opens in
show(), so it never appears when no check is needed. - A failure shows the message with a "Try again" button.
// A dialog over the page, like the reference skin, that can retry.
function createDialogSkin() {
let dialog;
function open() {
if (!dialog) {
dialog = document.createElement('dialog');
// Esc does not close it: the visitor has to finish the check.
dialog.addEventListener('cancel', (event) => event.preventDefault());
document.body.append(dialog);
dialog.showModal();
}
return dialog;
}
function close() {
dialog?.close();
dialog?.remove();
}
return {
// Only called at the first step: no dialog when no check is needed.
show: open,
final: close,
fail: (message) => {
const retry = document.createElement('button');
retry.type = 'button';
retry.textContent = 'Try again';
retry.addEventListener('click', () => window.location.reload());
// BotProt can fail before the first step, when there is no dialog yet.
open().replaceChildren(message, retry);
},
};
}
const token = await OT.createBotProt(identifier, createDialogSkin());
Debugging
While you build, set OpenTicket.debug = true in the console. BotProt
then logs each step of the run. Failures are always logged with console.error,
prefixed with [@openticket/botprot-lobby:…] and the part that failed.