Ping back URL: Difference between revisions

From Wiki Kaminari Click
No edit summary
(Marked this version for translation)
 
(14 intermediate revisions by the same user not shown)
Line 2: Line 2:
<translate>
<translate>
<!--T:1-->
<!--T:1-->
If you want to receive the verification results for each click on your URL, you can do so using the '''Ping-back URL''' option.
For a walkthrough of Ping-back URL setup, watch the short video:
https://www.loom.com/share/e3d1505a0bf34557bfb9e3cfc934c9b7
 
<!--T:22-->
If you want to receive the verification results for each click on your own URL, you can do so using the '''Ping-back URL''' option.


<!--T:2-->
<!--T:2-->
= Option activation =
= Option activation =
Request the activation of the '''Ping-back URL''' option from your manager for your integration.
Ask your manager to activate the '''Ping-back URL''' option on your integration.


<!--T:7-->
<!--T:7-->
Line 15: Line 19:


<!--T:8-->
<!--T:8-->
To understand which impression we've checked, you need to mark it. If you have an '''JS check'''-type integration, add the <code>kmnrId</code> key to <code>window.kmnr</code> with any unique identifier convenient for you. By this identifier you can later recognize the impression.
== kmnrId ==
To understand which impression we've checked, you need to mark it.  
 
<!--T:14-->
If you have an '''JS check'''-type integration, add the <code>kmnrId</code> key to <code>window.kmnr</code> with any unique identifier convenient for you. By this identifier you can later recognize the impression.


<!--T:9-->
<!--T:9-->
Line 29: Line 37:
Acceptable characters: [A-Za-z0-9_] Latin letters, Arabic numerals, underscore. Maximum length is 200 characters.
Acceptable characters: [A-Za-z0-9_] Latin letters, Arabic numerals, underscore. Maximum length is 200 characters.


<!--T:4-->
== Testing your endpoint == <!--T:4-->
 
<!--T:16-->
You can verify that your ping-back endpoint is working with the following curl command:
 
<!--T:17-->
curl -v -X POST -k 'https://example.com/ping-back' \
  -H 'content-type: application/json' \
  --data-raw '{"kmnrId":"50d9ecc6-402b-4a74-9397-fc20f2980567","kmnrKey":111111111,"fraud":1,"block":0,"reason":"Spoofing","sub1":"sub1 value","sub2":"sub2 value","sub3":"sub3 value","sub4":"","sub5":"","sub6":"","sub7":""}'
 
<!--T:18-->
Replace:
 
<!--T:19-->
* <code>https://example.com/ping-back</code> — your ping-back URL
* <code>111111111</code> — your kmnrKey
* <code>50d9ecc6-402b-4a74-9397-fc20f2980567</code> — any random kmnrId
 
<!--T:20-->
The request should return HTTP 200.
 
<!--T:21-->
= Response format =
= Response format =
After receiving, processing the data, and making a decision about the bot status of the click, we send the decision to you in JSON POST format. <code>{ kmnrId: 111111111, fraud: 1, block: 1 }</code>
After receiving, processing the data, and making a decision about the bot status of the click, we send the decision to you in JSON POST format.  
<pre>{
  "kmnrId": "50d9ecc6-402b-4a74-9397-fc20f2980567",
  "kmnrKey": 111111111,
  "fraud": 1,
  "block": 1,
  "sub1": "sub1 value",
  "sub2": "sub2 value",
  "sub3": "sub3 value",
  "sub4": 444,
  "sub5": 555,
  "sub6": "",
  "sub7": ""
}</pre>


<!--T:13-->
<!--T:13-->
Line 45: Line 87:
| kmnrKey || Integration identifier
| kmnrKey || Integration identifier
|-
|-
| fraud || 1 if the hit is fraudulent, 0 if the hit is non-fraudulent, -1 if the hit could not be verified
| fraud || 1 if the hit is fraudulent, 0 if the hit is non-fraudulent,
|-
|-
| block || 1 if the hit was blocked according to the integration settings, 0 if the hit wasn't blocked
| block || 1 if the hit was blocked according to the integration settings, 0 if the hit wasn't blocked
|-
| reason || The IVT category name as shown in the statistics: Crawlers, Spoofing, Automated, Incorrect requests, Bad reputation IP. Empty string for clean hits.
|-
|-
| sub1 || Sub-tags that were sent with the hit
| sub1 || Sub-tags that were sent with the hit
Line 64: Line 108:
|}
|}


If you receive a ping-back, your server should respond with a status 200. Otherwise, we make three more attempts to send the request. If it was not possible to send a ping-back, we save it in an internal log and can provide it to you upon request.
<!--T:15-->
If you receive a ping-back, your server should respond with a status 200. Otherwise, we make three more attempts to send the request. If the ping-back still cannot be delivered, you can always retrieve the status for any click via our API, which serves as the reliable source of truth regardless of delivery success.


<!--T:6-->
<!--T:6-->

Latest revision as of 08:01, 17 September 2026

Other languages:

For a walkthrough of Ping-back URL setup, watch the short video: https://www.loom.com/share/e3d1505a0bf34557bfb9e3cfc934c9b7

If you want to receive the verification results for each click on your own URL, you can do so using the Ping-back URL option.

Option activation

Ask your manager to activate the Ping-back URL option on your integration.

Once enabled, specify your URL in the settings.

Ping back url.png

kmnrId

To understand which impression we've checked, you need to mark it.

If you have an JS check-type integration, add the kmnrId key to window.kmnr with any unique identifier convenient for you. By this identifier you can later recognize the impression.

Ping back url2.png

If you have an Redirect-type integration, add kmnrId to URL: 

https://kaminari.systems/v1/click?kmnrKey=111111111&kmnrId=IMPRESSION_UNIQ_ID&u=https%3A%2F%2Fsome.url

Acceptable characters: [A-Za-z0-9_] Latin letters, Arabic numerals, underscore. Maximum length is 200 characters.

Testing your endpoint

You can verify that your ping-back endpoint is working with the following curl command:

curl -v -X POST -k 'https://example.com/ping-back' \ 

 -H 'content-type: application/json' \
 --data-raw '{"kmnrId":"50d9ecc6-402b-4a74-9397-fc20f2980567","kmnrKey":111111111,"fraud":1,"block":0,"reason":"Spoofing","sub1":"sub1 value","sub2":"sub2 value","sub3":"sub3 value","sub4":"","sub5":"","sub6":"","sub7":""}'

Replace:

The request should return HTTP 200.

Response format

After receiving, processing the data, and making a decision about the bot status of the click, we send the decision to you in JSON POST format. 

{
   "kmnrId": "50d9ecc6-402b-4a74-9397-fc20f2980567",
   "kmnrKey": 111111111,
   "fraud": 1,
   "block": 1,
   "sub1": "sub1 value",
   "sub2": "sub2 value",
   "sub3": "sub3 value",
   "sub4": 444,
   "sub5": 555,
   "sub6": "",
   "sub7": ""
}

By kmnrId and sub-tags you can find the impression in your stat.

Name Value
kmnrId Unique identifier convenient for you
kmnrKey Integration identifier
fraud 1 if the hit is fraudulent, 0 if the hit is non-fraudulent,
block 1 if the hit was blocked according to the integration settings, 0 if the hit wasn't blocked
reason The IVT category name as shown in the statistics: Crawlers, Spoofing, Automated, Incorrect requests, Bad reputation IP. Empty string for clean hits.
sub1 Sub-tags that were sent with the hit
sub2 ...
sub3 ...
sub4 ...
sub5 ...
sub6 ...
sub7 ...

If you receive a ping-back, your server should respond with a status 200. Otherwise, we make three more attempts to send the request. If the ping-back still cannot be delivered, you can always retrieve the status for any click via our API, which serves as the reliable source of truth regardless of delivery success.

Retrieved from "https://wiki.kaminari.click/index.php?title=Ping_back_URL&oldid=1604"