Troubleshooting

Решение частых проблем и ошибок при работе с ADQuest Widget.

Частые ошибки

Виджет не отображается

Проверьте загрузку скриптов

Убедитесь, что скрипты загружены правильно:

// Проверка в консоли браузера
console.log(typeof window.ADQuest); // Должно быть 'object'

Если undefined, проверьте:

Правильность URL скрипта
Отсутствие блокировки Content Security Policy
Отсутствие блокировки AdBlock

Проверьте Site Key

// Неправильно - Site Key не указан
ADQuest.init({
  container: document.getElementById("adquest-captcha"),
});

// Правильно
ADQuest.init({
  siteKey: "YOUR_SITE_KEY",
  container: document.getElementById("adquest-captcha"),
});

Проверьте контейнер

const container = document.getElementById("adquest-captcha");
console.log(container); // Не должно быть null

if (!container) {
  console.error("Контейнер не найден!");
}

Ошибка "Invalid Site Key"

Причины:

Неверный Site Key
Site Key для другого домена
Использование production ключа на localhost

Решение:

// Используйте тестовый ключ для разработки
const SITE_KEY =
  process.env.NODE_ENV === "production"
    ? "prod_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    : "test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

ADQuest.init({
  siteKey: SITE_KEY,
  container: document.getElementById("adquest-captcha"),
});

Токен не проходит проверку на сервере

Проверьте время жизни токена

Токены действительны 1 час по умолчанию:

// Увеличьте время жизни токена
ADQuest.init({
  siteKey: "YOUR_SITE_KEY",
  container: document.getElementById("adquest-captcha"),
  tokenTTL: 7200, // 2 часа
});

Проверьте одноразовое использование

Каждый токен можно использовать только один раз:

// Неправильно - повторное использование токена
const token = ADQuest.getToken();
await verifyToken(token); // Первая проверка - OK
await verifyToken(token); // Вторая проверка - FAIL

// Правильно - получите новый токен
ADQuest.reset();
// Пользователь проходит проверку заново

CORS ошибки

Добавьте домен в dashboard

Откройте Dashboard ↗
Перейдите в настройки Site Key
Добавьте ваш домен в список разрешенных

Проверьте apiBaseURL

// Убедитесь, что используете правильный URL
ADQuest.init({
  siteKey: "YOUR_SITE_KEY",
  container: document.getElementById("adquest-captcha"),
  apiBaseURL: "https://api.ad-quest.ru", // Правильный URL
});

Отладка

Включение debug режима

// Добавьте в консоль браузера
localStorage.setItem("adquest_debug", "true");

// Перезагрузите страницу
location.reload();

Вы увидите подробные логи в консоли:

[ADQuest] Initializing widget...
[ADQuest] Site Key: YOUR_SITE_KEY
[ADQuest] Mode: advertisement
[ADQuest] Loading advertisement...
[ADQuest] Token received: eyJ...

Проверка состояния виджета

// В консоли браузера
console.log(ADQuest.getToken()); // Текущий токен или null

Мониторинг событий

ADQuest.init({
  siteKey: "YOUR_SITE_KEY",
  container: document.getElementById("adquest-captcha"),

  onLoad: () => {
    console.log("✓ Виджет загружен");
  },

  onSuccess: (token) => {
    console.log("✓ Токен получен:", token);
  },

  onError: (error) => {
    console.error("✗ Ошибка:", error);
  },

  onExpire: () => {
    console.warn("⚠ Токен истек");
  },
});

Производительность

Ленивая загрузка

Загружайте виджет только когда он нужен:

// Загрузка при клике на форму
document.getElementById("loginForm").addEventListener(
  "focus",
  () => {
    if (!window.ADQuest) {
      const script = document.createElement("script");
      script.src = "https://cdn.ad-quest.ru/widget/v1/adquest-widget.min.js";
      script.async = true;
      document.body.appendChild(script);
    }
  },
  { once: true },
);

Предзагрузка

Используйте <link rel="preload"> для ускорения загрузки:

<link
  rel="preload"
  href="https://cdn.ad-quest.ru/widget/v1/adquest-widget.min.js"
  as="script"
/>
<link
  rel="preload"
  href="https://cdn.ad-quest.ru/widget/v1/adquest-widget.min.css"
  as="style"
/>

Безопасность

Content Security Policy

Добавьте в CSP:

<meta
  http-equiv="Content-Security-Policy"
  content="
        script-src 'self' https://cdn.ad-quest.ru;
        connect-src 'self' https://api.ad-quest.ru;
        style-src 'self' https://cdn.ad-quest.ru;
      "
/>

Защита от XSS

Никогда не вставляйте токен в HTML:

// Неправильно - уязвимость XSS
document.getElementById("token").innerHTML = token;

// Правильно - отправьте на сервер
fetch("/api/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token }),
});

Ограничения

Rate Limits

Действие	Лимит	Период
Инициализация виджета	10	1 минута
Проверка токена	100	1 минута
Получение рекламы	50	1 минута

При превышении лимита вы получите ошибку RATE_LIMIT_EXCEEDED.

Размер токена

Токены имеют размер ~500-1000 байт. Учитывайте это при передаче в URL или cookies.

Поддержка браузеров

Браузер	Минимальная версия
Chrome	90+
Firefox	88+
Safari	14+
Edge	90+

Следующие шаги

Конфигурация - настройка виджета
API Reference - полная документация API
Примеры интеграции - готовые решения