Measurement API

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}?

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.

Note:

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:

Caution - 

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

  1. Open the TrafficGuard Portal
  2. If you are an Agency user, select the organisation to which you want to add the app
  3. Go to Settings from the side navigation
  4. 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.