Security API Javascript SDK

Security API Javascript SDK by dtect.

Getting Started

The dtect Security API helps you gather valuable insights about your visitors, enhancing the quality of your survey data. This library is responsible for collecting data about the visitor's browser and behavior, send everything to our API and return a Security Result or a Security Token.

Please refer to our official documentation to learn more about the dtect Security API

If you want to use our API, please contact us

Installation

Install package

npm install @dtect/security-sdk-js

or

yarn add @dtect/security-sdk-js

or CDN

NPM Implementation

Read full documentation about implementation on our official docs

1. Start initialize security sdk by calling init function.

• Set your public client id as clientId
• Set your public api key as apiKey

import dtect from "@dtect/security-sdk-js";

dtect.init({
  clientId: "your-public-client-id-from-dashboard", // required
  apiKey: "your-public-api-key-from-dashboard", // required
});

| Prop | Type | Description | | :--------- | :------- | :----------------------------- | | clientId | string | Required. public client id | | apiKey | string | Required. public api key |

2. Use getSecurityResult or getSecurityToken function to check for visitor data

We recommend you to get securityToken from getSecurityToken then consult securityResult.

import dtect from "@dtect/security-sdk-js";

// after init
dtect
  .getSecurityToken({
    projectId: "your-project-id-for-deduplication", // required
  })
  .then((token) => console.log(token));

dtect
  .getSecurityResult({
    projectId: "your-project-id-for-deduplication", // required
    securitySettings: {
      countriesAllowed: ["can"], // only visitors from Canada is allowed
    },
  })
  .then((result) => console.log(result));

| Prop | Type | Description | | :----------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------- | | projectId | string | Required. A unique identifier for your project, study or survey. It allows our system to group visitor data and identify duplicates | | visitorId | string | Id to identify the visitor that is being evaluated | | metaData | object | Any additional information you want to add to each request | | securitySettings | object | Configures security settings. Includes countriesAllowed | | countriesAllowed | string[] | List of countries allowed for your project, survey, or study. |

CDN Implementation

<script>
  const dtectPromise = import(
    "https://unpkg.com/@dtect/security-sdk-js@latest/dist/index.mjs"
  ).then((dtect) =>
    dtect.init({
      clientId: "your-public-client-id-from-dashboard", // required
      apiKey: "your-public-api-key-from-dashboard", // required
    })
  );

  // Use getSecurityToken
  dtectPromise.then((dtect) =>
    dtect
      .getSecurityToken({
        projectId: "your-project-id-for-deduplication", // required
      })
      .then((token) => console.log(token))
  );

  // or use getSecurityResult
  dtectPromise.then((dtect) =>
    dtect
      .getSecurityResult({
        projectId: "your-project-id-for-deduplication", // required
      })
      .then((securityResult) => console.log(securityResult))
  );
</script>

Testing

This package uses Vitest with a JSDOM environment for deterministic unit tests.

• Run the full unit test suite:

yarn test

• Run tests in watch mode while developing:

yarn test:watch

• Run tests with coverage flag

yarn test --coverage

The test configuration is defined in vitest.config.ts, and coverage thresholds are enforced for the src/ directory.

Errors

Read full documentation about errors on our official docs

Access the list of error enums from SecurityAPIError

init()

You will see these errors on console

| Enum | Message | Description | | :------------------------- | :---------------------------------------------- | :-------------------------------------------------------------------------------------- | | MISSING_CREDENTIALS | Missing Public Client ID or Public API Key | Please provide valid Public Client ID and Public API Key when initializing our package. | | INVALID_CREDENTIALS | Invalid Public Client ID or Public API Key | Ensure you are using valid Public Client ID and Public API Key. | | SDK_INIT_ERROR | Internal Server Error during SDK Initialization | An unexpected error occurred on our servers during SDK initialization. | | DUPLICATE_INITIALIZATION | Multiple SDK Initializations Detected | You should initialize our package only once. | | MAINTENANCE_MODE | API Under Maintenance | The API is currently undergoing maintenance and will be available again shortly. |

getSecurityToken()/getSecurityResult()

| Error | Message | Description | | :------------------------------ | :--------------------------------------- | :------------------------------------------------------------------------------------------------- | | NOT_INITIALIZED | SDK Not Initialized | The SDK must be initialized before calling this function. | | INTERNAL_SERVER_ERROR | Internal Server Error during API Request | An unexpected error occurred on our servers during the API request. Check server logs for details. | | FAILED_TO_GET_SECURITY_TOKEN | Failed to Generate Security Token | An error occurred while generating the Security Token. | | FAILED_TO_GET_SECURITY_RESULT | Failed to Retrieve Security Result | An error occurred while retrieving the Security Result. | | MAINTENANCE_MODE | API Under Maintenance | The API is currently undergoing maintenance and will be available again shortly. |

                                      |

NPM implementation with errors

import dtect, { SecurityAPIError } from "@dtect/security-sdk-js";

// after init
dtect
  .getSecurityToken({
    projectId: "your-project-id-for-deduplication", // required
  })
  .then((token) => console.log(token))
  .catch((error) => {
    switch (error.message) {
      case SecurityAPIError.FAILED_TO_GET_SECURITY_TOKEN:
      // log internally
    }
  });

CDN implementation with errors

<script>
  dtectPromise.then((dtect) =>
    dtect
      .getSecurityResult({
        projectId: "your-project-id-for-deduplication", // required
      })
      .then((securityResult) => console.log(securityResult))
      .catch((error) => {
        switch(error.message) {
          case dtect.SecurityAPIError.FAILED_TO_GET_SECURITY_RESULT:
            // log internally
        }
      })
  );
</script>

Contact

dtect - Contact us - [email protected]