INTEGRITY Документация

← Cloudflare Waiting Room / waiting-room / how-to

Настройка зала ожидания

Вы можете настроить зал ожидания на панели управления или через API.

Настройка зала ожидания в дашборде

Чтобы настроить и предварительно просмотреть оформление зала ожидания, выберите Настройка вкладку в Создание зала ожидания страницу.

Cloudflare предлагает варианты настройки внешнего вида вашего зала ожидания:

Зал ожидания по умолчанию

Чтобы выбрать зал ожидания по умолчанию без брендирования:

  1. Выберите зал ожидания.
  2. Перейдите в Настройка шаг.
  3. Выберите Зал ожидания по умолчанию.
  4. Выберите язык страницы зала ожидания по умолчанию.

Пользовательский зал ожидания

Чтобы настроить зал ожидания:

  1. Выберите зал ожидания.
  2. Перейдите в Настройка шаг.
  3. Выберите Пользовательский зал ожидания.

Вы можете редактировать код HTML прямо в текстовом поле:

Текст шаблона содержит код для отображения времени ожидания. Если вы хотите показывать посетителям расчётное время ожидания, не удаляйте этот контент.

Загрузите HTML-файл

  1. Выберите Импорт чтобы загрузить HTML-файл с компьютера.
  2. Выберите файл в диалоговом окне, а затем нажмите Открыто. Максимальный размер HTML-файла составляет 1,048,576 байт (1 МБ).

Внесите дальнейшие изменения в текстовое поле. Включите код для отображения времени ожидания чтобы отображать примерное время в очереди на странице Waiting Room, либо создайте собственную страницу с помощью доступные переменные.

Отображение времени ожидания

Следующее содержимое в <main> раздел HTML-кода шаблона отображает время ожидания:

<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>

Следующий скрипт в <body> раздел после <main> получает время ожидания:

<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

Если вы используете 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, особенно вместе с managed challenges, которые могут быть интерактивными, стоит предупредить пользователей, что они не попадут в очередь, пока не пройдут проверку.

Доступные переменные

При создании зала ожидания с пользовательским HTML вам доступны несколько переменных для настройки ответа. Полный список переменных приведён в json_response_enabled параметр в Документация Cloudflare API.

Поддержка нескольких языков

Настраиваемые залы ожидания могут отображать текст на любом языке, поддерживаемом набором символов UTF-8. Чтобы отобразить примерное время ожидания, можно использовать числовые переменные, такие как waitTime и waitTimeHours в шаблоне зала ожидания независимо от языка пользователя. При этом на данный момент следующие переменные доступны только на английском языке: waitTimeFormatted, timeUntilEventStartFormatted, а также timeUntilEventEndFormatted.

Если вы хотите отображать разные языки в своём настроенном зале ожидания в зависимости от пути или поддомена, можно добавить в пользовательский HTML код на JavaScript, который это реализует. Ниже приведено несколько исходных шаблонов, которые можно использовать в качестве примера для начала работы:

Скачайте любой из этих шаблонов и настройте его по своему усмотрению. Обновите путь или поддомен так, чтобы он отражал структуру выбора языка вашего сайта. Добавить другие языки в эти шаблоны можно, добавив переводы в translations объект для каждой из локалей.

Размещение ресурсов

Если вы используете изображения или другие ресурсы для настроенного зала ожидания, не разместите эти ресурсы на хосте, который охватывает ваш зал ожидания. Иначе запросы к этим ресурсам не смогут пройти через зал ожидания.

Предварительный просмотр зала ожидания

Чтобы предварительно просмотреть оформление зала ожидания:

  1. В своём приложении перейдите к Трафик > Waiting Room.
  2. Либо создать зал ожидания или отредактировать существующий.
  3. Перейдите в Проверить шаг.
  4. Выберите Предварительный просмотр зала ожидания:

Устранение неполадок

Если при предварительном просмотре зала ожидания вы замечаете что-то неожиданное, проверьте свой пользовательский код на правильность синтаксиса. Часто забывают закрыть каждый тег соответствующим закрывающим тегом (имя тега с /).

Настройка зала ожидания через API

С помощью Waiting Room API можно настроить веб-страницу, которая показывается посетителям, помещённым в виртуальный зал ожидания.

В следующем PATCH запрос, custom_page_html поле содержит HTML-код для пользовательский зал ожидания:

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:
Изменение зала ожидания
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"
    }
  ]
}

Предварительный просмотр HTML-кода настроенного зала ожидания

Прежде чем отправлять запрос API для настройки страницы зала ожидания с пользовательским HTML, вы можете предварительно просмотреть свой 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 HTML-содержимое передаётся в поле custom_page_html поле.

Пример запроса:

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:
Создание предпросмотра пользовательской страницы зала ожидания
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 не нужна, поэтому страницу зала ожидания можно проверить на нескольких устройствах.

Предварительный просмотр веб-страницы зала ожидания по умолчанию или текущей настроенной страницы

После создание ссылки для предварительного просмотра, используйте следующую конечную точку, чтобы получить ссылку для предварительного просмотра текущей веб-страницы зала ожидания или страницы по умолчанию, если пользовательская страница не настроена.

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

Ссылка в ответе отображает содержимое custom_page_html поле, отображаемое с помощью mustache ↗.

Используйте необязательный force_queue параметр запроса, чтобы просматривать веб-страницу Waiting Room, когда весь трафик принудительно поставлен в очередь.