Match Activator Service API (1.0)
User matching and activation service.
Endpoints for matching the user's CDP uid cookie with a given hash.
All the match endpoints apply the same logic except the return value:
| Endpoint | Return | Use case |
|---|---|---|
| /match | HTML | to use in a <iframe/>'s src |
| /match/pixel.gif | image | to use in a <img/>'s src |
| /match/redirect | redirection | to use in a <a/>'s href to match the user and redirect him to the target page |
Requirements
For the matching to be successful, the query param providerId must be an enabled MatchProvider configured in the CDP.
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):
- Remove leading and trailing whitespace from the identifier string;
- Convert the resulting string to lowercase;
- Convert the resulting string to bytes with UTF-8 encoding;
- Apply the SHA256 hash function on the resulting bytes;
- 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 the CDP ID 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 DataReceivers enabled for ActivationContainers that have
ActivationContainer.activateOnMatchRequests enabled if
configIdis not present; - all DataReceivers associated with the provided ActivationContainer if
configIdis present.
Adequate to use in a <iframe/>'s src.
query Parameters
| providerId required | string The |
| configId | string The |
| id_{idType} required | string Multiple instances of this query parameter can be received.
The If configured for the given |
| cookies | boolean Default: true If false, a new adstax_uid Cookie won't be generated if it is missing from the request. |
header Parameters
| Cookie | string
|
Responses
Match an user and return pixel gif
Tries to match the CDP ID cookie with the query param {hash} value. An blank pixel gif is returned.
Adequate to use in a <img/>'s src.
query Parameters
| providerId required | string The |
| id_{idType} required | string Multiple instances of this query parameter can be received.
The If configured for the given |
| cookies | boolean Default: true If false, a new adstax_uid Cookie won't be generated if it is missing from the request. |
header Parameters
| Cookie | string
|
Responses
Match an user and redirect to ourl
Tries to match the CDP 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
| providerId required | string The |
| id_{idType} required | string Multiple instances of this query parameter can be received.
The If configured for the given |
| cookies | boolean Default: true If false, a new adstax_uid Cookie won't be generated if it is missing from the request. |
| ourl required | string The URL to which the browser will be redirected. This field must be URL-encoded. |
header Parameters
| Cookie | string
|
Responses
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 theadstax_uidencoded for the specific partner.
The DataReceivers that are considered for activation are all those enabled for the provided ActivationContainer.
Adequate to use in a <iframe/>'s src.
query Parameters
| receiverId | string The |
| configId | string The |
| id_{idType} | string Overrides the request UserId which is extracted by Cookie by default. The |
header Parameters
| Cookie | string
|
Responses
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 DataReceivers 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
| receiverId | string The |
| configId | string The |
| id_{idType} | string Overrides the request UserId which is extracted by Cookie by default. The |
header Parameters
| Cookie | string
|
Responses
Opts out of user tracking
The CDP privacy cookie is updated so that future match requests for that user are ignored.
query Parameters
| token required | string A token needed for alteration to the cookie privacy status.
It must match the token found inside the cookie |
Responses
Response samples
- 200
{- "status": "cookie",
- "token": "string"
}Opts out of user tracking
The CDP privacy cookie is updated so that future match requests for that user are ignored.
query Parameters
| token required | string A token needed for alteration to the cookie privacy status.
It must match the token found inside the cookie |
Responses
Response samples
- 200
{- "status": "cookie",
- "token": "string"
}Opts in to user tracking
The CDP privacy cookie is updated so that future match requests are considered normally.
query Parameters
| token required | string A token needed for alteration to the cookie privacy status.
It must match the token found inside the cookie |
Responses
Response samples
- 200
{- "status": "cookie",
- "token": "string"
}Opts in to user tracking
The CDP privacy cookie is updated so that future match requests are considered normally.
query Parameters
| token required | string A token needed for alteration to the cookie privacy status.
It must match the token found inside the cookie |
Responses
Response samples
- 200
{- "status": "cookie",
- "token": "string"
}