Overview

We recommend that you deploy ID5 in mobile in-app environments via a server to server integration. We do support alternative integration pathways depending on your requirements. If required, please reach out to your ID5 customer services representative.

To ensure accurate cross-domain and cross-device reconciliation, clients should provide signals, such as hashed emails and MAIDs in the request. We also expect you to store the 'signature' provided in our response on the user's device and provision it to us in future requests. This is integral to an optimal set up since it helps us re-identify consenting users even if their signals change as well as respect opt out requests.

Below are general instructions on how to retrieve an ID5 ID server-side for mobile app inventory and make it available in bid requests to your demand partners. The auction should be delayed in order to retrieve the user’s privacy preferences and the ID5 ID prior to sending out bid requests; the amount you delay may vary and so we recommend making it configurable for optimization purposes.

Process Flow

All the server-to-server requests should be made based on user even in the app and synchronously with them.

1. Check local storage cache for an available ID5 ID

   • IF there is no cached ID
     OR if the ID needs to be refreshed (we recommend a cache of 8 hours)
     OR if the user’s privacy preferences have changed:
     • Initialize a new HTTP POST request to the ID5 endpoint. If you previously had a stored response, then subsequent requests must include the "signature" as part of the request to ID5;
     • Store the response from ID5 locally (either in-app in local storage or in a database on the server);
   • ELSE if there is a valid, up-to-date value in cache:
     • Pull latest ID5 ID response from Cache
2. With the ID you now have from step 1 above (from request or cache), prepare the data for the bid request.
   • Fields that you must put in the bid request:
     • universal_uid
     • link_type
3. Include this data in each bid request to your demand partners as an eids array. For more information on how this is typically done, you can review Sending the ID5 ID to DSPs.

Caching the response

The response we return for the request will need to be cached as some of the response data needs to be used in future requests for the users. Use the ts parameter sent in the request in order to set a TTL for the cache refresh and a TTL for the cache deletion.

• The TTL for the cache refresh should be set to 8 hours. After the 8 hours, on the back of a user event in the app, a new request to ID5 should be made and the cached data refreshed using the data from the API response.
• The TTL for the cache deletion should be set to 30 days. The TTL for the cache deletion should be refreshed with every response from the API. If there will not be a user event in the app, in the 30 days time window, the data should be deleted.

Building Server-Side Request

Server-Side Fetch endpoints for in-app

North America

https://na.id5-sync.com/ga/v1

Global

https://api.id5-sync.com/ga/v1

Request Type

HTTP POST with JSON body.

Request Headers

Content-Type: application/json

Partner Number

The PARTNER in the request body will be an ID5-provided Partner Number. This value will be static for you once we set you up in our system. You may use the endpoint during testing with the Partner Number 173. If you haven't already been assigned a Partner Number, please contact us to request one.

Server-Side Request Parameters

Request Body

Segment Object

Response Body

Privacy Object

ext Object

Invalid Request Response

Example Request

{
  "ts": "2013-02-01T12:52:34+09:00",
  "partner": 123,
  "appid": "string",
  "bundle": "string",
  "ver": "string",
  "ip": "198.51.100.42",
  "ua": "Mozilla/5.0 (Linux; Android 11; moto e20 Build/RONS31.267-88-3; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/109.0.5414.118 Mobile Safari/537.36",
  "signature": "string",
  "gdpr": 0,
  "gdpr_consent": "string",
  "allowed_vendors": [
    "ID5-78",
    "134"
  ],
  "us_privacy": "1YNY",
  "gpp_sid": "6,7",
  "gpp_string": "DBABzw~1YNY~BVQqAAAAAgA",
  "name": "string",
  "domain": "string",
  "maid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "maid_type": "idfa",
  "hem": "f97ea86ed181d60b0ba62a30579f1e10ad71eaf21b548e173de75718065c533f",
  "phone": "string",
  "idfv": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "puid": "string",
  "ipv6": "2001:0db8:5b96:0000:0000:426f:8e17:642a",
  "country": "string",
  "region": "string",
  "city": "string",
  "att": true,
  "accept_language": "de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7"
}

Example Valid Response

{
  "created_at": "2013-02-01T12:52:34+09:00",
  "original_uid": "string",
  "universal_uid": "string",
  "privacy": {
    "jurisdiction": "gdpr",
    "id5_consent": true
  },
  "signature": "string",
  "ext": {
    "linkType": 0
  }
}

Example Invalid Response

{
  "code": "partner_id_invalid",
  "message": "unknown partner",
  "type": "invalid_request_error"
}

ID5 Signature

The ID5 Signature will be returned on every response from ID5 and contains all "user state" information necessary to support cross-domain reconciliation. As an example, this could include the following pieces of data:

• Original UID value (an encrypted first party ID for this user on this domain/publisher)
• Cookie Birthdate
• Last Seen Timestamp (from this domain/publisher)
• Current ID5 ID value (encrypted)
• Link Type

The Signature is used only by ID5 (it will be encrypted with a private key) and must be passed in every subsequent request to ID5.

Mobile Opt Ins/Opt Outs

User opt in and opt outs can be communicated via our Mobile Opt In/Opt Out endpoint