NPM Module

Install

1

npm i @botbye/client

1

yarn add @botbye/client

Configuration

Call initChallenges with your project client-key:

1
2
3
4
5
6

import { initChallenges } from "@botbye/client";

const runChallenge = await initChallenges({
  // Use your client-key
  clientKey: "00000000-0000-0000-0000-000000000000"
});

Usage

Generate token using runChallenge and send this token in any convenient way to the backend. For example in x-botbye-token header:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import { runChallenge } from "@botbye/client";

const botByeToken = await runChallenge();

fetch(
  'https://domain.com',
  {
    method: "POST",
    headers: {
         // "x-botbye-token" is an example — send this token in any convenient way.
        "x-botbye-token": botByeToken
    }
  }
)

Challenge runner

Package also exports runChallenge function. Before call it, make sure that initChallenges was called earlier.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import { initChallenges, runChallenge } from "@botbye/client";

initChallenges({
  // Use your client-key
  clientKey: "00000000-0000-0000-0000-000000000000"
});

...

const botByeToken = await runChallenge()

fetch(
  'https://domain.com',
  {
      method: "POST",
      headers: {
          "x-botbye-token": botByeToken
      }
  }
)

User identification

Call setUserId after a successful authentication to associate the current session with a user. This helps BotBye detect multi-account abuse.

1
2
3
4
5
6
7

import { setUserId } from "@botbye/client";

const response = await login({ username, password });

if (response.userId) {
  setUserId(response.userId);
}

Sessions

BotBye! records a timeline of user actions on your site — page changes and clicks — that operators can review in the admin panel. For a click, BotBye! stores a short text label read from the clicked element so the action stays recognizable.

Hiding personal data

If an element can show personal data — a user name, email, account or card number, and so on — mark it with the data-bb-not-track attribute to keep that text out of the recording. The attribute works on the element itself or on any of its ancestors, so wrapping a region protects everything inside it.

Give the attribute a value to record that value instead of the element's real text:

1

<button data-bb-not-track="Account menu">John Doe — john@example.com</button>

Leave the attribute empty to record no text at all — only the click position is stored:

1
2
3

<div data-bb-not-track>
  <!-- clicks inside are recorded without any element text -->
</div>

Disabling Sessions

Sessions run by default. To turn them off completely, add withoutSessions: true to the options you pass when you initialize BotBye! — initChallenges, or the plugin / component options in Vue:

1
2
3
4

initChallenges({
  clientKey: "00000000-0000-0000-0000-000000000000",
  withoutSessions: true
});

Click tags

A click tag ties a token to a real user click on a specific element, so a token for a sensitive action can only be produced after the visitor actually clicked it — not by a script calling runChallenge on its own.

Mark the element with data-bb-tag (only genuine clicks count):

1

<button data-bb-tag="login">Log in</button>

Pass the same name as clickTag when you generate the token. Do it right after the click — the tag is only remembered for a short time:

1

const botByeToken = await runChallenge({ clickTag: "login" });

BotBye! then embeds the tag in the token, so you can add an admin rule that declines requests missing it — for example, decline any login request whose token is not tagged `login`.