Use Server-Side Tracking

Greta
  • Updated

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).

12.png

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

name

Tracking Point name. In case empty, pageUrl will be set if not empty.

text

Mandatory

pageUrl

Web page URL where the event originated from

text

Optional

refererUrl

Web page URL the user visited before navigating to the current page.

text

Optional

User Identity

eids

An object array of extended IDs, where:

  • id: User identifier.

  • atype: Agent type (which environment ID is bound to) based on IAB standard.

  • source: ID provider, type: text. See examples of sources from Prebid.

Example:

"identity":{
         "eids":[
            {
               "source":"id5-sync.com",
               "uids":[
                  {
                     "atype":1,
                     "id":"ID5-ABCDEFG12345"
                  }
               ]
            }
         ]
      }

id: text

atype: integer

source: text

Optional, Recommended

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.

id : first-party ID set by Adform prior s2s even in client side environment.

domain: domain on which the first-party ID has been set (advertiser’s website domain).

Example:

"identity":{
    "firstPartyId": {
        "id": "243503985029384",
        "domain": "advertiser.com"
    }
}

id : string

domain: text

Mandatory (For conversion attribution and retargeting to work, you must pass either cookieID or firstPartyId.).

cookieId

Adform third-party cookie ID.

Example:

"identity":{
         "cookieId":"5561975860057581265"
}

string

Mandatory (For conversion attribution and retargeting to work, you must pass either cookieID or firstPartyId.).

advertisingId

Mobile Advertising ID (IDFA or AAID), use for in-app tracking.

Example:

"identity":{
         "advertisingId":"86eea5f9-f886-4f52-a05b-cd0328d55f72"
}

text

Optional, Recommended

Compliance

gdpr

gdprConsent

usPrivacy

gpp

gppSid

  • gdpr - GDPR applicability (possible values 1 - applies, 0 - doesn’t apply), type: integer.

  • gdprConsent - GDPR user consent string, type: text. This is required if gdpr has value 1, according to IAB TCF.

  • usPrivacy - US privacy signal (CCPA), type: text.

  • gpp - User’s Consent string according to IAB Global Privacy Platform (GPP)

  • gppSid - GPP Section ID which Adform uses for privacy resolution (Possible values 2 = EU TCF v. 2; 7 = US MSPA)

Example:

    "compliance":{
     "gpp":"DBACMMA~CPuBYEAPuBYEAPoABABGCyCAAAAAAAAAAAAAAAAAAAAA.QAAA.IAAA~BAAAAAAAAAA.QA"
     "gppSid":"2"
     "gdpr":1,
     "gdprConsent":"CPHHBKGPHHBKGBaADAENQC8wGMgXnAIAAyAB8AJ4AfwBCAEcANoAvMAAA.f_gACfgAAAAA",
     "usPrivacy":"1---"
  }

gdpr - integer

gdprConsent - text

usPrivacy - text

gpp - text

gppSid - text

Optional, Recommended

User Context

userAgent

User’s browser user agent

text

Optional, Recommended

userIp

User’s IP address.

text

Optional, Recommended

browserLanguage

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 variables object accept a single value per request.

  • Variables used in subVariables object 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.

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!