Latest revision as of 11:18, 9 June 2023

THIS PAGE IS DEPRECATED!

Интеграция предназначена для серьёзных решений, где необходим анализ кликов и недопустима их потеря. Server-2-server ping позволяет соединить ваши данные с результатами проверки Kaminari.

Общий алгоритм работы

Пользователь приходит на ваш сайт. Вы генерируете уникальный kmnrId и отстукиваетесь с ним на сервер Kaminari на URL /ping, мы сохраняем данные в кэш.
Затем вы отправляете пользователя к нам на проверку, добавив в URL тот самый kmnrId.
Мы проверяем пользователя и вычисляем его фродовый статус.
Дальше мы проверяем в кэше:
1. Если там есть запись с аналогичным kmnrId (пришедшая на /ping), мы склеиваем данные из кеша с результатами проверки и пишем их в статистику, а также отсылаем вам на pingBackUrl kmnrId и результат проверки. Если клик фродовый, вы можете сразу пометить его, например, как неподлежащий оплате.
2. Если записи с таким kmnrId нет, мы ждём до пяти минут. Если вторая запись так и не приходит, мы пишем в статистику то, что есть, а также отсылаем вам на на pingBackUrl kmnrId и результат проверки.
3. Так же мы периодически проверяем кэш и если там находятся просроченные клики, пришедшие на /ping и так и оставшиеся без пары, мы отстукиваемся о них вам на pingBackUrl. Если нам не удалось никак их проверить, мы пишем их в стату со статусом «Технические потери».

Настройка интеграции

Общие настройки

Общая информация по настройке интеграции находится здесь: General settings

Target URL и текст ссылки

Если у вас есть постоянная целевая ссылка, или она передаётся в каком-то параметре, можете указать её в настройках интеграции. Также можете указать текст кликовой ссылки.

Если вы вставляете ссылку, обязательно нажмите кнопку Encode, чтобы она стала безопасной для URL.

Если указываете внешний параметр, кнопку Encode нажимать не надо.

Другой вариант.

Ping-back URL

Здесь надо указать адрес, на который мы будем отстукиваться с результатами проверки.

Настройка на стороне клиента

Отправка данных на https://kaminari.systems/v2/ping

Когда пользователь приходит на страницу необходимо в фоне послать на URL https://kaminari.systems/v2/ping инициализирующую информацию.

Данные должны слаться в формате JSON.

Список параметров.

Название	Описание параметра	Обязательный?
kmnrId	Рандомный идентификатор показа. Генерируется на стороне клиента. Это может быть всё, что угодно — UUID, случайное число, случайная текстовая строка. Должна слаться в виде строки.	да
kmnrKey	Идентификатор интеграции, в рамках которой анализируется показ.	да
sub1	Заполенные суб-метки. Если какие-то метки вы не используете, их слать не обязательно.	нет
sub2	...	нет
sub3	...	нет
sub4	...	нет
sub5	...	нет
sub6	...	нет
sub7	...	нет
sub8	...	нет
sub9	...	нет
sub10	...	нет

Также в этот запрос должны быть добавлены следующие заголовки, полученные от пользователя:

Название	Описание
user-agent	user agent пользователя
referer	страница, с которой пришёл пользователь
accept-language	язык интерфейса браузера
x-original-ip	реальный IP пользователя
x-forwarded-for	IP
x-real-ip	IP

Пример:

curl 'https://kaminari.systems/v2/ping' \
  -H 'accept: application/json' \ 
  -H 'accept-language: en-US,en;q=0.9' \ 
  -H 'cache-control: no-cache' \ 
  -H 'content-type: text/plain;charset=UTF-8' \
  -H 'origin: https://test.com' \ 
  -H 'pragma: no-cache' \ 
  -H 'referer: https://test.com/' \ 
  -H 'user-agent: Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36' 
  --data-raw '{"kmnrKey":"xxxxxxxxx","kmnrId":"1125570260","sub1":"test","sub2":"1001","sub3":"10","sub4":"1385282124113622","sub5":"222","sub6":"555666","sub7":"8833705265931305","sub8":"94839150"}' 
  --compressed

Перенаправление пользователя на кликворкер

