@dtect/security-sdk-react NPM

Security SDK React

Security API SDK for React by dtect.

<li>
  <a href="#getting-started">Getting Started</a>
  <ul>
    <li><a href="#installation">Installation</a></li>
  </ul>
</li>
<li>
  <a href="#implementation">Implementation</a>
</li>
<li><a href="#license">License</a></li>
<li><a href="#contact">Contact</a></li>

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 read full documentation on security api

If you want to use our API, please contact us

Installation

Install package

npm install @dtect/security-sdk-react

yarn add @dtect/security-sdk-react

Implementation

Read full documentation about implementation on our official docs

1. Wrap your application (or component) with `<SecurityAPIProvider>`.

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

Read more about keys on our official docs

// index.ts or app.tsx
import React from "react";
import { SecurityAPIProvider } from "@dtect/security-sdk-react";
import App from "./App";
import Form from "./src/form";

function MyPage() {
  return (
    <SecurityAPIProvider
      clientId={"your-public-client-id-from-dashboard"} // required
      apiKey={"your-public-api-key-from-dashboard"} // required
    >
      <Form />
    </SecurityAPIProvider>
  );
}

Prop	Type	Description
`clientId`	`string`	Required. public client id
`apiKey`	`string`	Required. public api key

2. Use `useSecurityApi` hook inside your component to check for visitor data

useSecurityApi has getSecurityToken and getSecurityResult functions to validate visitor. We recommend you to get securityToken from getSecurityToken then consult securityResult.

// src/form.ts
import React from "react";
import { useSecurityApi } from "@dtect/security-sdk-react";
import App from "./App";

function Form() {
  const { getSecurityToken } = useSecurityApi();

  const handleSubmit = async () => {
    const response = await getSecurityToken({
      projectId: "your-project-id-for-deduplication", // required
      visitorId: "your-visitor-id",
      securitySettings: {
        countriesAllowed: ["usa", "can"],
      },
    });

    if (response?.securityToken) {
      // send securityToken to your backend server then consult dtect's securityResult API to get result with security
    }
  };

  return (
    <form>
      {/* ...some inputs */}
      <button type="submit" onClick={handleSubmit}>
        Submit
      </button>
    </form>
  );
}

export default Form;

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.

Errors

Read full documentation about errors on our official docs

Access the list of error enums from SecurityAPIError

SecurityAPIProvider

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.

// src/form.ts
import React from "react";
import { useSecurityApi, SecurityAPIError } from "@dtect/security-sdk-react";
import App from "./App";

function Form() {
  const { getSecurityToken } = useSecurityApi();

  const handleSubmit = async () => {
    try {
      const response = await getSecurityToken({
        projectId: "your-project-id-for-deduplication", // required
        visitorId: "your-visitor-id",
        securitySettings: {
          countriesAllowed: ["usa", "can"],
        },
      });

      if (response?.securityToken) {
        // send securityToken to your backend server then consult dtect's securityResult API to get result with security
      }
    } catch (error) {
      switch (error.message) {
        case SecurityAPIError.FAILED_TO_GET_SECURITY_TOKEN:
        // log internally
      }
    }
  };

  return (
    <form>
      {/* ...some inputs */}
      <button type="submit" onClick={handleSubmit}>
        Submit
      </button>
    </form>
  );
}

export default Form;