Skip to main content

Attribute Sync

Introduction

TheAttribute Datasync Syncallows Serviceassociating provides implementersusers with the option of storing items on the Adhese server,attributes which can be used for inventory, campaign insights, and targeting.
These associations are retrieved on ad-request.

Because the data is associated with a userId consent is needed. When you push data to adhese via the attribute-sync, we assume the sender validated the consent. Do not push userdata for which no consent was given.

On the ad-request side we do validate consent. An ad-request without a userId or consent will not get linked with the data that was pushed via attribute-sync.

Pushing data

Authentication

The storagefirst step of pushing data, is retrieving a valid JWT token from our keycloak. We use the ROPC flow, this exact flow may change in the future. You will be provided with the login credentials for an account specifically used for the attribute-sync.

An example request to retrieve a JWT token

curl --location 'https://auth.we.adhese.org/realms/user-sync/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=user-sync-app' \
--data-urlencode 'username=[username]' \
--data-urlencode 'password=[password]' \
--data-urlencode 'grant_type=password'

This token can be linkedre-used tomultiple anytimes kinduntil it expires.

IP-filtering

If requested we can enable IP-filtering on the attribute-sync endpoint. If enabled we will only accept data coming from a predefined list of identifier as per configuration.IP-Addresses.

Server

Uploading Side Memory

data

TheActually memory service allows an implementer to save certainuploading data pointshappens linked to a unique key. The key can be either a user ID, which is only allowed withvia the user's explicit consent, or any other non-personal key (e.g., a DOOH device ID).

The event is a string that will be saved and reported exactly as sent in. A human-readable label can be added in the Adhese inventory configuration.

The third parameter of the memory service is optional and indicates the time-to-live of the saved data point. If no value is passed, the default of 14 days will be applied.

https://ads-[customer].adhese.com/usersync/handlers/[service_handler]/user_sync?id=[event1],[event2]&u=[userid]&ttl=[expiration_in_minutes]

attributesync

Example

endpoint

https://ads-[customer].adhese.com/usersync/handlers/ec_view/user_sync?id=pricewatch&u=123abc&ttl=20160

Example(POST with multiplejson events

https://ads-[customer].adhese.com/usersync/handlers/ec_view/user_sync?id=pricewatch,laptop,macbook&u=123abc&ttl=20160

Removing Data for a Key or User

All data stored in Redis will expire after a given time. The 'right to be forgotten' is one of the most important reasons, and it is essential to provide a way to remove stored data at the request of the rights holder (the end-user)payload).

ToBe removesure data,to simply callpass the useraccess_token sync service withfrom the userprevious IDsteps oras keya youbearer want.token The service will remove all data stored for that key and then removein the keyAuthorization itself.header

Example

https://ads-[customer].adhese.com/usersync/handlers/ec_view/user_sync?iu=123abc

User sync for Open Market OpenRTB

A very specific application of the Data Sync Service can be used to support the OpenRTB User Sync process.

The User Sync process is designed to match P users with SSP users. We recommend syncing users once every day at the earliest opportunity.

The User Sync service is triggered by Adhese directly on the client, enabling the SSP to establish a connection and transfer the resulting user ID to Adhese.

According to the setup, a simple or complex workflow is available. A complex workflow leads to a 1st party user sync cookie, while a simple workflow leads to a 3rd party user sync cookie.

User Consent: This application of the sync service depends on a cookie that contains a unique ID. Users need to be informed about this and give consent prior to calling the service. Adhese has the contractual right to audit the use of this service to ensure it is legally implemented.

Simple workflow

  1. The user navigates to newz.zz
  2. Browser calls SSP endpoint  https://ssp.com/sync?partner=adhese
  3. The SSP redirects to the user sync endpoint
  4. Browser calls Adhese user sync endpoint  https://user-sync.adhese.com/handlers/ssp/user_sync?u=IH3D8DXL-20-KV8Y
  5. We issue a cookie Set-Cookie: ssp_uid=IH3D8DXL-20-KV8Y; <a href="http://Domain=.adhese.com" title="http://Domain=.adhese.com">Domain=.adhese.com</a>; Expires=Fri, 25-Dec-2024 09:57:40 GMT; Path=/
  6. Browser requests an ad on <a href="https://ads-adhese.com/ad/sl_foo_-bar" title="https://ads-adhese.com/ad/sl_foo_-bar">https://ads-adhese.com/ad/sl_foo_-bar</a>
  7. We read ssp_uid cookie to send it over to the SSP’s API

Complex workflow for 1st domain implementations

