Introduction
You can track, measure and validate impressions, clicks and events in real-time via TrafficGuard measurement API.
Measurement API
The measurement API is comprised of a number of parts, including the base URL, parameters, and values associated with those parameters:
Base URL
This is the domain for the click which always includes the api subdomain. Both HTTP and HTTPS are supported, we recommend data be sent securely with the HTTPS protocol.
You can send data using either POST or GET requests.
GET https://api.trafficguard.ai/api/v1/validate/{request_type}?
💡 Tip
Recommended - POST requests
Using POST
We recommend sending data via POST because it allows for a larger payload. When using POST, issue the following HTTP request:
POST https://api.trafficguard.ai/api/v1/validate/{request_type}
Body: {payload_data}Where:
{request_type} - The type of request from the allowed API request types
{payload_data} - The BODY of the post request. The body must include exactly 1 transaction's payload in valid JSON format and must be no longer than 8192 bytes.
💡 Tip
The payload must be sent in application/json format.
API request types
| API Request Type |
impression | ad impression |
click | ad click |
event | installs and in-app event |
Sending required values
The following parameters are required for each payload:
💡 Tip
Ad network clients are required to pass the 'advertiser_identifier' parameter (which is configured in your advertiser property settings) instead of the 'property_id'. This is a unique identifier for the advertiser on your end.
organisation_id // Organisation ID
property_id // Property ID
api_key // Authentication secret provided by TrafficGuard
session_id // Session ID. A unique identifier for the user e.g. IDFA
ip_address // IP address of the end users device on the click
user_agent // User-Agent of the end users device on the click
source_id // ID of you traffic source, partner, publisher, or network
click_time // click time
Each payload must contain a valid request type and each request type has its own set of required fields. For example to validate a click for a mobile campaign, you would use the following POST payload:
POST https://api.trafficguard.ai/api/v1/validate/click
{
"organisation_id": "test_organisation",
"property_id": "tg-124565-1",
"api_key": "1fds4d",
"session_id": "4bd700e5-bb4b-4387-8b2f-a5fd0494bf25",
"ip_address": "94.139.94.200",
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 12_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/16B92",
"source_id": "709610",
"click_time": "2018-11-07T03:25:14Z"
}
Or you would use the following GET request:
/click?organisation_id=test_organisation&property_id=tg-124565-1&api_key=1fds4d&session_id=4bd700e5-bb4b-4387-8b2f-a5fd0494bf25&user_ip=94.139.94.200&user_agent=Mozilla/5.0%20(iPhone;%20CPU%20iPhone%20OS%2012_1%20like%20Mac%20OS%20X)%20AppleWebKit/605.1.15%20(KHTML,%20like%20Gecko)%20Mobile/16B92&source_id=709610&click_time=2018-11-07T03:25:14+0000
Required values for certain request types
Some parameters may only be sent with specific request types. For example, the event type requires that the event_time and event_name also be set. The Measurement parameter reference describes which parameters are required for which request type.
Authentication
The API requires you to authenticate via a secret token. You should set the &api_key to the api_key value. As this token is passed on the server-side it will never be exposed to the end user.
API key
Open the TrafficGuard Portal
If you are an Agency user, select the organisation to which you want to add the app
Go to Settings from the side navigation
Click Copy API key
URL encoding values
All values sent to TrafficGuard must be UTF-8 encoded. All values sent via GET requests must be URL encoded. To send the user agent via a GET request, it will need to be URL encoded, resulting in the final string:
user_agent=Mozilla/5.0%20(iPhone;%20CPU%20iPhone%20OS%2012_1%20like%20Mac%20OS%20X)%20AppleWebKit/605.1.15%20(KHTML,%20like%20Gecko)%20Mobile/16B92
Response codes
We return a HTTP 2xx response for all valid API requests.
Bad requests (e.g., a request containing a malformed or corrupt payload) will return HTTP 4xx. You should NOT retry the request. Instead, you should stop and correct any errors in your HTTP request.
Responses
{
"status_code": 200,
"message" : "success",
"execution_time_ms": 30,
"results": {
"transaction_status": "invalid",
"reason": "known_hosts_ip_global"
}
}Rate limits
There is no hard rate limit on the TrafficGuard measurement API. However, we ask you let us know if you need to measure at a rate exceeding 500 requests per second.
Caching and sampling
We strongly advise against caching API responses in your application or site or sampling events to measure. TrafficGuard does its best work with all the data points of user interaction and as TrafficGuard is determining the difference between real and none real users in real-time you may introduce false positives from cached data.
Privacy by design
Impression
organisation_id // Organisation ID
property_id // Property ID
api_key // Authentication secret provided by TrafficGuard
session_id // Session ID. A unique identifier for the user e.g. IDFA
user_ip // IP address of the end users device on the impression
user_agent // User-Agent of the end users device on the impression
source_id // ID of you traffic source, partner, publisher, or network
site_id // ID of the site or mobile app where the user was engaged
creative_type // Type of ad creative
creative_id // Identifier of the ad creative
webpage_url // Where the impression happened
destination_url // Where the click is going to redirect
http_referrer // The referrer URL of the click, HTTP_REFERER of the request headers
Click
organisation_id // Organisation ID
property_id // Property ID
api_key // Authentication secret provided by TrafficGuard
session_id // Session ID. A unique identifier for the user e.g. IDFA
user_ip // IP address of the end users device on the click
user_agent // User-Agent of the end users device on the click
source_id // ID of you traffic source, partner, publisher, or network
site_id // ID of the site or mobile app where the user was engaged
click_time // The time of the click ISO 8601
http_referrer // The referrer URL of the click, HTTP_REFERER of the request headers
Event
organisation_id // Organisation ID
property_id // Property ID
api_key // Authentication secret provided by TrafficGuard
session_id // Session ID. A unique identifier for the user e.g. IDFA
user_ip // IP address of the end users device on the event
user_agent // User-Agent of the end users device on the event
source_id // ID of you traffic source, partner, publisher, or network
event_time // The time of the event ISO 8601
event_name // Name of the event as defined by TrafficGuard
goal_id // This can be used when event_name=goal, to send the measurement platform’s event ID or name
event_param // Additional meta information related to the event parameter/s
event_revenue_usd // Event revenue in USD
is_conversion // Is the event a conversion? 0 = no, 1 = yes
Parameters reference
For a full reference, please visit developer reference page
Unique identifier parameters (highly recommended)
aaid // Android only. Android advertiser unique identifier
idfa // iOS Only - iOS unique identifier
Campaign metadata parameters
agency_id // ID of the agency
campaign_id // Campaign name or ID
sub_source_id // Identifier of the sub-source or sub-publisher
site_id // ID of the site or mobile app where the user was engaged
placement_id // Identifier of the ad placement
creative_type // Type of ad creative
creative_set_id // Identifier of the ad creative set
creative_id // Identifier of the ad creative
section_id // Identifier of section of the ad placement
is_retargeting // Is the engagement a result of a retargeting campaign
click_lookback // The maximum lookback attribution period of an install
keyword= // keyword
App parameters
app_id // App package name as it appears in the store
app_version // App version
Additional parameters
sub_param_1 // Custom Parameter 1
sub_param_2 // Custom Parameter 2
sub_param_3 // Custom Parameter 3
sub_param_4 // Custom Parameter 4
sub_param_5 // Custom Parameter 5
Device parameters
user_ip // IP address of the device collected
user_agent // User-Agent of the device collected
Request parameters
http_referrer // IP address of the device collected
destination_url // Where the click is going to redirect
webpage_url // Where the impression happened
Timing parameters
click_time // The time of the click ISO 8601
click_time_milliseconds // The time of the click (Milliseconds since the Unix Epoch)
install_time // The time of the install ISO 8601
install_time_milliseconds // The time of the install (Milliseconds since the Unix Epoch)
event_time // The time of the event ISO 8601
event_time_milliseconds // The time of the event (Milliseconds since the Unix Epoch)
Cost data parameters
cost_model // The model cost is calculated by
cost_value_usd // Cost in USD
cost_event_name // The event that cost should be applied to if cost model is CPE
Data privacy parameters
gdpr // GDPR Consent passing
gdpr_consent // GDPR Consent passing - Encodes the consented-to purposes and vendor consent string, as obtained from the CMP JS API or OpenRTB.
gdpr_pd // GDPR Consent passing - for generic URL parameters, gdpr_pd=0 indicates none of them contain personal data (from the perspective of the callee). For "defined" URL parameters, their definition should define whether they include personal data.