> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress KYC 插件：WooCommerce 年龄验证

> 面向 WordPress 与 WooCommerce 的身份验证、年龄限制和 KYC 插件，无需编码。每次完整 KYC 检查低至 $0.33，每月 $10 免费额度，无需签约。

为 WordPress 网站或 WooCommerce 商店添加 Didit 身份验证和年龄限制。该插件作为安全的后端代理运行，您的 API 密钥保留在服务器上。它提供短代码、WooCommerce 结账验证门槛和开发者钩子，无需编写 JavaScript 即可接入验证功能。

## 前提条件

* WordPress 6.0 或更高版本
* PHP 7.4 或更高版本
* 一个 [Didit Console](https://business.didit.me) 账户

## 步骤 1 获取您的 Didit 凭证

1. 在 **[business.didit.me](https://business.didit.me)** 注册或登录
2. 前往 **API & Webhooks**，复制您的 **API Key**
3. 前往 **Workflows**，创建或选择一个工作流，并复制 **Workflow ID**

> [!NOTE]
>
> 您可以使用 **UniLink URL** 预览验证流程，无需 API 密钥。
> 对于内容限制和 WooCommerce 验证要求，请使用 **API Session** 模式，并配合 API 密钥和工作流 ID。
> 仅完成 UniLink 不会解锁受保护的内容，也不会批准订单。

## 步骤 2 安装插件

1. 从 **[0.3.4 发布版本](https://github.com/didit-protocol/plugin-wordpress/releases/tag/v0.3.4)** 下载 `didit-verify-0.3.4.zip`
2. 在 WordPress 后台，前往 **Plugins → Add New → Upload Plugin**
3. 选择下载的 ZIP 文件，然后点击 **Install Now**
4. 点击 **Activate**

> [!NOTE]
>
> Didit Verify 也列在 [WordPress.org](https://wordpress.org/plugins/didit-verify/) 上。
> 安装前请检查版本：若要使用此处描述的服务器确认验证行为，请使用 0.3.4 或更高版本。
> 从 0.3.4 版本起，已批准的验证如果之后被拒绝、过期或重新进入审核，用户对受保护内容的访问权限将被撤销。
> 如果插件目录中是较旧的版本，请安装上面的 ZIP 发布版本。

> [!WARNING]
>
> 从 0.3.2 之前的版本升级后，如果用户之前的批准未经服务器确认，该用户在访问受保护内容或完成需要验证的结账之前，必须重新验证。

## 步骤 3 配置插件

前往 **Settings → Didit Verify**。

### 选择模式

| 模式 | 适用场景 | 所需内容 |
| - | - | - |
| **UniLink** | 快速测试 | 仅需工作流中的 UniLink URL |
| **API Session**（推荐） | 生产环境使用 | 工作流 ID + API 密钥 |

**使用 UniLink：** 将 Mode 设为 "UniLink"，粘贴您的 URL，然后保存。

**使用 API Session：** 将 Mode 设为 "API Session"，输入您的工作流 ID 和 API 密钥，然后保存。

> [!NOTE]
>
> API 密钥安全地存储在您的服务器上，绝不会暴露给访客。

### 配置会话选项（仅限 API 模式）

以下为可选设置，可让您更好地掌控验证流程：

* **Vendor Data**：将每次验证关联到 Didit 控制台中的特定用户，以便您追踪是谁完成了验证。默认值为 WordPress 用户 ID（例如 `wp-42`）。您也可以选择 User Email、自定义前缀，或将其禁用。
* **Callback URL**：验证完成后用户被重定向到的您网站上的页面。Didit 会将 `verificationSessionId` 和 `status` 作为查询参数附加到该地址。
* **Callback Method**：决定由哪台设备处理重定向：`initiator`（发起验证的设备）、`completer`（完成验证的设备）或 `both`。
* **Language**：从 54 种语言中选择，或让其根据浏览器自动检测。

### 配置显示选项

* **Display Mode**：Modal（弹出式覆盖层）或 Embedded（嵌入页面内）
* **Close Button**：显示或隐藏弹窗上的 X 按钮
* **Exit Confirmation**：关闭时显示 "Are you sure?" 对话框
* **Auto-close**：验证完成后自动关闭弹窗
* **Debug Logging**：将 SDK 事件记录到浏览器控制台（用于排查问题）

### 自定义按钮

在 **Button Appearance** 下，您可以更改以下内容：

* 按钮文字和成功提示文字
* 背景颜色和文字颜色
* 圆角半径、内边距和字体大小

您每次更改数值时，实时预览都会即时更新。

## 步骤 4 将验证添加到您的网站

### 适用于 WooCommerce 商店

1. 在 **Settings → Didit Verify → WooCommerce** 中，勾选 **Require identity verification at checkout**
2. 选择验证部分的显示位置：
   * 结账页面顶部
   * 账单信息之后
   * 订单备注之后
   * "下单"按钮之前（推荐）
3. 可选择设置 **Product Scope**：所有商品（默认）、仅限选定商品，或除选定商品外的所有商品。
   在商品编辑器中，于 **Product data → Advanced** 下勾选 **Didit verification** 复选框，即可标记需要验证的商品。
   购物车中只要包含至少一件需要验证的商品，就必须完成验证。
   该范围同时适用于结账模式和购买后模式。
4. 可选择在 **Settings → Didit Verify → WooCommerce** 下编辑 **Section Title**、**Checkout Message** 和 **Post-purchase Message**；留空的字段将使用默认文字。
5. 可选择启用 **Send Billing Data**，自动将客户的姓名、邮箱、电话和地址发送至 Didit，用于预填和交叉验证。

> [!NOTE]
>
> 国家代码会自动从 WooCommerce 的 alpha-2 格式转换为 Didit 所需的 alpha-3 格式。

客户必须获得服务器确认的 **Approved** 决定后，才能下单。
此规则同时适用于经典结账和区块结账。
插件会检查该会话是否属于当前购物者，以及是否已被用于其他订单。
会话 ID 会保存到订单中，以便查阅。

如果您选择 **After purchase**，订单将保持在暂停状态，直至服务器确认批准。
访客可以使用有效的订单密钥，在订单页面上完成验证。
请配置 **Settings → Didit Verify** 中显示的 Webhook URL 和密钥，以便带签名的状态更新能够放行已批准的订单。

### 适用于任何 WordPress 页面

将以下短代码添加到任意页面或文章中：

```
[didit_verify]
```

页面上会出现一个验证按钮，其样式与您的 Button Appearance 设置一致。

您可以按页面覆盖按钮文字：

```
[didit_verify text="Verify Now" success_text="Done!"]
```

也可以在特定页面上强制使用嵌入模式：

```
[didit_verify mode="embedded"]
```

## 第 5 步 仅向已验证用户开放内容(可选)

根据验证状态显示或隐藏内容：

内容限制要求用户已登录，并且审批须通过 API 会话模式确认。浏览器回调和重定向查询参数不会授予访问权限。

```
[didit_gate]
This content is only visible to verified users.
[/didit_gate]
```

未验证用户会看到一条提示和一个验证按钮。您可以自定义该提示：

```
[didit_gate message="Please verify to continue."]Secret content here.[/didit_gate]
```

在任何位置显示用户的验证状态：

```
[didit_status]
```

为已登录用户显示 "Identity Verified" 或 "Not Verified"。

## 检查验证状态

| 位置 | 方式 |
| - | - |
| **管理面板** | **Users → All Users**：“Didit” 列为已验证用户显示 ✓ |
| **WooCommerce 订单** | Didit 会话 ID 显示在订单详情中 |
| **短代码** | `[didit_status]` 可在任何页面显示状态 |

## 故障排除

| 问题 | 解决方法 |
| - | - |
| "Creating session..." 一直卡住 | 请检查 **Settings → Didit Verify** 中的 Workflow ID 和 API 密钥是否正确 |
| 弹窗无法打开 | 请确保页面包含 `[didit_verify]`，或已启用 WooCommerce 结账验证 |
| 验证界面语言错误 | 在 **Session Options** 中更改 **语言** 设置 |
| 需要调试 | 在 Display Options 中启用 **Debug Logging**，然后打开浏览器控制台（F12）查看 SDK 事件 |

## 安全性

插件充当安全的后端代理。您的 API 密钥永远不会到达浏览器。每个会话请求都受以下机制保护：

1. **CSRF nonce**：请求必须来自您的 WordPress 站点
2. **登录要求**：只有已注册用户才能创建会话（可配置）
3. **速率限制**：每位用户每小时 10 个会话，访客每个 IP 每小时 3 个
4. **输入清理**：所有字段均已列入白名单，并在服务器端进行清理

会话创建会将验证与当前买家或订单绑定。插件在将用户或订单标记为已通过之前，会通过 Didit API 或已验证的 Webhook 确认决策。

当需要验证时，即使已启用通用登录要求，访客结账也可以创建会话。

购买后验证同样需要有效的订单密钥。

***

## 面向开发者

### PHP 钩子

插件会触发 WordPress 动作，其他插件或主题可以挂接这些动作：

```php theme={null}
// When a user completes verification
add_action('didit_verification_completed', function ($user_id, $session_id, $status) {
    // Update CRM, send email, grant access, etc.
}, 10, 3);

// When a user cancels verification
add_action('didit_verification_cancelled', function ($user_id, $session_id) {
    // Log cancellation
}, 10, 2);

// When a session is created server-side
add_action('didit_session_created', function ($url, $user_id, $vendor_data) {
    // Log, notify, etc.
}, 10, 3);
```

### JavaScript 事件

验证完成时会派发一个 DOM 事件：

```javascript theme={null}
document.addEventListener('didit:complete', function (e) {
    console.log('Result:', e.detail); // { type, session }
});
```

### 在 PHP 中检查验证

```php theme={null}
$is_verified = Didit_Verify::init()->is_user_verified($user_id);
```

使用此辅助函数执行服务器确认检查。
不要仅凭旧版用户元数据或浏览器的 `didit:complete` 事件授予访问权限。

## 资源

* [插件源代码（GitHub）](https://github.com/didit-protocol/plugin-wordpress)
* [Didit API 文档](https://docs.didit.me/zh.md)
* [Didit 控制台](https://business.didit.me)
* [创建会话 API 参考](https://docs.didit.me/zh/sessions-api/create-session.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.