If a publisher serves on its own domains, the process is more complicated. There are no calls made to *.adhese.com.

  1. The user navigates to publisher-domain.com
  2. Browser registers request domain with Adhese user sync discovery https://user-sync.adhese.com/handlers/ssp/user_sync_discovery?domain=adhese.publisher-domain.com&protocol=https

protocol query parameter is optional, it defaults to https

  1. We read the domain parameter
  2. We issue a cookie: Set-Cookie: user_sync_domain=adhese.publisher-domain.com;Path=/;Expires=Fri, 25-Dec-2024 10:16:23 GMT
  3. The browser calls the SSP endpoint  https://ssp.com/sync?p=publisher
  4. SSP redirects to user sync discovery
  5. The browser calls Adhese user sync discovery  https://user-sync.adhese.com/handlers/ssp/user_sync_discovery?u=IH3D8DXL-20-KV8Y
  6. We read the user_sync_domain cookie
  7. We redirect the call to the user sync endpoint running on the correct domain
  8. The browser calls Adhese user sync endpoint  https://adhese.publisher-domain.com/handlers/ssp/user_sync?u=IH3D8DXL-20-KV8Y
  9. We issue a cookie: Set-Cookie: ssp_uid=IH3D8DXL-20-KV8Y; Expires=Fri, 25-Dec-2024 09:57:40 GMT; Path=/
  10. Browser requests an ad on <a href="https://adhese.publisher-domain.com/ad/sl_foo_-bar">https://adhese.publisher-domain.com/ad/sl_foo_-bar</a>
  11. We read the ssp_uid cookie to send it over SSP’s API

Example endpoint payload

{
  "reportDateTimeValid": "2022-2026-02-11T17:11:00Z",
  "entries": [
    {
      "identifier": {
        "name": "DIGIMON_ID",
        "value": "3255408b0294f9be350bf40adaf47eb016ba32aade43ece486fea55634ccdc49"userId1"
      },
      "attributes": [
        {
          "name": "profileAudience"firstAttribute",
          "value": [
            "known_app_user",
            "known_test_trait_pageview_less_then_1"example_value"
          ]
        },
        {
          "name": "profileAudience2"secondAttribute",
          "value": [
            "known_app_user2",
            "known_test_trait_pageview_less_then_2"
          ]
        }
      ]
    },
    {
      "identifier": {
        "name": "DIGIMON_ID",
        "value": "3255408b0294f9be350bf40adaf47eb016ba32aade43ece486fea55634ccdc50"foobar"
      },
      "attributes": [
        {
          "name": "profileAudience"firstAttribute",
          "value": [
            "known_app_user",
            "known_test_trait_pageview_less_then_1"another_example_value"
          ]
        }
      ]
    }
  ]
}

Above you can see an example payload.

reportDateTimeValidOptionalHow long we can/should store the data from this request. If absent we default to 7 days in the future. By default we limit the validity to a maximum of 30 days in the future.
entriesMandatory

Each user is represented by an entry. We accept up to 500 entries per request.

To store data for more than 500 users, please use multiple requests instead.

entries.identifier.valueMandatory

This field represents the userId of this entry.

entries.identifier.nameMandatory

Some customers have different types of userIds (eg an actual userId and a deviceId) and want to be able to store different data for the same userId if the userId came from a different source. You can think of this as a namespace for your userIds. These can be arbitrary but need to be used consistently.

Inform our support agents which ones you plan to use.

 

Even if you only use a single source of userIds, a value still needs to be chosen.

entries.attributesMandatory but can be empty

Can be left empty for deleting data. See below.

entries.attributes.nameMandatory

The attribute for which you want to store values for the specific userId.

entries.attributes.valuesMandatory

The values you want to store with the attribute for the specific userId.

Each time we receive data via the attribute-sync for a specific user, it overwrites the data from previous requests regarding that user, even if certain attributes are not included in the latest request but were in the first request.
This has as a side effect that you can delete all (attribute-sync) data associated with a user by leaving the entries.attributes empty. 

Because attribute-sync is meant for textual data, we may reject data that contains Unicode control characters. 

Using the data

Cooperate with support to configure which target(s) represent userId(s), and which attribute corresponds with which target. When done ad-requests with consent and a userId will automatically get additional targets from the data you pushed, even if the push happened less than a second ago.

What data to store

Because all the data pushed via the attribute-sync needs to be accessible without delay, this data is stored in memory. For this reason we ask to be mindful of what data you store:

  • Only store attributes you actually plan on using.
  • Do not make attributes/attribute values overly verbose (they do not need to be human readable)
  • Keep userIds to a reasonable length

 

Back to top