Meta redirect s2s: Difference between revisions

From Wiki Kaminari Click
No edit summary
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
Интеграция предназначена для серьёзных решений без потери кликов.
<br />
== THIS PAGE IS DEPRECATED! ==
<br />
<br />


== Настройка интеграции ==
[[Meta redirect s2s en|English version]]
 
Интеграция предназначена для серьёзных решений, где необходим анализ кликов и недопустима их потеря. Server-2-server ping позволяет соединить ваши данные с результатами проверки Kaminari.
 
= Общий алгоритм работы =
# Пользователь приходит на ваш сайт. Вы генерируете уникальный <code>kmnrId</code> и отстукиваетесь с ним на сервер Kaminari на URL /ping, мы сохраняем данные в кэш.
# Затем вы отправляете пользователя к нам на проверку, добавив в URL тот самый <code>kmnrId</code>.
# Мы проверяем пользователя и вычисляем его фродовый статус.
# Дальше мы проверяем в кэше:
## Если там есть запись с аналогичным <code>kmnrId</code> (пришедшая на /ping), мы склеиваем данные из кеша с результатами проверки и пишем их в статистику, а также отсылаем вам на pingBackUrl <code>kmnrId</code> и результат проверки. Если клик фродовый, вы можете сразу пометить его, например, как неподлежащий оплате.
## Если записи с таким <code>kmnrId</code> нет, мы ждём до пяти минут. Если вторая запись так и не приходит, мы пишем в статистику то, что есть, а также отсылаем вам на на pingBackUrl <code>kmnrId</code> и результат проверки.
## Так же мы периодически проверяем кэш и если там находятся просроченные клики, пришедшие на /ping и так и оставшиеся без пары, мы отстукиваемся о них вам на pingBackUrl. Если нам не удалось никак их проверить, мы пишем их в стату со статусом «Технические потери».
 
= Настройка интеграции =


=== Общие настройки ===
=== Общие настройки ===
Line 21: Line 37:
[[File:Meta redirect 7.png]]
[[File:Meta redirect 7.png]]


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


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


Данные должны слаться в формате JSON.
Данные должны слаться в формате JSON.
Line 34: Line 53:
! Название !! Описание параметра !! Обязательный?
! Название !! Описание параметра !! Обязательный?
|-
|-
| kmnrId || Рандомный идентификатор показа. Генерируется на стороне клиента. Это может быть всё, что угодно — UUID, случайное число, случайная текстовая строка. || да
| kmnrId || Рандомный идентификатор показа. Генерируется на стороне клиента. Это может быть всё, что угодно — UUID, случайное число, случайная текстовая строка. '''Должна слаться в виде строки.''' || да
|-
|-
| kmnrKey || Идентификатор интеграции, в рамках которой анализируется показ. || да
| kmnrKey || Идентификатор интеграции, в рамках которой анализируется показ. || да
Line 70: Line 89:
| accept-language || язык интерфейса браузера
| accept-language || язык интерфейса браузера
|-
|-
| x-original-ip || IP
| x-original-ip || реальный IP пользователя
|-
|-
| x-forwarded-for || IP
| x-forwarded-for || IP
Line 79: Line 98:
Пример:
Пример:
<pre>
<pre>
curl 'https://kaminari.click/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 'sec-ch-ua: "Google Chrome";v="105", "Not)A;Brand";v="8", "Chromium";v="105"' -H 'sec-ch-ua-mobile: ?0' -H 'sec-ch-ua-platform: "Windows"' -H 'sec-fetch-dest: empty' -H 'sec-fetch-mode: no-cors' -H 'sec-fetch-site: cross-site' -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
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
</pre>
</pre>


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


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


