The Adform API enables clients to leverage site-tracking capabilities while sending tracking events server-side. As illustrated in the diagram below, tracking points are sent from the client’s (Adform customer) or third-party tag manager's server (A) directly to Adform servers (B) without any direct interaction with the user’s browser (C).
Server-Side Tracking Advantages
-
Fewer tracking scripts on advertisers' websites (the user's browser can block a high number of tracking scripts, and it can result in long loading times).
-
More control over what data is collected by Adform.
-
No browser compatibility issues.
-
Doesn't contribute to advertiser site latency, since no tracking script is loaded in the user's browser.
Server-Side Tracking Considerations
Direct control over data means that you must configure each needed parameter to be sent (no context is being captured automatically). To attribute conversions, one of the identifiers must be passed:
-
cookieId: Adform third-party cookie ID. -
advertisingId: Mobile Advertising ID (IDFA or AAID), use for in-app tracking.
To build audiences and retarget, one of the identifiers must be passed:
-
eids: An object array of extended IDs. -
firstPartyId: Adform first-party ID. Only use for hybrid setups, where part of site tracking is implemented client side to be able to pass this ID that Adform has set previously. -
cookieId: Adform third-party cookie ID. -
advertisingId: Mobile Advertising ID (IDFA or AAID), use for in-app tracking.
Send Tracking Request
To send server-side tracking events, make a POST request to Adform Server Side Tracking API.
Endpoint Path:
https://{trackingDomain}/{apiVersion}/sitetracking/{trackingsetupid}/trackingpoints/
Where:
-
{trackingDomain}is the tracking domain set on the advertiser level. -
{apiVersion}is the latest API version (V2). -
{trackingsetupid}is the advertiser's tracking ID, which can be found under Site Tracking in Adform UI.
Add all necessary tracking point parameters in the POST request body as Json object.
Filling POST Body Parameters
Make sure to include and pass relevant values to the POST body from the parameters listed below. Include mandatory parameters and any of the recommended and optional.
Note
To use audience building and retargeting, make sure to pass any of user identity parameters.
To use geo and device information, include userIp and userAgent.
Standard conversion attribution currently works only if cookieId (Adform third-party cookie) or advertisingId (mobile advertising ID) is passed correctly.
Cookieless Insights reporting is enabled by userIp and userAgent.
Supported Parameters
|
Parameter |
Description |
Value type |
Application |
|---|---|---|---|
|
|
Tracking Point name. In case empty, |
text |
Mandatory |
|
|
Web page URL where the event originated from |
text |
Optional |
|
|
Web page URL the user visited before navigating to the current page. |
text |
Optional |
|
User Identity |
|||
|
|
An object array of extended IDs, where:
Example: "identity":{
"eids":[
{
"source":"id5-sync.com",
"uids":[
{
"atype":1,
"id":"ID5-ABCDEFG12345"
}
]
}
]
}
|
|
Optional, Recommended |
|
|
Adform first-party ID. Only use for hybrid setups, where part of site tracking is implemented client side to be able to pass this ID that Adform has set previously.
Example: "identity":{
"firstPartyId": {
"id": "243503985029384",
"domain": "advertiser.com"
}
}
|
|
Mandatory (For conversion attribution and retargeting to work, you must pass either |
|
|
Adform third-party cookie ID. Example: "identity":{
"cookieId":"5561975860057581265"
}
|
string |
Mandatory (For conversion attribution and retargeting to work, you must pass either |
|
|
Mobile Advertising ID (IDFA or AAID), used for in-app tracking. Example: "identity":{
"advertisingId":"86eea5f9-f886-4f52-a05b-cd0328d55f72"
}
|
text |
Optional, Recommended |
|
Compliance |
|||
|
|
Example: "compliance":{
"gpp":"DBACMMA~CPuBYEAPuBYEAPoABABGCyCAAAAAAAAAAAAAAAAAAAAA.QAAA.IAAA~BAAAAAAAAAA.QA"
"gppSid":"2"
"gdpr":1,
"gdprConsent":"CPHHBKGPHHBKGBaADAENQC8wGMgXnAIAAyAB8AJ4AfwBCAEcANoAvMAAA.f_gACfgAAAAA",
}
|
|
Optional, Recommended |
|
User Context |
|||
|
|
User’s browser user agent |
text |
Optional, Recommended |
|
|
User’s IP address. |
text |
Optional, Recommended |
|
|
User’s browser language |
text |
Optional |
|
Example: "userContext":{
"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36",
"userIp":"111.111.111.111",
"browserLanguage":"en-US"
}
|
|||
Add Custom Variables
Additional information can be collected and passed together with the POST request using Adform variables. These can be passed in variables: { } object alongside other parameters in the POST body.
-
Variables used in
variablesobject accept a single value per request. -
Variables used in
subVariablesobject arrays can form multiple value sets in the same request. For example, product information of several products in case of an ecommerce purchase.
Send Multiple Tracking Requests
Server-side tracking API allows multiple tracking points and tracking requests to be sent via a single POST request. To do that, include up to 20 data objects in the post request body.
Retrieve Third-Party Cookie ID
Adform cookie ID can be retrieved from the client-side by using a JavaScript code and from Adform campaign banner tags using macros. The retrieved cookie ID needs to be stored and later sent in the post-back URL.
To make sure that cookie ID is retrieved in all possible cases, both cookie retrieval options must be implemented. Resorting to a single option will negatively impact attribution and retargeting capabilities.
Using JavaScript
In order to get Adform cookie ID from the user’s browser using JavaScript, use the following JavaScript tag:
<script src="https://track.adform.net/Serving/Cookie/?adfaction=getjs;adfcookname=uid"></script>
Once the script is loaded, the cookie ID will be assigned to a JavaScript variable window.Adform._uid which can be stored client-side and passed in the server-side request.
The cookie retrieval script doesn't set a cookie. Hence, if there is a need to expand the possible retargeting pool, it is common practice to fire a single tracking point of any type before cookie retrieval to make sure the user has the Adform cookie set.
Use Landing Page Macro on Tags
You can add Adform ID directly to the landing page URL. This can be useful when you don't want to put JavaScript on our page. Even with JavaScript, having Adform ID on a landing page adds a second source for the ID, so if JavaScript is blocked, or late, the ID still exists. Thus, as the best practice, Adform recommends having both the JavaScript solution and the landing page parameter.
To add Adform ID to the landing page, the following macro needs to be added to it as an appended URL parameter value:
__ADFUID__
This macro can be entered by using auto-tagging or URL append functions in the tags section of your campaign. After clicking on an ad, the user lands on the landing page with macro replaced by the actual cookie ID.
An example URL of how the landing page could look like when landing from the ad:
https://www.adform.com/?adfcookieid=2375332706306330000
The extracted cookie ID’s are 19-digit strings which can also be negative values.
Example values of Adform cookie IDs:
2375332706306330000
1594981157981720000
The cookie ID passed with the server-side request is used to attribute tracking point visits to campaigns or for re-targeting later on.