Overview

This guide is for Equativ’s demand partners and explains how to use the OpenRTB API, including setup, configuration as well as the supported objects and parameters. This article explains cookie synchronization between Equativ and our demand partners.

There are two ways to synchronize cookies between Equativ and the demand partners.

1. Partner initiates synchronization requests.
2. Equativ initiates synchronization requests.

Partner initiates synchronization request

In order to synchronize cookies between Equativ and the partner, the partner calls:

Example 1: No call back to partner (no Equativ user ID sent to partner): https://sync.domain.com/redir/?partnerid=USER_POOL_ID&partneruserid=PARTNER_USER_ID

Example 2: Call back to partner with Equativ’s user ID (optional): https://sync.domain.com/redir/?partnerid=USER_POOL_ID&partneruserid=PARTNER_USER_ID&redirurl=ENCODED_PARTNER_URL

where

• sync.domain.com is a placeholder domain; the actual domain to be used will be communicated during the integration process
• USER_POOL_ID is a placeholder replaced by the partner with the user pool identifier provided by Equativ during integration
• PARTNER_USER_ID is a placeholder replaced by the partner before a call with the partner’s unique identifier for the user that will be passed by Equativ in bid requests (via the buyeruid attribute of the user object)
  • ⚠ Only ASCII characters between 0x21 and 0x7E, inclusive are accepted. In addition, the following characters are not accepted: " , ; \ | (double quote, comma, semicolon, backslash and pipe).
• ENCODED_PARTNER_URL is an optional callback URL, if provided it must be percent encoded
  • before encoding, ENCODED_PARTNER_URL must contain the following macro: SMART_USER_ID (Example: https://partnerdomain/partnerpath?userId=SMART_USER_ID)
  • the SMART_USER_ID macro is mandatory and will be replaced by a Equativ unique user ID before a callback
  • this ID will be passed by Equativ in bid requests (via the id attribute of the user object)

Example 1:

Partner calls : https://sync.domain.com/redir/?partnerid=3&partneruserid=A1B2C345DFEDF&redirurl=https%3A%2F%2Fpartnerdomain%2Fpartnerpath%3FuserId%3DSMART_USER_ID

The response code is HTTP 302 and it will be redirected to: https://partnerdomain/partnerpath?userId=123456789

Example 2:

Partner calls:

https://sync.domain.com/redir/?partnerid=3&partneruserid=A1B2C345DFEDF

The response code is HTTP 200. Note that sync.domain.com is a placeholder domain; the actual domain to be used will be communicated during the integration process.

Equativ initiates synchronization request

This is done by calling the partner’s cookie synchronization server. To use this method, the partner has to provide a cookie synchronization URL.

After Equativ calls said synchronization URL, the partner will have to call Equativ back using the parameterized URL provided in the section above. Alternatively, the Equativ user synchronization may provide a callback URL directly as a parameter in the call to the partner. The partner will then have to call this URL after appending the partner’s user ID for this call.

Example 1 - No additional call back to the partner (no Equativ user ID sent to partner):

https://partnerdomain/partnerpath?sspurl=http%3A%2F%2Fsync.domain.com%2Fredir%2F%3Fpartnerid%3DUSER_POOL_ID%26partneruserid%3DPARTNER_USER_ID 

Example 2 - Additional call back to the partner with Equativ’s user ID (optional):

https://partnerdomain/partnerpath?sspurl=http%3A%2F%2Fsync.domain.com%2Fredir%2F%3Fpartnerid%3DUSER_POOL_ID%26partneruserid%3DPARTNER_USER_ID%26redirurl%3DDOUBLE_ENCODED_PARTNER_URL

where

• sync.domain.com is a placeholder domain; the actual domain to be used will be communicated during the integration process
• USER_POOL_ID is a placeholder replaced by the partner with the user pool identifier provided by Equativ during integration (note: for some legacy integrations the user pool ID is the same as the assigned partner ID)
• PARTNER_USER_ID is a placeholder replaced by the partner before a call and contains a unique identifier of the user that will be passed in bid requests (via the buyeruid attribute of the user object)
• DOUBLE_ENCODED_PARTNER_URL is an optional callback URL, if provided it must be double encoded using a URL percent encoding (http://en.wikipedia.org/wiki/Percent-encoding)
• prior to encoding, DOUBLE_ENCODED_PARTNER_URL must contain the following macro: SMART_USER_ID
• (Example: https://partnerdomain/partnerpath?userId=SMART_USER_ID)
• the SMART_USER_ID macro is mandatory and will be replaced by a Equativ unique user ID before a callback
• this ID will be passed by Equativ in bid requests (via the id attribute of the user object)

Example:

Equativ calls the following URL provided by the partner:

https://partnerdomain/partnercookiesyncpath

The partner redirects (HTTP 302) to:

https://sync.domain.com/redir/?partnerid=3&partneruserid=A1B2C345DFEDF&redirurl=http%3A%2F%2Fpartnerdomain%2Fpartnerpath%3FuserId%3DSMART_USER_ID

This behaves similarly to a partner initiated call as described in the section above. Note that sync.domain.com is a placeholder domain; the actual domain to be used will be communicated during the integration process

GDPR

TCFv2 GDPR parameters are required in all scenarios as per the TCF V2 spec, for URL-based services. In particular, the following parameters must be appended to 100% of user sync calls:

• gdpr = 0 or 1
• gdpr_consent = {TCFv2 consent string}

See the TCFv2 spec link above for further details.

Known user filtering

On demand, and in conjunction with cookie synchronization, Equativ can restrict desktop and mobile web requests to a given partner to the already known users. Meaning that only requests coming from users with a mapped partner buyerUID will be sent to that partner.

Placement Transparency

Publishers using Equativ can choose three modes for placement transparency on their websites.

• Full Transparency: the site.page item of the BidRequest will hold the full referrer of the web page the ad will be delivered on. And for mobile applications the app.name will hold the application name.
• Half-Blind: publishers that do not wish to transmit the full referrer but still want to identify bidRequests as coming from one of their pages may instead send a custom URL that will be sent in the site.page item for all pages of their websites. E.g: Example Inc. might send http://www.example.com for all their pages instead of detailed URLs.
• Blind: publishers that do not want their traffic to be identified by third parties will send http://rtbplus.smartadserver.com or http://rtbplus.smartadserver.com/<IAB category> in the site.page item for web and mobile web traffic and http://rtbplus-mobile.smartadserver.com or http://rtbplus-mobile.smartadserver.com/<IAB category> in the app.domain for mobile applications.

In order to facilitate targeting specific transparency levels, Equativ transmits a field in the extension of the bid request indicating the transparency of the auction.

When the field ext.sas.transparency is not present the auction is understood to be transparent by default.

When the field is present, it takes on the following values and meanings:

• 0 = transparent
• 1 = semi-blind
• 2 = blind

Here's an example of the extension for a semi-blind bid request:

{
    "id": "316474690992272740",
    "imp": [{...}],
    "app": {...},
    "device": {...},
    "user": {...},
    "at": 2,
    "cur": ["USD"],
    "ext": {
        "sas": {
            "transparency": 1
        }
    }
}