# Match Activator Service API (1.0)

User matching and activation service.

## Match

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

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

```bash
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

|     |     |
| --- | --- |
| providerId<br>required | string<br>The `id` of the _MatchProvider_ that issues the match request. |
| configId | string<br>The `id` of the _ActivationContainer_ that should be used when computing the Destinations to activate. |
| id_{idType}<br>required | string<br>Multiple instances of this query parameter can be received.<br>The `{idType}` should be replaced with the type of _UserId_ being matched while the parameter value will be _UserId_'s id itself.<br>If configured for the given `providerId`, the UserId id can be encrypted. |
| cookies | boolean<br>Default: true<br>If false, a new **adstax_uid** Cookie won't be generated if it is missing from the request. |

##### header Parameters

|     |     |
| --- | --- |
| Cookie | string<br>- **adstax_uid**: The default uid used to identify the user in Kevel Audience. If not present, a new one will be generated and set. |

### 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

|     |     |
| --- | --- |
| providerId<br>required | string<br>The `id` of the _MatchProvider_ that issues the match request. |
| id_{idType}<br>required | string<br>Multiple instances of this query parameter can be received.<br>The `{idType}` should be replaced with the type of _UserId_ being matched while the parameter value will be _UserId_'s id itself.<br>If configured for the given `providerId`, the UserId id can be encrypted. |
| cookies | boolean<br>Default: true<br>If false, a new **adstax_uid** Cookie won't be generated if it is missing from the request. |

##### 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

|     |     |
| --- | --- |
| receiverId | string<br>The `id` of the _ActivationContainer_ that should be used when computing the Destinations to activate. This parameter will be deprecated in the future. Use `configId` instead. |
| configId | string<br>The `id` of the _ActivationContainer_ that should be used when computing the Destinations to activate. |
| id_{idType} | string<br>Overrides the request _UserId_ which is extracted by Cookie by default.<br>The `{idType}` should be replaced with the type of the _UserId_ while the parameter value will be _UserId_'s id itself. |

##### 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

|     |     |
| --- | --- |
| cookiesyncId | string<br>The ID of the third-party provider of cookies. |
| uid | string<br>The ID of the user, if the mapping is to be stored on the system. |
| id_1pCookie | string<br>If `cookies=false`, the `adstax_uid` cookie will be ignored and the user id should be specified via this query parameter instead. |
| cookies | boolean<br>Default: true<br>If false, a new **adstax_uid** Cookie won't be generated if it is missing from the request. |

### 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

|     |     |
| --- | --- |
| token<br>required | string<br>A token needed for alteration to the cookie privacy status.<br>It must match the token found inside the cookie `priv`. |

### 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