JavaScript 的 Dodgeball 客户端信任 SDK

目录

• 目的
• 先决条件
• 相关
• 安装
• 使用量
• API 密码

目的

道奇球 使开发人员能够从他们的应用程序代码中解开安全逻辑. 这有几个好处,包括:

• 能够切换和比较诸如欺诈引擎、外交部、KYC和机器人预防等安保服务.
• 对新的攻击作出更迅速的反应。 当威胁演化和发现新的弱点时,您的应用程序的安全逻辑可以在不改变一行代码的情况下被更新.
• 有能力在注重产品开发的同时,为未来的安全改进提供替代条件.
• 一个将所有应用程序安全逻辑 在一个地方可视化的方法.

用于JavaScript的道奇球客户端信托SDK使得与道奇球API的整合变得容易,由道奇球队维护.

先决条件

您需要从您的地址获取应用程序的 API 密钥 Dodgeball 开发者中心。 。 。 .

相关

看看这个 Dodgeball 信托服务器 SDK 如何将道奇球整合到应用程序的后端.

安装

使用 npm 安装 Dodgeball 模块:

npm install @dodgeball/trust-sdk-client

或者,使用 yarn数字 :

yarn add @dodgeball/trust-sdk-client

使用量

反应应用程序

道奇球客户端SDK来了 useDodgeball 钩子可以用于所有组件中. 您首先需要用您的公共 API 密钥初始化 SDK, 可在 开发者设置 页 次 只需在应用程序首次装入时完成一次,如下例所示:

import { useDodgeball } from "@dodgeball/trust-sdk-client";
import { useEffect, useSelector } from "react";
import { selectCurrentUser, selectCurrentSession } from "./selectors";

export default function MyApp() {
  const dodgeball = useDodgeball('public-api-key...');
  const currentSession = useSelector(selectCurrentSession);
  const currentUser = useSelector(selectCurrentUser);

  useEffect(() => {
    /* 
      When you know the ID of the currently logged-in user, 
      pass it along with a session ID to dodgeball.track():
    */
    dodgeball.track(currentSession?.id, currentUser?.id);
  }, [currentSession?.id, currentUser?.id]);

  return (
    <div>
      <h1>My App</h1>
      <MyComponent/>
    </div>
  );
}

下面是一个简单的例子,说明在发出命令时进行核查的组件:

import { useDodgeball } from "@dodgeball/trust-sdk-client";
import { useState, useEffect } from "react";
import axios from "axios";

export default function MyComponent() {
  const dodgeball = useDodgeball(); // Once initialized, you can omit the public API key

  const [isPlacingOrder, setIsPlacingOrder] = useState(false);
  const [isOrderPlaced, setIsOrderPlaced] = useState(false);
  const [isOrderDenied, setIsOrderDenied] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    setIsPlacingOrder(false);
  }, [isOrderPlaced, isOrderDenied])

  const placeOrder = async (order, previousVerification = null) => {
    const sourceToken = await dodgeball.getSourceToken();

    const endpointResponse = await axios.post("/api/orders", { order }, {
      headers: {
        "x-dodgeball-source-token": sourceToken, // Pass the source token to your API
        "x-dodgeball-verification-id": previousVerificationId // If a previous verification was performed, pass it along to your API
      }
    });

    dodgeball.handleVerification(endpointResponse.data.verification, {
      onVerified: async (verification) => {
        // If an additional check was performed and the request is approved, simply pass the verification ID in to your API
        await placeOrder(order, verification.id);
      },
      onApproved: async () => {
        // If no additional check was required, update the view to show that the order was placed
        setIsOrderPlaced(true);
      },
      onDenied: async (verification) => {
        // If the action was denied, update the view to show the rejection
        setIsOrderDenied(true);
      },
      onError: async (error) => {
        // If there was an error performing the verification, display it
        setError(error); // Usage Note: If the user cancels the verification, error.errorType = "CANCELLED"
        setIsPlacingOrder(false);
      }
    });
  }

  const onPlaceOrderClick = async () => {
    setIsPlacingOrder(true);

    const order = {} // Fill in with whatever data your API expects
    await placeOrder(order);
  }

  return (
    <div>
      <h2>My Component</h2>
      <p>
        This component is using the Dodgeball Client SDK.
      </p>
      {isOrderPlaced ? (
        <p>
          Your order was placed!
        </p>
      ) : (
        <p>
          {isOrderDenied && <span>Order was denied. Contact support.</span>}

          <button onClick={onPlaceOrderClick} disabled={isPlacingOrder || isOrderDenied}>
            {isPlacingOrder ? 'Placing Order...' : 'Place Order'}
          </button>

          {error && <div>{error}</div>}
        </p>
      )}
    </div>
  );
}

