Meta redirect s2s en
Integration is designed for serious solutions where click analysis is required and their loss is unacceptable. Server-2-server ping allows you to connect your data with the results of Kaminari verification.
General workflow
- The user arrives at your website. You generate a unique
kmnrIdand send it to Kaminari server via /ping URL, and we save the data in the cache. - Then you redirect the user to us for verification, adding that same
kmnrIdto the URL. - We check the user and determine their fraud status.
- Then we check the cache:
- If there is a record with a similar
kmnrId(coming from /ping), we merge the data from the cache with the verification results, write them to statistics, and send you thekmnrIdand verification result on pingBackUrl. If the click is fraudulent, you can immediately mark it, for example, as non-payable. - If there is no record with that
kmnrId, we wait up to five minutes. If the second record still does not come, we write what we have to the statistics, and send you thekmnrIdand verification result on pingBackUrl. - We also periodically check the cache, and if there are expired clicks that came to /ping and remained unpaired, we send you unverified result on pingBackUrl. If we couldn't verify them, we write them to statistics with the status of "Technical losses".
- If there is a record with a similar
Integration setup
General settings
General information on setting up integration can be found here: General settings
Target URL and link text
If you have a permanent target link or it's passed in some parameter, you can specify it in the integration settings. You can also specify the text of the click-through link.
If you insert a link, be sure to click the Encode button to make it safe for the URL.
If you specify an external parameter, you don't need to press the Encode button.
Another option.
Ping-back URL
Here, you need to specify the address to which we will tap for the verification results.
Client-side setup
Sending data to https://kaminari.systems/v2/ping
When a user comes to the page, it is necessary to send initializing information to the URL https://kaminari.systems/v2/ping in the background.
The data should be sent in JSON format.
List of parameters:
| Parameter Name | Parameter Description | Mandatory? |
|---|---|---|
| kmnrId | Random impression identifier. Generated on the client side. It can be anything - UUID, random number, random string of text. Must be sent as a string. | yes |
| kmnrKey | Integration identifier within which the impression is analyzed. | yes |
| sub1 | Filled sub-tags. If you do not use certain tags, there is no need to send them. | no |
| sub2 | ... | no |
| sub3 | ... | no |
| sub4 | ... | no |
| sub5 | ... | no |
| sub6 | ... | no |
| sub7 | ... | no |
| sub8 | ... | no |
| sub9 | ... | no |
| sub10 | ... | no |
In addition, the following headers obtained from the user should be added to this request:
| Parameter Name | Parameter Description |
|---|---|
| user-agent | User agent |
| referer | Page the user came from |
| accept-language | Browser interface language |
| x-original-ip | IP |
| x-forwarded-for | IP |
| x-real-ip | IP |
Example:
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 '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
Redirecting the user to Clickworker
The user should be redirected to a page where our JS script can gather data about them. There are two options - use our Clickworker or implement your own.
With our Clickworker
Redirect the user to https://kaminari.systems/v1/click. The following fields must be added to the GET request:
| Parameter Name | Parameter Description |
|---|---|
| kmnrId | kmnrId, generated when hitting https://kaminari.systems/v2/ping. Needed to glue clicks together. |
| kmnrKey | Integration ID for the ad being analyzed. |
| sub1 | Filled sub-tags. If you're not using certain tags, there's no need to send them. |
| sub2 | ... |
| sub3 | ... |
| sub4 | ... |
| sub5 | ... |
| sub6 | ... |
| sub7 | ... |
| sub8 | ... |
| sub9 | ... |
| sub10 | ... |
| u | Target URL to which the user will be sent after verification. It should be in URL-safe form (for example, processed with the JS encodeURIComponent method). |
Example:
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
With your clickworker
You need your own clickworker so that all manipulations take place on one domain. In this case, there will be no losses on redirects. And there will also be no delays in network requests because the script is placed directly on the page.
The clickworker code must be stored on the client side and pulled from us periodically for updates.
The clickworker can be downloaded from the link: https://kaminari.systems/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}. And then replace the {foo} templates with your values when delivering it to the client.
| Parameter Name | Parameter Description |
|---|---|
| kmnrId | kmnrId, generated when hitting https://kaminari.systems/v2/ping. Needed to glue clicks together. |
| kmnrKey | Integration ID for the ad being analyzed. |
| sub1 | Filled sub-tags. If you're not using certain tags, there's no need to send them. |
| sub2 | ... |
| sub3 | ... |
| sub4 | ... |
| sub5 | ... |
| sub6 | ... |
| sub7 | ... |
| sub8 | ... |
| sub9 | ... |
| sub10 | ... |
| u | Target URL to which the user will be sent after verification. It should be in URL-safe form (for example, processed with the JS encodeURIComponent method). |
| checkUrl | The URL that proxies our click verification endpoint on your domain. |
The clickworker must return the following headers:
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: *
Sending the verification result
After the script finishes the verification, it sends the data to https://kaminari.systems/v2/check. If you want everything to work more reliably, you can proxy this URL on your domain. And then everything will happen within one domain.
You need to specify your endpoint in the checkUrl template when downloading the clickworker (see example above).
Nginx configuration
You need to add to the http block:
upstream antifraud {
server kaminari.click;
keepalive 10;
}
You need to add to the config (the example shows the option of proxying to the /antifraud endpoint):
location /antifraud {
rewrite /antifraud /v2/check break;
proxy_set_header Host kaminari.click;
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.click;
}
Ping back
After we receive and process the data, we send it back to you at the Ping back URL (specified in the integration settings) in JSON POST format: { kmnrId, fraud }
| Parameter Name | Parameter Description |
|---|---|
| kmnrId | kmnrId, generated when hitting https://kaminari.systems/v2/ping. Needed to glue clicks together. |
| fraud | 0 if the click is non-fraud, 1 if the click is fraud, -1 if the click cannot be verified. |