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

Один скрипт в браузере, один вызов API с вашего сервера. Всё, что нужно для запуска, на одной странице.

Быстрый старт

Вам понадобятся публичный ключ (pk_...) для браузера и секретный ключ (sk_...) для сервера. Оба находятся в панели, в разделе «Сайты и ключи».

1. Добавьте скрипт

Разместите этот тег на страницах, где пользователи регистрируются, входят, кликают по офферам или запрашивают вывод. Скрипт инициализируется сам, используя data-key

<script src="https://cashoutguard.com/v1/agent.js" data-key="pk_live_YOUR_PUBLIC_KEY" async></script>

2. Соберите request_id и отправьте его на сервер

Вызовите collect() в нужный момент, передав название события. Результат: { request_id, visitor_id }

const { request_id } = await CashoutGuard.collect({ event: 'cashout' });

collect() никогда не завершается reject. При сбое (блокировка, офлайн, таймаут) он возвращает request_id: null и строку с ошибкой. Всё равно отправляйте форму, а решение пусть принимает сервер.

3. Запросите решение с сервера

Отправьте событие POST-запросом на /v1/evaluate с секретным ключом в заголовке Authorization: Bearer sk_live_...

Никогда не размещайте секретный ключ в коде браузера или мобильного приложения. Вызывать /v1/evaluate должен только ваш сервер.

Запрос evaluate

POST https://cashoutguard.com/v1/evaluate оценивает одно событие для одного аккаунта, связывает его с устройством, сетью и адресом выплаты и возвращает решение. Отправляйте JSON.

Ответ

Ответ всегда имеет одинаковую структуру. Неприменимые поля равны null.

• score принимает значение от 0 до 100. Причины комбинируются так, что несколько средних сигналов складываются, не превышая 100.
• reasons перечисляет все сработавшие сигналы, начиная с самого сильного, с их весом, подробностями и понятной английской подписью, которую можно показать как есть.
• device.confidence показывает, насколько уникально выглядит устройство. Отпечатки можно подделать, поэтому мы никогда не заявляем стопроцентную уверенность.
• linked_accounts перечисляет другие аккаунты с тем же устройством, адресом выплаты или email.
• cashout заполняется только для событий cashout и показывает статус в вашей очереди проверки.

Решения и action

Ориентируйтесь на поле action, а не на decision. Пороги ниже заданы по умолчанию, их можно изменить для каждого сайта в панели.

В теневом режиме action всегда равно allow, поэтому тот же код можно безопасно выкатить до включения enforce. При переключении на enforce в вашем коде ничего не меняется.

Типы событий

Отправляйте те события, которые у вас есть. Важнее всего signup и cashout; conversion нужны для проверки скорости выполнения офферов.

Офферволы и постбэки

Конверсии офферволов приходят постбэком, сервер к серверу, без браузера. CashoutGuard связывает каждую конверсию с кликом, с которого она началась, и оценивает её по устройству и сети этого клика.

1. Когда пользователь открывает оффер

Соберите данные в браузере и отправьте offer_click с оффером и вашим id клика.

2. Когда приходит постбэк

Отправьте conversion из обработчика постбэков с тем же account_id и click_id. request_id не нужен. Передайте IP пользователя, если оффервол его сообщает.

Конверсии проверяются на: слишком быстрое выполнение для оффера, конверсию без клика, клик и конверсию из разных стран, заработок намного выше обычного дня аккаунта и повторные id транзакций.

Сети офферволов

Если у вас сеть с множеством издателей, передавайте id аккаунтов с издателем и включите «Режим сети офферволов» в разделе «Сайты». Тогда аккаунты связываются только внутри одного издателя, ведь один человек нередко пользуется сайтами нескольких ваших издателей. Формат: publisher_id:user_id

Каталог офферов

POST /v1/offers отправляет названия ваших офферов (до 1 000 за вызов). Прошлые и будущие события будут показывать настоящее название, даже если в них только id.

Коды причин

Эти коды приходят в reasons[].code. Текст показывайте модераторам, а в логике используйте код.

Веса объединяются по принципу noisy-OR: score = 100 x (1 - произведение (1 - weight/100)). Два сигнала по 40 дают 64, а не 80. Совпадение с чёрным списком всегда даёт 100.

Webhooks

Укажите URL вебхука в панели. Мы отправляем POST на каждое событие с оценкой block (event.blocked), когда аккаунт переходит в block (account.blocked) и когда команда принимает решение по выводу (cashout.decided). Игнорируйте ненужные типы.

Каждый запрос подписывается вашим секретом webhook. HMAC-SHA256 от исходного тела в hex передаётся в заголовке X-CashoutGuard-Signature

Ответьте любым статусом 2xx. Неудачные доставки повторяются до 5 раз: через 10 секунд, 1 минуту, 5 минут и 15 минут.

Статус аккаунта

GET /v1/accounts/{account_id} возвращает текущую картину риска по аккаунту, не создавая событие.

POST /v1/accounts/{account_id}/status позволяет вашим собственным инструментам модерации менять статус аккаунта.

• active: Обычная оценка.
• allowlisted: Оценка ограничена ниже порога проверки. Для доверенных пользователей и сотрудников.
• blocked: Любое событие возвращает block с оценкой 100.

Отмены и точность

POST /v1/outcomes сообщает, что стало с конверсиями после нашей оценки: отменены офферволлом или рекламодателем (chargeback) или подтверждены. Мы сопоставляем ваши id и измеряем движок на вашем трафике на странице «Точность».

Без кода: загрузите на странице «Точность» ежемесячный файл отмен от офферволлов (CSV или Excel). Колонку с id найдём сами.

PHP, Node.js, Python, Android

SDK не нужен. Достаточно обычного HTTP-запроса с коротким таймаутом. Полный пример для вывода:

• cashoutguard.php: PHP 7.4+, один файл, без Composer. Подключите через require.
• composer require cashoutguard/cashoutguard-php: тот же PHP-клиент с README для вашей папки vendor.
• npm install @cashoutguard/node: Node 18+, с типами TypeScript.
• cashoutguard-wordpress.zip: плагин WordPress: скрипт браузера на каждой странице, оценка регистраций и входов, а также хуки для выводов, конверсий офферволов и отмен.

Ошибки и лимиты

Fail open: если вызов завершился таймаутом или ошибкой, разрешите действие и запишите это в лог. Никогда не позволяйте нашему сбою останавливать ваших пользователей.