---
title: "验证设置"
description: "设置 Verify 验证码的有效时长、验证在多少次错误校验后失败、重新发送冷却时间，以及验证码自动填充所绑定的网站。"
canonical: "https://bird.com/zh-sg/wendang/guides/verify/settings"
---

# 验证设置

[**Configure**](https://bird.com/dashboard/w/verify/configure) 页面的 **General** 选项卡决定工作区中每个验证的行为。它控制验证码的有效时长、多少次错误尝试会结束一个验证、多久之后可以发送新验证码，以及验证码所属的网站。

每个字段显示的是生效值：如果您设置了覆盖值，则显示该值，否则显示 Bird 的平台默认值。离开字段时即自动保存。**Duration**、**Maximum Retries** 和 **Website** 在创建验证时固定，因此修改它们只对新的验证生效。修改 **Retry Delay** 则对下一次创建调用生效，包括已在进行中的验证。

修改设置需要 `write` 级别的 `verify_management` 权限，`admin` 和 `developer` 角色包含该权限。`analyst` 角色可以查看此页面。请参阅[用户、团队和角色](/docs/guides/users-teams-roles#workspace-roles)。

![Configure 页面的 General 选项卡，显示 Duration、Maximum Retries、Retry Delay 和 Website 字段](/images/docs/dashboard-verify-configure-general.png)

## 验证周期

| 设置                | 控制内容                                                                                             | 默认值  | 范围          |
| ------------------- | ---------------------------------------------------------------------------------------------------- | ------- | ------------- |
| **Duration**        | 验证保持有效的时长。超过此时间窗口后的校验会返回原因 `expired`，验证随即结束，原因为 `ttl_elapsed`。 | 10 分钟 | 1 至 999 分钟 |
| **Maximum Retries** | 多少个错误验证码会结束一个验证。最后一个错误验证码会使验证失败，原因为 `attempts_exhausted`。        | 5       | 1 至 10       |
| **Retry Delay**     | 重新发送冷却时间：向同一收件人发送下一个验证码前的最短等待时间。                                     | 60 秒   | 0 至 3600 秒  |

- **Duration** 从创建验证时开始计时。重新发送验证码或切换到其他渠道会发送新的验证码，但保留原来的过期时间，因此较晚的重新发送不会延长有效期。对于身份验证流程，请将其设为 10 分钟或更短；原因见[最佳实践](/docs/guides/verify/best-practices#keep-the-lifetime-at-ten-minutes-or-less)。
- **Maximum Retries** 统计该验证下所有已发送验证码的错误输入次数，因此重新发送不会将其重置。如果某次校验使用了错误的验证码但验证仍处于待定状态，响应会在 `attempts_remaining` 中报告剩余的尝试次数。
- **Retry Delay** 在你为同一收件人再次调用创建接口时生效。在冷却期内，该调用会返回仍有效的验证，而不会发送新的验证码。[通过其他渠道发送验证码](/docs/guides/verify/sending-verifications#send-the-code-on-another-channel)不受此限制，因为切换渠道与再次请求同一渠道是不同的请求。将其设为 0，则每次调用创建接口都会发送新的验证码，但仍受[滥用防护](/docs/guides/verify/sending-verifications#abuse-guardrails)中针对每个收件人的限制约束。

验证码长度不在此页面设置。验证码默认为六位数字，`options.code_length` 可为单个验证设置 4 到 8 位数字；请参阅[选项](/docs/guides/verify/sending-verifications#options)。

## 自动填充

**Website** 指定用户输入验证码的网站，例如 `https://login.example.com`。设置网站后，浏览器只会在该网站上提示填入验证码，不会在其他网站上提示，这样用户无需手动复制验证码。留空则发送的验证码不指定任何网站。

网站的写法为 `https://` 加上小写域名，不带端口、路径或末尾斜杠。国际化域名使用其 `xn--` 形式，例如 `bücher.example` 写作 `https://xn--bcher-kva.example`。其他任何形式都会被拒绝；如果存在可用的形式，错误消息会给出应填写的形式。请使用显示验证码输入框的确切网站：位于 `login.example.com` 上的表单需要填写 `https://login.example.com`，而不是 `https://example.com`。

验证一旦设置了网站，Verify 就会将其添加到验证码消息中：

- **SMS**：消息末尾会附加一行，例如 `@login.example.com #123456`。为验证码输入框添加 `autocomplete="one-time-code"`，Safari 和其他浏览器就会提示填入验证码；如果希望浏览器无需点击即可自动填入，请在页面中调用 [WebOTP API](https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API)。这一额外行可能会增加一个 SMS 分段：在许多需要 Unicode 编码的语言中，例如阿拉伯语、希腊语或俄语，绑定网站的验证码会占用两个分段而不是一个，使其 SMS 费用翻倍；在其他语言中，较长的域名也可能产生同样的结果。
- **电子邮件**：消息会携带一个 `OTP-Token` 邮件头，其中包含验证码和网站，其定义见 [OTP-Token 互联网草案第 01 版](https://datatracker.ietf.org/doc/draft-goto-otp-token/01/)。邮件应用才刚开始读取此邮件头，因此请将其视为消息正文中验证码的补充。

网站在创建验证时即已确定。重新发送、回退到其他渠道或为同一收件人再次调用创建接口都会保留该网站。

### 按请求绑定验证码

请求可以通过 `options.autofill_origin` 指定自己的网站，该值会替换此验证的 **Website**。当一个工作区服务多个网站时使用。

如果验证码输入框位于跨源 iframe 中，例如嵌入在商店结账页中的支付表单，请将 `options.autofill_origin` 设为该 iframe 的网站，并将 `options.autofill_top_level_origin` 设为浏览器标签页中的页面。这样 SMS 行会同时列出两个网站，如 `@shop.example #123456 @pay.example`，这在任何语言中都可能增加一个分段。当页面直接嵌入该 iframe 并授予其 `allow="otp-credentials"` 时，Chrome 会自动填充该表单。对于这类验证，电子邮件不发送 `OTP-Token` 头，因为该头只能指定一个网站。如果顶层网站格式错误、请求和此页面中都未设置网站，或者顶层网站与该网站相同，请求会被拒绝并返回 `422`。

### 已注册的 SMS 发送方

如果您通过自己注册的发送方发送 SMS，例如美国 10DLC 活动，请在设置网站之前，向该活动添加一条以绑定行结尾的示例消息。如果消息与活动注册的示例不同，运营商可能会过滤该消息。

## 故障排除

- **网站被拒绝。** 该值不符合要求的格式。请输入消息建议的格式，例如用 `https://example.com` 表示 `https://Example.com/`。
- **浏览器没有提供验证码。** 请检查网站是否与页面地址完全一致（包括所有子域名），以及验证码输入框是否设置了 `autocomplete="one-time-code"`。对于 iframe，请检查请求是否同时设置了两个网站，以及嵌入页面是否授予了 `allow="otp-credentials"`。自动填充还取决于浏览器：Chrome 通过 WebOTP 读取 SMS 行，Safari 通过其验证码自动填充功能读取，而 Firefox 不支持 WebOTP（[浏览器支持](https://caniuse.com/mdn-api_otpcredential)）。
- **验证码在用户输入前已过期。** 在调高 **Duration** 之前，请先在 [Verify 日志](/docs/guides/verify/verify-log)中查看尝试的时间。原因通常是投递路径较慢，而延长有效时间会削弱验证码的安全性。

## 后续步骤

- [发送验证](/docs/guides/verify/sending-verifications)：创建和检查验证，包括按请求设置的选项。
- [目的地](/docs/guides/verify/destinations)：为每个目的地国家/地区选择渠道及其顺序。
- [发送方与品牌](/docs/guides/verify/senders)：查看 Verify 发送的消息，并为每个渠道选择发送方。

## Related resources

- [Verify phone numbers at signup](/learn/series/verify-phone-numbers-at-signup) (video)
- [What does OTP mean? One-time passwords explained](/explained/verify/what-does-otp-mean) (answer)
- [Customer verification](/verify-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=verify)