跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

自定义 Waiting Room

最后更新 查看 MarkdownAgent 设置

您可以从仪表板或通过 API 自定义 Waiting Room。

从仪表板自定义 Waiting Room

要设计和预览 Waiting Room 的外观，请在 Create Waiting Room（创建 Waiting Room） 页面中选择 Custom（自定义） 选项卡。

Cloudflare 提供了自定义 Waiting Room 外观的选项：

  • 默认 Waiting Room：一个无品牌标识的 Waiting Room，向访问者显示预计的等待时间。
    • 为您的默认 Waiting Room 页面选择一种语言。您可以从以下语言中进行选择：英语、阿拉伯语、德语、西班牙语、法语、印度尼西亚语、意大利语、日语、韩语、荷兰语、波兰语、葡萄牙语（巴西）、土耳其语和中文（简体和繁体）。
  • 自定义 Waiting Room：编辑模板文本或创建您自己的 HTML 代码：
    • 自定义 HTML 或 CSS 内容，包括字体、颜色、静态图像、其他语言等。
    • 直接在仪表板中编辑内容或导入相关文件。
  • 返回 JSON 友好的 Waiting Room 响应：切换以同时启用包含用户在 Waiting Room 中状态的 JSON 响应。

默认 Waiting Room

要选择默认的、无品牌标识的 Waiting Room：

  1. 选择一个 Waiting Room。
  2. 转到 Customize（自定义） 步骤。
  3. 选择 Default Waiting Room（默认 Waiting Room）。
  4. 为您的 Waiting Room 默认页面选择语言。

自定义 Waiting Room

要自定义 Waiting Room：

  1. 选择一个 Waiting Room。
  2. 转到 Customize（自定义） 步骤。
  3. 选择 Custom Waiting Room（自定义 Waiting Room）。

您可以直接在文本框中编辑 HTML 代码：

  • 选择 Download default template（下载默认模板） 将包含默认模板内容的 HTML 文件下载到您的计算机。
  • 选择 Download（下载） 将包含文本框内容的 HTML 文件下载到您的计算机。
  • 选择 Copy（复制） 将文本框中的文本复制到剪贴板，然后将其粘贴到您选择的编辑器中。

模板文本包含 显示等待时间的代码。如果您想向访问者显示预计的等待时间，请不要删除此内容。

上传 HTML 文件

  1. 选择 Import（导入） 从您的计算机上传 HTML 文件。
  2. 在对话框中选择文件并选择 Open（打开）。HTML 文件大小限制为 1,048,576 字节 (1 MB)。

在文本框中进行进一步编辑。包含 显示等待时间的代码 以在 Waiting Room 页面上显示预计排队时间，或使用 可用变量 创建您自己的自定义页面。

显示等待时间

模板 HTML 代码 <main> 部分中的以下内容显示等待时间：

