Match Activator Service API (1.0)

User matching and activation service.

Match

Endpoints for matching the user's uid cookie with a given hash.

Requirements

For the matching to be successful, the query param providerId must be an enabled MatchProvider configured in Audience's system.

Hashes

The hash given to the endpoint should exactly match a hash present within the system.

Example to hash an unique identifier (as long as the data in the system was processed the same way):

1. Remove leading and trailing whitespace from the identifier string;
2. Convert the resulting string to lowercase;
3. Convert the resulting string to bytes with UTF-8 encoding;
4. Apply the SHA256 hash function on the resulting bytes;
5. Convert the resulting bytes back to a string by using the url-safe base64 variant.

function encode {
  echo -n $1 |
    awk '{print tolower($0)}' | tr -d '\n' | # convert to lowercase
    openssl dgst -binary -sha256 | # apply SHA256 hash function
    base64 | sed -e "s/\//_/g" -e "s/=*$//" # encode using url-safe base64
}

Concrete example: example@example.com becomes McVUPBc00lxyBvX9WRUl0Clb7G_oT_gvlGo0_pcKHmY.

Match an user and return HTML

Tries to match Audience's cookie with the query param hash value.

An empty HTML page is returned. The HTML may contain additional tags to activate the user with:

• all DataReceiver s enabled for ActivationContainer s that have ActivationContainer.activateOnMatchRequests enabled if configId is not present;
• all DataReceiver s associated with the provided ActivationContainer if configId is present.

Adequate to use in a <iframe/>'s src.

query Parameters

header Parameters

Responses

200

Operation successful or not. Check the response content.

307

Redirecting to check if browser has cookies enabled

Match an user and return pixel gif

Tries to match Audience's ID cookie with the query param {hash} value. An blank pixel gif is returned.

Adequate to use in a <img/>'s src.

query Parameters

header Parameters

Responses

200

Operation successful or not. It will always be the pixel response

307

Redirecting to check if browser has cookies enabled

Match an user and redirect to ourl

Tries to match Audience's ID cookie with the query param hash value. A redirection to ourl is returned.

Adequate to use in a <a/>'s href to match the user and redirect him to the target page.

query Parameters

header Parameters

Responses

302

Redirection to the given URL

307

Redirection to check if browser has cookies enabled

404

Invalid or missing providerId

Activation

Activate and return HTML

Tries to activate an user identified by the request UserId with the configuration defined by the specified ActivationContainer. An HTML page is returned, containing:

• <img/> tags pointing to the URLs configured by DataReceiver.dataTransferUrlTemplate with the macros replaced by the user's parsed attributes for that DataReceiver config;
• <img/> tags pointing to the URLs configured by DataReceiver.cookieSyncRedirectUrl with the adstax_uid encoded for the specific partner.

The DataReceiver s that are considered for activation are all those enabled for the provided ActivationContainer.

Adequate to use in a <iframe/>'s src.

query Parameters

header Parameters

Responses

200

Operation successful or not. No img tags if unsuccessful.

Activate and redirect

Tries to activate an user identified by the request UserId with the configuration defined by the specified ActivationContainer*. A redirect is performed to an DataReceiver.dataTransferUrlTemplate of the DataReceivers enabled for the provided ActivationContainer. The DataReceiver is chosen at random if ActivationContainer.receiverRedirectActivation.random* is enabled. Otherwise, the receiver whose id is specified in ActivationContainer.receiverRedirectActivation.receiver is used.

Background activations are performed for all DataReceiver s enabled for the provided ActivationContainer.

Adequate to use in a <img/>'s src as long as the configured DataReceiver.dataTransferUrlTemplate returns an image as well.

query Parameters

header Parameters

Responses

302

Redirection to the DataReceiver.dataTransferUrlTemplate.

404

Invalid or missing receiverId.

Cookiesync

Synchronize IDs between two systems and return HTML

This endpoint provides a way to synchronize an user ID among two different systems, triggering activations for destinations whose activated ID types contain the cookie sync receiver.

The endpoint behaviour is different whether the uid query parameter is present:

• uid parameter present - the user ID used to trigger relevant activations is the one provided in the uid query parameter and the response will be an empty html;
• uid parameter missing - the user ID used to trigger relevant activations is Audience's first-party cookie mapped to the provided cookie sync receiver. The response will be a redirection to the configured urlTemplate for the cookie sync receiver.

query Parameters

Responses

200

The sync was successful

302

Redirecting to the Cookie syncing redirection URL to provide Audience's uid to the other system

307

Redirection to check if browser has cookies enabled

Synchronize IDs between two systems and return HTML

The endpoint behaviour is different whether the uid query parameter is present:

query Parameters

Responses

200

The sync was successful

302

Redirecting to the Cookie syncing redirection URL to provide Audience's uid to the other system

307

Redirection to check if browser has cookies enabled

Privacy

Returns the current privacy status

The privacy cookie is read if it exists and the current privacy status is returned.

Responses

200

Successful request

Response samples

• 200

Content type

application/json

Copy

{"status": "cookie", "token": "string"}

Opts out of user tracking

The privacy cookie is updated so that future match requests for that user are ignored.

query Parameters

Responses

200

Successful request

Opts in to user tracking

The privacy cookie is updated so that future match requests are considered normally.

query Parameters

Responses

200

Successful request