{| class="wikitable"
{| class="wikitable"
Line 92: Line 121:
! Название !! Описание
! Название !! Описание
|-
|-
| kmnrId || kmnrId, сгенерированный при отстуке на https://kaminari.click/v2/ping. Нужен для склеивания кликов.
| kmnrId || kmnrId, сгенерированный при отстуке на https://kaminari.systems/v2/ping. Нужен для склеивания кликов.
|-
|-
| kmnrKey || Идентификатор интеграции, в рамках которой анализируется показ.
| kmnrKey || Идентификатор интеграции, в рамках которой анализируется показ.
Line 121: Line 150:
Пример:
Пример:
<pre>
<pre>
https://kaminari.click/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.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
</pre>
</pre>


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


Код кликворкера должен храниться на стороне клиента и с какой-то периодичностью подтягиваться от нас для обновления.
Код кликворкера должен храниться на стороне клиента и с какой-то периодичностью подтягиваться от нас для обновления.
Кликворкер можно скачать по ссылке: <code>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}</code>. И затем при отдаче клиенту заменять шаблоны {foo} своими значениями.
{| class="wikitable"
|-
! Название !! Описание
|-
| kmnrId || kmnrId, сгенерированный при отстуке на https://kaminari.systems/v2/ping. Нужен для склеивания кликов.
|-
| kmnrKey || Идентификатор интеграции, в рамках которой анализируется показ.
|-
| sub1 || Заполенные суб-метки. Если какие-то метки вы не используете, их слать не обязательно.
|-
| sub2 || ...
|-
| sub3 || ...
|-
| sub4 || ...
|-
| sub5 || ...
|-
| sub6 || ...
|-
| sub7 || ...
|-
| sub8 || ...
|-
| sub9 || ...
|-
| sub10 || ...
|-
| u || целевая ссылка, на которую пользователь будет отправлен после проверки. Должна быть в URL-безопасном виде (например, обработана JS-методом [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent encodeURIComponent]).
|-
| checkUrl || URL, проксирующий на вашем домене наш эндпойнт проверки клика.
|}


Кликворкер должен отдавать следующие заголовки:
Кликворкер должен отдавать следующие заголовки:
Line 136: Line 200:
access-control-allow-origin: *
access-control-allow-origin: *
</pre>
</pre>
{%l= clickUrl %} - URL, на который скрипт отправит данные
{%l= trafficBackUrl %} - заполняем мы


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


<code>
Ваш эндпойнт надо указать в шаблоне checkUrl при скачивании кликворкера (см. пример выше).
map $antifraud $antifraud_host {
antifraud_new kaminari.space;
antifraud kadam-antifraud.com;
}


split_clients $request_id $antifraud {
===== Настройка для Nginx =====
     100%    antifraud_new;
В блок http надо добавить:
     *      antifraud;
<pre>
upstream antifraud {
     server kaminari.systems;
     keepalive 10;
}
}
</pre>


map $request_uri $url_type {
В конфиг надо добавить (в примере показан вариант с проксированием на эндпойнт /antifraud):
default other;
<pre>
~*^/cnt antifraud;
location /antifraud {
}
    rewrite /antifraud /v2/check break;
 
    proxy_set_header Host kaminari.systems;
location /cnt/api/index {
    proxy_http_version 1.1;
access_log /var/log/nginx/antifrod_access.log main;
    proxy_set_header Connection "";
rewrite /cnt/(.*) /$1 break;
    proxy_set_header X-Forwarded-For $http_x_forwarded_for;
root /var/www/html/collectrom.com/current/public;
proxy_set_header Host $antifraud_host;
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-Real-IP $remote_addr;
     proxy_set_header X-KUser-IP $http_x_real_ip;
     proxy_set_header X-KUser-IP $http_x_real_ip;
proxy_pass http://$antifraud;
    proxy_pass http://kaminari.systems;
}
}
</code>
</pre>


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


Данные обрабатываются, пишутся в КХ, на Ping back url (указывается в настройках) шлётся fraud и то, что пришло на /ping
{| class="wikitable"
req.Header.SetContentType(ApplicationJSON)
|-
req.Header.SetMethod("POST")
! Название !! Значение
|-
| kmnrId || kmnrId, сгенерированный при отстуке на https://kaminari.systems/v2/ping
|-
| fraud || 0 если клик нефродовый, 1 если клик фродовый, -1 если клик не удалось проверить
|}

Latest revision as of 11:18, 9 June 2023


THIS PAGE IS DEPRECATED!



English version

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

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

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

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

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

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

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

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

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

Meta redirect 6.png

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

Meta redirect 8.png

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

Meta redirect 7.png

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 если клик не удалось проверить
Retrieved from "https://wiki.kaminari.click/index.php?title=Meta_redirect_s2s&oldid=254"