<h2 id="time-remaining">
  <noscript>
    {{#waitTimeKnown}}Your estimated wait time is {{waitTimeFormatted}}...{{/waitTimeKnown}}
    {{^waitTimeKnown}}{{#queueIsFull}}The estimated wait time is greater than a day. You will
    automatically be placed in the queue once space is available.{{/queueIsFull}}
    {{^queueIsFull}}Your estimated wait time is unavailable.{{/queueIsFull}}{{/waitTimeKnown}}
  </noscript>
</h2>

<main> 后面的 <body> 部分中的以下脚本获取等待时间：

<script type="text/javascript">
  var remainingEl = document.getElementById('time-remaining');
  var waitTime = {{waitTime}};
  var waitTimeKnown = {{waitTimeKnown}};

  var remainingString = 'Your estimated wait time is ';

  if (!waitTimeKnown) {
    remainingString += 'unavailable.'
  } else {
    if (waitTime === 1) {
      remainingString += waitTime + ' minute...';
    } else {
      remainingString += waitTime + ' minutes...';
    }
  }

  remainingEl.innerText = remainingString;
</script>

Turnstile 变量

如果您为自定义 Waiting Room 使用 Turnstile，您需要确保已添加 turnstile 变量。默认排队页面模板和任何新创建的自定义模板已包含此变量。如果您有现有的自定义 HTML 模板并希望启用 Turnstile 集成，则需要在模板的某个位置添加 {{{turnstile}}}，以让 Waiting Room 知道小组件应该放置在哪里。Waiting Room 使用 Mustache 模板，因此在模板中包含未转义的原始 HTML 需要三个大括号，而不是两个。

<!DOCTYPE html>
<html>
  <head>
    <title>Waiting Room</title>
  </head>
  <body>
    <h1>You are currently in the queue.</h1>
    {{#waitTimeKnown}}
      <h2>Your estimated wait time is {{waitTimeFormatted}}.</h2>
    {{/waitTimeKnown}}
    {{^waitTimeKnown}}
      <h2>Your estimated wait time is unknown.</h2>
    {{/waitTimeKnown}}
    {{#turnstile}}
      <!-- for a managed (and potentially interactive) challenge, you may want to instruct the user to complete the challenge -->
      <p>Please complete this challenge so we know you're a human:</p>
      {{{turnstile}}} <!-- include the turnstile widget -->
    {{/turnstile}}
  </body>
</html>

当使用无限队列 (Infinite Queue) 时（特别是使用可能具有交互性的托管质询时），您可能希望让用户知道，在他们完成质询之前，他们不会处于队列中。

可用变量

在创建带有自定义 HTML 的 Waiting Room 时，您可以访问多个变量以自定义您的响应。有关变量的完整列表，请参考 Cloudflare API 文档 中的 json_response_enabled 参数。

多语言支持

可自定义的 Waiting Room 可以显示 UTF-8 字符集支持的任何语言的文本。要显示预计等待时间，您可以在 Waiting Room 模板中使用诸如 waitTime 和 waitTimeHours 等数值变量，无论用户的语言是什么。但是，目前，以下变量仅提供英语版本：waitTimeFormatted、timeUntilEventStartFormatted 和 timeUntilEventEndFormatted。

如果您希望根据路径或子域在自定义 Waiting Room 中显示不同的语言，则可以将 JavaScript 代码添加到您的自定义 HTML 中来实现。以下您可以找到几个入门模板，您可以将它们用作起点的示例：

  • 若要基于路径显示不同的语言，请下载此 模板。如果路径包含 en 或作为默认设置，则该模板以英语显示内容；如果路径包含 jp，则以日语显示；如果包含 fr，则以法语显示；如果包含 es，则以西班牙语显示。

  • 若要基于子域显示不同的语言，请下载此 模板。默认情况下或子域包含 en 时，该模板以英语显示内容；如果子域包含 jp，则以日语显示；如果包含 fr，则以法语显示；如果包含 es，则以西班牙语显示。

下载其中任何一个模板并根据您的意愿进行自定义。更新路径或子域以反映您站点的语言选择结构。您可以通过为每个语言环境向 translations 对象添加翻译，来编辑这些模板以包含其他语言。

资源托管

如果您在自定义 Waiting Room 中使用图像或其他资源，请 不要 将这些资产托管在您的 Waiting Room 涵盖的主机名上。否则，对这些资产的任何请求将无法通过 Waiting Room。

预览 Waiting Room

要预览 Waiting Room 的外观：

  1. 在您的应用程序中，转到 Traffic（流量） > Waiting Room（等候室）。
  2. 创建 Waiting Room 或 编辑现有的 Waiting Room。
  3. 转到 Review（检查） 步骤。
  4. 选择 Preview Waiting Room（预览 Waiting Room）：
  • 选择 Queueing（排队） 以显示仪表板上已启用它且未启用 Queue-all（全部排队） 时的 Waiting Room 外观。
  • 选择 Queue-All（全部排队） 以显示仪表板上已启用它且也启用了 Queue-all（全部排队） 时的 Waiting Room 外观。当为 Waiting Room 启用 Queue-all（全部排队） 时，不会显示预计的等待时间。

故障排除

如果您在预览 Waiting Room 时发现异常情况，请检查您的自定义代码，查看语法是否正确。通常，您可能会忘记用其适当的结束标签（带有 / 的标签名称）闭合每个标签。

通过 API 自定义 Waiting Room

您可以使用 Waiting Room API 来自定义访问者被放入虚拟 Waiting Room 时所服务的网页。

在以下 PATCH 请求中，custom_page_html 字段包含 自定义 Waiting Room 的 HTML 代码：

Required API token permissions

At least one of the following token permissions is required:
  • Waiting Rooms Write
Patch waiting roombash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/$WAITING_ROOM_ID" \
	--request PATCH \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"name": "webshop-waiting-room",
		"host": "example.com",
		"new_users_per_minute": 200,
		"total_active_users": 300,
		"custom_page_html": "<p>Include custom HTML here</p>"
	}'

响应：

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": [
    {
      "id": "1111111111111111111111",
      "name": "webshop-waiting-room",
      "description": "Waiting room for webshop",
      "host": "example.com",
      "path": "/shop",
      "suspended": false,
      "queue_all": false,
      "new_users_per_minute": 200,
      "total_active_users": 300,
      "session_duration": 1,
      "disable_session_renewal": false,
      "json_response_enabled": false,
      "queueing_method": "FIFO",
      "cookie_attributes": {
        "samesite": "auto",
        "secure": "auto"
      },
      "custom_page_html": "<p>Include custom HTML here</p>",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "modified_on": "2014-01-01T05:20:00.12345Z"
    }
  ]
}

预览自定义 Waiting Room 的 HTML 代码

在发出 API 请求以使用自定义 HTML 配置 Waiting Room 网页之前，您可以通过将其上传到预览端点来预览您的自定义 HTML：

POST https://api.cloudflare.com/client/v4/zones/{zone_id}/waiting_rooms/preview

在请求正文中，将自定义的 HTML 内容包含在 custom_html 字段中：

{
  "custom_html": "<p>Include custom HTML here</p>"
}

请注意，您将 HTML 内容在 custom_html 字段中传递给预览端点，但是在您使用 API 配置 Waiting Room 时，您需要在 custom_page_html 字段中传递 HTML 内容。

请求示例：

Required API token permissions

At least one of the following token permissions is required:
  • Waiting Rooms Write
Create a custom waiting room page previewbash
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/waiting_rooms/preview" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"custom_html": "<p>Include custom HTML here</p>"
	}'

预览端点在响应正文中返回一个临时 URL，您可以在该处预览您的自定义页面：

{
  "result": {
    "preview_url": "https://waitingrooms.dev/preview/111111111111"
  },
  "success": true,
  "errors": [],
  "messages": []
}

您不必拥有 Cloudflare 账户即可访问预览链接，因此您可以在多台设备上验证 Waiting Room 网页。

预览默认或当前的 Waiting Room 网页

在 生成预览 URL 后，使用以下端点生成用于预览当前配置的 Waiting Room 网页的链接，如果未配置自定义页面，则为默认页面。

GET https://waitingrooms.dev/preview/{preview_id}

响应中的链接显示 custom_page_html 字段的内容，使用 mustache ↗ 呈现。

使用可选的 force_queue 查询参数可在所有流量都被强制排队时预览 Waiting Room 网页。

这篇文档对您有帮助吗？