SDK 嵌入或托管链接：选择如何集成验证

嵌入 SDK 当验证发生在您的产品内部，也就是用户在其会话中访问产品时，则发送托管链接。当验证发生在产品外部时，例如贷款专员催促文件、商家通过电子邮件完成入驻流程、客户在注册数月后被要求重新验证身份等，则发送托管链接。这就是全部决策规则，大多数团队最终都需要这两种方式。

这种方案之所以成本低廉，是因为它只需构建一次，即可作为已发布的流程使用。嵌入程序会根据 ID 挂载它，链接会运行相同的已发布快照，检查、品牌标识和决策规则都完全相同。您选择的是一个交付平台，而不是需要维护的第二个验证流程。

两者之间究竟有何不同？

两条路径最终殊途同归。申请人完成信息采集步骤后，平台异步处理验证，后端通过Webhook （在新标签页中打开）或状态轮询获知结果。区别在于流程的发起方以及代码控制的内容。

最后一行是人们容易误解的地方。有了工作流，两种路径都不需要修改代码就能改变流程。如果没有工作流，嵌入代码就意味着要把国家/地区、ID 类型和步骤切换等参数作为 props 传递，而且每次修改都会触发一次发布。

当 SDK 嵌入是正确的选择

当验证是您掌控的用户旅程中的一个步骤，且用户已登录时，即可嵌入验证。例如，钱包应用会在用户首次转账前进行验证，或者市场平台会在卖家首次上架商品前进行验证，这两种情况都符合要求。

你可以获得链接无法提供的三样东西。

在您自己的代码中使用回调函数 。SDK 呼叫onSubmit与一个verificationId验证创建完成后，即可将用户移至待处理屏幕，而无需等待 webhook。onError报告技术故障（网络、摄像头权限、已禁用的 ID 类型），并保持稳定。code。

原生设备功能。React Native 和 Flutter SDK 可以 （在新标签页中打开）通过读取 Passport 芯片来获取设备信息。 NFC 并在设备上运行实时检测。浏览器无法与护照芯片通信，因此网络 SDK 仪表盘构建器预览中仅显示芯片屏幕。

你已拥有的身份。你通过userId和userData从您的会话中，验证与已知帐户关联，并将您持有的姓名与文档进行比较。

一个极简的网页嵌入，取自 SDK 文档：

<MyazaKYC
  apiKey="pk_live_…"
  workflowId="wf_AbC123dEf456"
  userId="user_42"
  metadata={{ requestId: "order_1001" }}
  onSubmit={(s) => console.log(s.verificationId)}
/>

成本确实存在，但并不高。你添加一个依赖项，只需确保其版本不低于支持该依赖项的最低版本即可。workflowId（Web 2.2.0、React Native 2.1.0、Flutter 2.2.0 或更高版本），并且在 React Native 上需要自定义开发版本，因为 SDK 搭载原生代码。

何时选择托管链接才是正确的选择

当您需要验证的人员不在应用内时，请发送链接。以下是一些常见链接样式：

• 一家商业贷款机构正在收款 KYC 来自一位从未登录过任何网站的导演。

• 运营团队正在重新核实一位证件已过期的客户的信息。

• 一个没有移动应用程序的平台，仅验证通过电子邮件访问的用户。

• 合作伙伴渠道，但您完全无法在该渠道发布代码。

链接有两种类型，选择哪种链接比选择链接还是嵌入更重要。

每个申请人的会话链接

当您知道谁应该进行验证时，请从后端创建一个会话。POST /api/kyc/sessions （在新标签页中打开）以及一把密钥：

curl "https://api.toden.co/api/kyc/sessions" \
  -H "Authorization: Bearer $MYAZA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "wf_AbC123dEf456",
    "externalUserId": "user_42",
    "userData": { "firstName": "John", "lastName": "Doe" }
  }'