非反应应用程序

道奇球客户端 SDK 输出 a Dodgeball 类,可以传递公共 API 密钥和可选配置对象。 见 构造器 章节,以获取关于配置的更多信息。 您可以在网站上找到您的公共 API 密钥 开发者设置 页 次.

您首先需要用您的公共 API 密钥初始化 SDK, 可在 开发者设置 页 次 只需在SDK首次装入时进行一次,如下例所示:

import { Dodgeball } from "@dodgeball/trust-sdk-client";

const dodgeball = new Dodgeball('public-api-key...'); // Do this once when your application first loads

const sourceToken = await dodgeball.getSourceToken();

当您知道当前登录用户的身份时,请拨 dodgeball.track()。 。 。 .

// As soon as you have a session ID, pass it to dodgeball.track()
const onSession = (currentSession) => {
  dodgeball.track(currentSession?.id);
}

// When you know the ID of the currently logged-in user, pass it along with a session ID to dodgeball.track()
const onLogin = (currentSession, currentUser) => {
  dodgeball.track(currentSession?.id, currentUser?.id);
}

稍后,当你想核实一个访客被允许执行某项行动时,请打电话 dodgeball.getSourceToken() 以获得代表此设备的标志。 传回 sourceToken 给你的API。 一旦你的API返回回复,通过 verification 改为 dodgeball.handleVerification 以及一些回调功能:

const placeOrder = async (order, previousVerificationId = null) => {
  const sourceToken = await dodgeball.getSourceToken();

  const endpointResponse = await axios.post("/api/orders", { order }, {
    headers: {
      "x-dodgeball-source-token": sourceToken, // Pass the source token to your API
      "x-dodgeball-verification-id": previousVerificationId // If a previous verification was performed, pass it along to your API
    }
  });

  dodgeball.handleVerification(endpointResponse.data.verification, {
    onVerified: async (verification) => {
      // If an additional check was performed and the request is approved, simply pass the verification ID in to your API
      await placeOrder(order, verification.id);
    },
    onApproved: async () => {
      // If no additional check was required, update the view to show that the order was placed
      setIsOrderPlaced(true);
    },
    onDenied: async (verification) => {
      // If the action was denied, update the view to show the rejection
      setIsOrderDenied(true);
    },
    onError: async (error) => {
      // If there was an error performing the verification, display it
      setError(error); // Usage Note: If the user cancels the verification, error.errorType = "CANCELLED"
      setIsPlacingOrder(false);
    }
  });
}

通过 CDN 装入

Dodgeball客户端 SDK 也可以通过 CDN 在这个url 获取:

https://www.unpkg.com/@dodgeball/trust-sdk-client@latest/dist/umd/index.js

要装入 HTML 文档 :

