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>

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:

  1. BotProt starts a session. When this visitor needs no check, the run is done right away: BotProt calls final without calling show. Otherwise it calls show and renders the first step. Some steps finish by themselves, without the visitor doing anything; then final follows shortly after show.
  2. Otherwise it fetches the first step.
  3. It renders the step into your element, replacing what was there.
  4. The visitor completes the step, and BotProt fetches the next one, until it has a final token.
  5. At the end, BotProt calls final and resolves, or calls fail and rejects. Note: A step can also send the visitor elsewhere.
  6. 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.

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:

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.

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:

// 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.