Пользователя надо отправить на страницу, где наш JS-скрипт сможет собрать о нём данные. Есть два варианта — воспользоваться нашим кликворкером, или реализовать свой.

С нашим кликворкером

Перенаправьте пользователя на https://kaminari.systems/v1/click. В GET-запрос надо добавить следующие поля:

Название	Описание
kmnrId	kmnrId, сгенерированный при отстуке на https://kaminari.systems/v2/ping. Нужен для склеивания кликов.
kmnrKey	Идентификатор интеграции, в рамках которой анализируется показ.
sub1	Заполенные суб-метки. Если какие-то метки вы не используете, их слать не обязательно.
sub2	...
sub3	...
sub4	...
sub5	...
sub6	...
sub7	...
sub8	...
sub9	...
sub10	...
u	целевая ссылка, на которую пользователь будет отправлен после проверки. Должна быть в URL-безопасном виде (например, обработана JS-методом encodeURIComponent).

Пример:

https://kaminari.systems/v1/click?kmnrKey=930824531&kmnrId=123456789&sub1=test&sub2=1001&sub3=10&sub4=1385282124113622&sub5=222&sub6=555666&sub7=8833705265931305&u=https%3A%2F%2Ftest.com

Со своим кликворкером

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

Код кликворкера должен храниться на стороне клиента и с какой-то периодичностью подтягиваться от нас для обновления.

Кликворкер можно скачать по ссылке: https://kaminari.space/v1/click?kmnrKey={kmnrKey}&kmnrId={kmnrId}&sub1={sub1}&sub2={sub2}&sub3={sub3}&sub4={sub4}&sub5={sub5}&sub6={sub6}&sub7={sub7}&sub8={sub8}&sub9={sub9}&sub10={sub10}&u={clickUrl}&checkUrl={clickUrl}. И затем при отдаче клиенту заменять шаблоны {foo} своими значениями.

Название	Описание
kmnrId	kmnrId, сгенерированный при отстуке на https://kaminari.systems/v2/ping. Нужен для склеивания кликов.
kmnrKey	Идентификатор интеграции, в рамках которой анализируется показ.
sub1	Заполенные суб-метки. Если какие-то метки вы не используете, их слать не обязательно.
sub2	...
sub3	...
sub4	...
sub5	...
sub6	...
sub7	...
sub8	...
sub9	...
sub10	...
u	целевая ссылка, на которую пользователь будет отправлен после проверки. Должна быть в URL-безопасном виде (например, обработана JS-методом encodeURIComponent).
checkUrl	URL, проксирующий на вашем домене наш эндпойнт проверки клика.

Кликворкер должен отдавать следующие заголовки:

accept-ch: Width, Viewport-Width, DPR, Device-Memory, Downlink, RTT, ECT, Save-Data, Sec-CH-UA-Arch, Sec-CH-UA-Bitness, Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA, Sec-CH-UA-Full-Version
access-control-allow-headers: X-Requested-With, Cache-Control, Content-Type
access-control-allow-methods: GET, POST, OPTIONS
access-control-allow-origin: *

Отправка результата проверки

После того, как скрипт закончит проверку он отправляет данные на https://kaminari.systems/v2/check. Если вы хотите чтобы всё работало надёжнее, можно проксировать этот URL на своём домене. И тогда всё будет происходить в рамках одного домена.

Ваш эндпойнт надо указать в шаблоне checkUrl при скачивании кликворкера (см. пример выше).

Настройка для Nginx

В блок http надо добавить:

upstream antifraud {
    server kaminari.systems;
    keepalive 10;
}

В конфиг надо добавить (в примере показан вариант с проксированием на эндпойнт /antifraud):

location /antifraud {
    rewrite /antifraud /v2/check break;
    proxy_set_header Host kaminari.systems;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header X-Forwarded-For $http_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-KUser-IP $http_x_real_ip;
    proxy_pass http://kaminari.systems;
}

Ping back

После того, как мы получили и обработали данные мы отсылаем их вам на Ping back url (он указывается в настройках интеграции) в формате JSON POST. { kmnrId, fraud }

Название	Значение
kmnrId	kmnrId, сгенерированный при отстуке на https://kaminari.systems/v2/ping
fraud	0 если клик нефродовый, 1 если клик фродовый, -1 если клик не удалось проверить