<!doctype html>
<html>
  <head>
    <title>My Application</title>
    <script type="text/javascript" async defer src="https://www.unpkg.com/@dodgeball/trust-sdk-client@latest/dist/umd/index.js" onload="onDodgeballLoaded()"></script>
    <script>
      async function onDodgeballLoaded() {
        const dodgeball = new Dodgeball('public-api-key...'); // Do this once when your application first loads

        // At some point later, when you are ready to call your API:
        const placeOrder = async (order, previousVerificationId = null) => {
          const sourceToken = await dodgeball.getSourceToken();

          const endpointResponse = await axios.post("/api/orders", { order }, {
            headers: {
              "x-dodgeball-source-token": sourceToken, // Pass the source token to your API
              "x-dodgeball-verification-id": previousVerificationId // If a previous verification was performed, pass it along to your API
            }
          });

          dodgeball.handleVerification(endpointResponse.data.verification, {
            onVerified: async (verification) => {
              // If an additional check was performed and the request is approved, simply pass the verification ID in to your API
              await placeOrder(order, verification.id);
            },
            onApproved: async () => {
              // If no additional check was required, update the view to show that the order was placed
              setIsOrderPlaced(true);
            },
            onDenied: async (verification) => {
              // If the action was denied, update the view to show the rejection
              setIsOrderDenied(true);
            },
            onError: async (error) => {
              // If there was an error performing the verification, display it
              setError(error); // Usage Note: If the user cancels the verification, error.errorType = "CANCELLED"
              setIsPlacingOrder(false);
            }
          });
        }

        await placeOrder({
          cart: [],
          paymentMethod: {},
          // ... any other data relevant to your API
        });
      }
    </script>
  </head>
  <body>
  Your application's content...
  </body>
</html>

API 密码

配置

软件包需要公开的 API 密钥作为构建器的第一个参数.

const dodgeball = new Dodgeball("public-api-key...");

可选的,您可以在多个配置选项中传递到构建器:

const dodgeball = new Dodgeball("public-api-key...", {
  // Optional configuration
  apiVersion: "v1",
  apiUrl: "https://api.dodgeballhq.com",
  logLevel: "ERROR",
  disableCookies: false,
  isEnabled: true
});

跟踪用户

这个 track 方法用于初始化已知的任何会话和用户信息。 此方法应在您有会话ID和可选用户ID后立即调用. 如果没有用户ID,可以通过 null 或省略第二个论据.

dodgeball.track(sessionId, userId);

获取源选项

这个 getSourceToken 方法返回表示当前设备上活动期间的符号。 当您想要验证一个用户被允许执行动作时, 此符号应该传递到您的 API 。 源代码在1小时后过期,由SDK自动刷新.

const sourceToken = await dodgeball.getSourceToken();

如果Aync/Await不是你的东西, 你可以引用 getSourceToken 将调用源代码作为参数的调用函数:

dodgeball.getSourceToken((sourceToken) => {});

刷新源代码

这个 refreshSourceToken 方法刷新当前源代码。 如果您想要在符号过期前刷新该符号, 如用户登录退出时, 此选项将有所帮助 .

const newSourceToken = await dodgeball.refreshSourceToken();

或者,你可以援引 refreshSourceToken 用新源符号调用回调函数作为参数的方法:

dodgeball.refreshSourceToken((newSourceToken) => {});

处理核查

这个 handleVerification 用于处理来自您的 API 的校验响应。 此方法应在您的 API 返回包含验证对象的响应后调用 。 核查对象载有关于已进行的核查的资料。 这个 handleVerification 方法取一个核查对象和一个包含若干回调函数的配置对象。 这个 handleVerification 方法将根据核查反应调用适当的回调功能.

dodgeball.handleVerification(
  verification, // This is the verification object returned from your API
  {
    onVerified: async (verification) => {
      // If an additional check was performed and the request is approved, the requested action has not yet been taken on your API. To do so, simply retry the request, being sure to pass the verification.id to your API. On your API the verification.id should be passed as the useVerificationId argument to dodgeball.checkpoint()
    },
    onApproved: async () => {
      // If no additional check was required, the requested action was approved and taken on your API, so you should update the view to show that the action was taken
    },
    onDenied: async (verification) => {
      // If the action was denied, update the view to show the rejection
    },
    onPending: async (verification) => {
      // (Optional) This callback will be called if the verification is still processing. This is useful to inform the user that their request is still being processed.
    },
    onBlocked: async (verification) => {
      // (Optional) This callback will be called if the verification requires additional information from the user before it can be processed (e.g. the user needs to complete an MFA challenge or IDV flow)
    },
    onError: async (verificationError) => {
      // (Optional) If there was an error performing the verification, this callback will be called with an error object. If the user cancels the verification, error.errorType = "CANCELLED"
    }
  },
  {
    // Optional configuration
    maxDuration: 24 * 60 * 60 * 1000, // 24 hours
  }
);