The DAP API is the primary method by which client applications and server interact with the the DAP platform. It is based on REST and aims to be as simple as possible. At a high level, the API allows clients to tokenize PII into a privacy-safe pseudonymization called a DAP Token, and retrieve cohort-level targeting parameters for those tokens.
A fundamental principle embraced by DAP is the concept of protecting privacy by placing individuals into large groups of individuals called cohorts. When an individual is "hidden among the crowd", it becomes extremely difficult or even impossible to track that one individual's behavior. This is why DAP only allows individuals to be targeted by a cohort, and never as an individual. The cohort concept also removes any individual identifiers from the bidstream further making it difficult or even impossible to build a profile on individual user behavior.
A DAP client include has been created to simplify the process for tokenizing end user identities and retrieving the associated cohorts for submission to the bid-stream.
<!-- DAP CLIENT BEGIN -->
<!-- Adjust jQuery include as needed; DAP does not depend on a specific version of jQuery, -->
<!-- it just needs $.ajax(). -->
<script src="https://code.jquery.com/jquery-3.2.1.min.js" crossorigin="anonymous"></script>
<script src="https://sym-dist.symitri.net/dap-x1.2.js"></script>
<script src="https://sym-dist.symitri.net/dap-client-x1.2.js"></script>
<script>
config = {
api_hostname: "api.dap.akadns.net",
api_version: "x1",
domain: "advertiser.com"
};
identity = {
type: "dap-signature:1.3.0"
};
let ttl = 3600; // seconds
let dap_token = dap_get_token( config, identity, ttl );
let dap_segment = dap_get_segments( config, dap_token );
</script>
<!-- DAP CLIENT END -->The dap_segment object is suitable for including into the OpenRTB user.data.segment array.
In order to test the code is working, deploy the code to your site, and then use DevTools to inspect the network traffic as the site loads. You should see a request of an object called tokenize, and then subsequently membership. The tokenize request should return 201 Created and carry with it a Symitri-DAP-Token response header with the DAP token for the supplied identity and type. The membership request should return 200 and have a set of cohorts and a Secure Ad ID (SAID) in the response body JSON.
| API | Location | Snippet |
|---|---|---|
| Tokenize | Response Header | Symitri-DAP-Token: eyJhbGci... |
| Membership | Response Body (JSON) |
{
"cohorts": [ "1", "5", "7" ],
"said": "eyJraWQI..."
}
|
The Symitri Data Activation Platform has been integrated into Prebid.JS through the use of Prebid's User ID module subsystem. This integration is a stop-gap until the bid-stream is ready to transact on segments, at which point we will deprecate this module in favor of our DAP Real Time Data module. For now, this integration requires the Trust-X SSP to receive and strip the token from the bid-stream, and subsequently map the cohorts returned by the Membership API into one or more Deal IDs.
In order to enable DAP within Prebid.JS you simply need to include the "symitriDAPIdSystem" along with your other modules when building Prebid.
The latest documentation for this integration, as well as an example of the required client-side configuration can be found in the module's documentation page.
A quick-start for supporting consenting but unauthenticated users with Prebid in "SSP-assist" mode would be:
pbjs.setConfig({
userSync: {
userIds: [{
name: "symitriDAPId",
params: {
apiHostname: "prebid.dap.akadns.net",
apiVersion: "x1",
domain: "prebid.org",
type: "dap-signature:1.0.0"
},
}],
}
});In order to test that the module is working, incorporate your DAP-enabled prebid.js build into a web page, make the appropriate prebid configurations, and inspect an outgoing bid looking for the presence of Symitri EIDS in the bid-stream. For example, the Symitri EIDS can be found in the following locations with the following bid adapters:
| Bid Adapter | Location | Snippet |
|---|---|---|
| gridBidAdapter, pubmaticBidAdapter | Request Body (JSON) |
"user": {
"ext": {
"eids": [ {
"source": "symitri.com",
"uids": [ {
"atype": 1,
"id": "eyJhbGci..."
} ]
} ]
}
}
|
| rubiconBidAdapter | Request Header | eid_symitri.com: eyJhbGci... |
For non-bidding use-cases (e.g. audience cohort curation), GTM can be used to tokenize consented end users and capture their identities within the DAP system. A typical example would be tagging an interaction on an advertiser site that places the end user into a specific cohort to be targeted at some point in the future.
In the following example, the end user is placed into cohort 5 for 30 days (2,592,000 = 3600 x 24 x 30).
<!-- Begin DAP Signature Code -->
<!-- Adjust jQuery include as needed; DAP does not depend on a specific version of jQuery, -->
<!-- it just needs $.ajax(). -->
<script src="https://code.jquery.com/jquery-3.2.1.min.js" crossorigin="anonymous"></script>
<script src="https://sym-dist.symitri.net/dap-x1.2.js"></script>
<script src="https://sym-dist.symitri.net/dap-client-x1.2.js"></script>
<script>
config = {
"api_hostname": "api.dap.akadns.net",
"api_version": "x1",
"domain": "advertiser.com"
};
identity = {
"type": "dap-signature:1.3.0",
"attributes": {
"cohorts": [ "5:2592000" ]
}
};
ttl = 3600; // seconds
dap_get_token( config, identity, ttl );
</script>
<noscript><!-- Unsupported --></noscript>
<!-- End DAP Signature Code -->In order to test that the tag is working, deploy the tag above to your site, and then use DevTools to inspect the network traffic as the site loads. You should see a request for an object called tokenize which is an invocation of the DAP API to protect an identity by encapsulating it in a token. You should see a DAP Token returned in the Symitri-DAP-Token response header.
| Location | Snippet |
|---|---|
| Response Header | Symitri-DAP-Token: eyJhbGci... |
Tokenize an identity into a secure pseudonymization suitable for privacy-safe, cohort membership lookups. Identities can be supplied by the client or can be requested from the server in the form of a signature.
This API protects direct end user PII by tokenizing it into a pseudonymization in the form of a highly secure, JSON Web Token with Encryption (JWT/JWE) object called a DAP Token. DAP Tokens cannot be decrypted by anyone, and therefore prevent leakage or misuse of PII.
Once a DAP Token is returned in the response, it can be used as input to the Membership API to lookup cohorts this end user belongs to.
For cases where the end user is not supplying PII, a server-side device ID can be assigned by setting the type to a valid DAP signature format (e.g. dap-signature:1.3.0).
Identities only need to be tokenized once, or when the identity value itself changes. It is expected that identities will be tokenized in conjunction with a login event, or when an application assigns an ID to a device.
C->S: POST /data-activation/x1/domain/{domain}/identity/tokenize
Host: api.dap.akadns.net
Content-Type: application/json
{
"identity": "obiwan@jedi.com",
"type": "email"
}
S->C: HTTP/1.1 200 Ok
Symitri-DAP-Token: eyJ0eXAi...
C->S: POST /data-activation/x1/domain/{domain}/identity/tokenize
Host: api.dap.akadns.net
Content-Type: application/json
{
"type": "dap-signature:1.3.0"
}
S->C: HTTP/1.1 200 Ok
Symitri-DAP-Token: eyJ0eXAi...
The output of the Tokenize API is a DAP Token containing the supplied domain, identity, and type.
Retrieve the cohort membership and a new Secure Ad ID (SAID) for the supplied DAP Token. The cohorts and SAID are then supplied to the bidstream: the cohorts for targeting purposes, and the SAID for future measurement and attribution purposes. The cohorts allow the bidder to match on segments of the population they have previously curated. The SAID is meant to be collected and stored, and then submitted back to DAP where analysis can be done on large numbers of SAIDs and results returned at the cohort level--this is foundational to preventing unauthorized tracking and profiling of individuals.
This API returns a set of cohorts to which this end-user belongs and a new so-called one-time use Secure Ad ID (SAID) to represent this impression opportunity. Cohorts are created by the buy-side, and periodically updated within DAP to represent the current needs of a campaign.
Along with the cohorts, a new SAID is returned as well. SAIDs allow the buy-side to collect information that can only be used to understand cohort level behavior if the appropriate permissions by the publisher have been granted.
This API must be invoked every "page load" to ensure that a new Secure Ad ID (SAID) is supplied along with the cohorts to the bidstream. It is imperative to privacy that SAIDs appear as ephemeral as possible to the bidstream so that the potential for tracking is minimized. It is intended that a new SAID be created for every set of impression opportunities on a page, or every ad in a pod is auctioned.
C->S: GET /data-activation/v1/token/{token}/membership
Host: api.dap.akadns.net
S->C: HTTP/1.1 200 OK
Content-Type: application/json
{
"cohorts": [ "1", "5", "7" ],
"said": "eyJraWQiO..."
}
Update token attributes such as associating cohorts.
This API allows third-party systems to maintain attributes of a given token they have relationships with. The common use-case is to add or update cohorts that should be associated with the supplied token.
Cohorts additionally have an optional TTL associated with them and is specified by appending the TTL, in seconds, to the end of the cohort ID delimited by a colon.
It is expected that third-party systems will continuously be updating cohort membership throughout the life of a campaign. This API should be invoked as often as is necessary to satisfy campaign requirements.
C->S: POST /data-activation/x1/token/{token}/attributes
Host: api.dap.akadns.net
Content-Type: application/json
{
attributes: {
cohorts: [ "39:2592000", "32:3600" ]
}
}
S->C: HTTP/1.1 200 OK
In this example, the third-party is establishing or updating two cohort memberships that read as follows:
The output of this API is an HTTP status code representing success or failure.