回应包含url它属于那位申请人。它是一次性的，可以追溯到您。externalUserId一旦提交，费用就会立即消耗，所以转发给第二个人是行不通的。您可以传递email您可以选择让别人代您发送链接，或者亲自发送。

桌面用户在托管页面上会看到一个“在手机上继续”的二维码，用于指示相机操作步骤，因此通过电子邮件发送给笔记本电脑用户的链接仍然可以访问相机。（网络） SDK 桌面端也采用相同的切换方式，由其控制。deviceHandoff选项。）

有两个细节需要注意。链接在以下情况下不再接受新的开始：expiresAt个人流程的有效期为 24 小时，业务流程的有效期为 7 天，除非工作流自行设置了会话生命周期。申请人访问的配置是您创建链接时已发布的快照，因此重新发布不会更改已存在于用户收件箱中的链接。

共享托管链接

每个已发布的流程都可以作为一个公共流程启用。 URL 许多人都会打开这个链接，每次访问都会启动一次验证。它适用于营销活动或柜台上的二维码，因为你确实不知道谁会来。缺点在于归因问题：该链接不包含系统中任何用户的关联信息，因此你必须通过其他方式来核对结果。从工作流页面重新生成链接会覆盖旧的关联信息。 URL 如果信息传播范围超出预期，你可以立即采取行动。如果你认识对方，可以使用私信的方式。

中间路径：应用内的托管链接

有些团队希望页面由我们托管，但需要在他们自己的移动应用中打开，通常是为了避免对原生应用的依赖。这可行。打开会话url在react-native-webview，webview_flutter或者使用 iframe，页面会将进度作为托管链接事件 （在新标签页中打开）报告给宿主：ready，started，step，submitted，completed，error和closed。

<WebView
  source={{ uri: session.url }}
  onMessage={(event) => {
    const message = JSON.parse(event.nativeEvent.data);
    if (message.source !== 'myaza-kyc') return;
    if (message.type === 'submitted') {
      navigation.replace('VerificationPending', { id: message.verificationId });
    }
  }}
/>

选择之前先了解它的局限性。 NFC WebView 内部不支持芯片读取、后台存在性检查和原生活体检测。事件仅包含 ID、步骤名称和错误代码，不包含申请人输入或记录的任何内容，这些信息仅供界面参考，并非记录。最终结果仍由 Webhook 或状态轮询决定。

在 iframe 中，将页面的源作为参数附加到 iframe 中。origin查询参数。只有当浏览器确认您的页面确实是嵌入页面时，页面才会发布事件；否则，不会发布任何事件。

经过深思熟虑的决定

假设有一家消费贷款机构，它拥有一个移动应用和一个现场销售团队。新客户在首次贷款前需要在应用内进行验证，因此该应用嵌入了 React Native。 SDK 已发布的流程包括读取护照芯片。现场代理负责为尚未安装该应用程序的市场中的交易员进行注册，因此后端会为每位交易员创建一个会话，并以交易员的线索 ID 为准。externalUserId代理人通过以下方式发送链接 SMS ID 过期的客户会从运营部门获得新的会话链接。

一个工作流程可以服务于所有三个环节，或者贷款方可以为字段链接保留一个更轻量级的工作流程。无论哪种方式，所有结果都会发送到同一个 webhook 处理程序，该处理程序由……键控。verificationId并承担贷款方自身的责任externalUserId。

决策规则

1. 在选择界面之前，先构建一个已发布的流程。

2. 如果用户在验证时已登录您的产品，则嵌入 SDK 使用原生 SDK 如果您需要 NFC 芯片读取。

3. 如果验证发生在您的产品之外，并且您认识该人，请从您的后端为每个申请人创建一个会话。

4. 仅当您无法确定谁会打开链接时才使用共享托管链接，并计划如何归因结果。

5. 如果您想在应用内使用托管页面，请打开会话。 URL 在 WebView 中监听托管链接事件，接受芯片读取和原生活性丢失的情况。

6. 无论你选择哪种方式，都要将 webhook 视为真理来源，将客户端信号视为提示。