Passing Partner Data to ID5

Passing Partner Data to ID5

What is Partner Data?

Partner Data represents any signals that a partner is able to pass to ID5 to help recognize the user.  Browsers are taking increasing steps to obfuscate signals to third parties, therefore to maximize the addressability of your audience, ID5 requires publishers and advertisers to send IP address and user agent into the pd string and recommends the provision of hashed emails, mobile ad ids and any other signals for consented users when available.  If there are any signals you feel might help reconcile your users across your properties, please discuss this with your ID5 representative and we will advise you of how to pass them through. If you do not want to pass signals through a client side integration, please reach out and we can discuss server side options. 

How is Partner Data Used?

Signals passed in the ID5 ID request, are used to inform ID5 ID generation and linking users across domains. “Hard signals” such as hashed email addresses take priority for cross-domain linkage purposes. ID5 performs a real-time look-up for the value provided and returns the ID5 ID that was already associated with that value. If the value doesn’t exist in the ID5 database, a new ID5 ID is created and provided in the response. 

Publisher provided signals such as IP address and user agent may be used in ID5’s probabilistic algorithm when ID5 deems that they may be more accurate than those that ID5 can source directly from the http request. ID5 requires sha256 hashing & URL-safe base64 encoding to ensure that personally-identifiable information isn’t transmitted in the ID5 ID call. 


Types of Partner Data Supported

Key
Description
Type
0
other
Optional
1
sha256 hashed email
(see below for how to cleanse the email prior to hashing)
Recommended
2
sha256 hashed phone number
(remove all characters besides numbers before hashing)
Recommended
3
cross-partner user id value
(i.e. a user id that could be used across ID5 Partner Numbers / Accounts)
Optional
4
cross-partner user id source
(value will be provided by ID5)
Optional
5
partner-specific user id value
(i.e. a user id that is specific to a single ID5 Partner Number / Account)
Optional
6
Apple ID for Advertising (IDFA)
(lowercased) *Recommended for in-app requests*
Recommended
(when available)
7
Google Advertising ID (GAID)
(lowercased) *Recommended for in-app requests*
Recommended
(when available)
8
Full URL (text). Example: https://id5.io/solutions/
Recommended
(Not necessary to include if you are sending key 9)
9

Domain (text). Example: www.id5.io

Recommended
(Not necessary to include if you are sending the full URL key 8)
10
IPv4 address of the end-user’s device. Example: 77.99.190.227
Required (learn more)
11

The IPv6 address of the end-user’s device. Example: 2001:0db8:85a3:000:000:8a2e:0370:7334

Recommended
12
The user agent string of the end-user’s device (text). Example: Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36
Required (learn more)
13
A flag for whether the hashed email provided is a burner email (boolean). As emails are provided to ID5 in hashed form, ID5 is unable to determine whether provided hashed emails are ‘burner’ emails. Publishers can use this flag to signal to ID5 whether the provided email should be treated as a ‘burner’ email. At the moment, we recommend you send ‘true’ for all icloud email addresses. Example: true
Optional
14
Apple ID for Vendor (idfv). An alphanumeric string that uniquely identifies a device to the app’s vendor.
Optional
15
CTV ID - the specific user id for the CTV ecosystem the user is observed in, as received by the CTV/OTT/Publisher provider
Optional
16
CTV ID Type - the type of the CTV id received (i.e. Roku, Samsung, etc)
Optional
17
An IAB TechLab Tokenization Framework token (e.g. uid2)
Optional

Deriving the Partner Data (pd) Value

Here are a few examples on how to send partner data in requests to ID5.

Example 1 - Partner wants to pass in IPv4, IPv6 and User Agent.
  1. Key 10= IPv4 = 2a00:23c6:b188:be01:b064:589f:9606:d18
  2. Key 11= IPv6 = 109.154.90.18
  3. Key 12 = User Agent String = Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36
  1. URL-encode (according to RFC 3986) each value using UTF-8 charset.
  2. Create the raw pd string containing the keys 10 (for the URL-encoded IPv4), key 11 (for the URL-encoded IPv6) and key 12 (for the URL-encoded IPv6) separated by &’s (the order doesn’t matter)
  3. Finally, URL-safe base64 (RFC 4648) the entire raw pd string, resulting in the final pd value:
MTA9MTA5LjE1NC45MC4xOCYxMT0yYTAwJTNBMjNjNiUzQWIxODglM0FiZTAxJTNBYjA2NCUzQTU4OWYlM0E5NjA2JTNBZDE4JjEyPU1vemlsbGElMkY1LjAlMjAoV2luZG93cyUyME5UJTIwMTAuMCUzQiUyMFdpbjY0JTNCJTIweDY0KSUyMEFwcGxlV2ViS2l0JTJGNTM3LjM2JTIwKEtIVE1MJTJDJTIwbGlrZSUyMEdlY2tvKSUyMENocm9tZSUyRjEwNS4wLjAuMCUyMFNhZmFyaSUyRjUzNy4zNg==
      4.This string can be passed to ID5 in the pd field in any of our integrations.

Example 2 - Partner wants to pass in Hashed Email, IPv4, IPv6 and User Agent.
  1. Key 1 = Hashed Email =  myuser@domain.com
  2. Key 10= IPv4 = 2a00:23c6:b188:be01:b064:589f:9606:d18
  3. Key 11= IPv6 = 109.154.90.18
  4. Key 12 = User Agent String = Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36
  1. First cleanse the email prior to hashing per the below instructions (not necessary in this case).
  2. , perform a sha256 hash of the email, resulting in a string: b50ca08271795a8e7e4012813f23d505193d75c0f2e2bb99baa63aa822f66ed3 
  3. URL-encode (according to RFC 3986) each value (excluding those that are hashed) using UTF-8 charset.
  4. Create the raw pd string containing the keys 1 (sha256 hash of the email), key 10 (for the URL-encoded IPv4), key 11 (for the URL-encoded IPv6) and key 12 (for the URL-encoded IPv6) separated by &’s (the order doesn’t matter)
  5. Finally, URL-safe base64 (RFC 4648) the entire raw pd string, resulting in the final pd value:
MT1iNTBjYTA4MjcxNzk1YThlN2U0MDEyODEzZjIzZDUwNTE5M2Q3NWMwZjJlMmJiOTliYWE2M2FhODIyZjY2ZWQzJjEwPTEwOS4xNTQuOTAuMTgmMTE9MmEwMCUzQTIzYzYlM0FiMTg4JTNBYmUwMSUzQWIwNjQlM0E1ODlmJTNBOTYwNiUzQWQxOCYxMj1Nb3ppbGxhJTJGNS4wJTIwKFdpbmRvd3MlMjBOVCUyMDEwLjAlM0IlMjBXaW42NCUzQiUyMHg2NCklMjBBcHBsZVdlYktpdCUyRjUzNy4zNiUyMChLSFRNTCUyQyUyMGxpa2UlMjBHZWNrbyklMjBDaHJvbWUlMkYxMDUuMC4wLjAlMjBTYWZhcmklMkY1MzcuMzY=
      6. This string can be passed to ID5 in the pd field in any of our integrations.

Example 3 - Partner wants to pass in Hashed Email, partner specific user ID, IPv4, IPv6 and User Agent.
  1. Key 1 = Hashed Email =  lee.ann.smith@gmail.com 
  2. Key 5= Partner-specific user ID value (this could be a proprietary publisher first party ID for example) =  123456 (note: we discourage the use of special characters in the IDs).
  3. Key 10= IPv4 = 2a00:23c6:b188:be01:b064:589f:9606:d18
  4. Key 11= IPv6 = 109.154.90.18
  5. Key 12 = User Agent String = Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36
  1. First cleanse the email prior to hashing per the below instructions: lee.ann.smith@gmail.com normalizes to leeannsmith@gmail.com
  2. Perform a sha256 hash of the email, resulting in a string: 5790fd18680dcaf166f99322e926f24ba8b13bf05a8fff8ee0eecb89b8974ce4
  3. URL-encode (according to RFC 3986) each value (excluding those that are hashed) using UTF-8 charset.
  4. Create the raw pd string containing the keys 1 (sha256 hash of the email), key 5 (for the URL-encoded partner-specific user ID), key 10 (for the URL-encoded IPv4), key 11 (for the URL-encoded IPv6) and key 12 (for the URL-encoded IPv6) separated by &’s (the order doesn’t matter)
  5. Finally, URL-safe base64 (RFC 4648) the entire raw pd string, resulting in the final pd value:
MT01NzkwZmQxODY4MGRjYWYxNjZmOTkzMjJlOTI2ZjI0YmE4YjEzYmYwNWE4ZmZmOGVlMGVlY2I4OWI4OTc0Y2U0JjU9MTIzNDU2JjEwPTEwOS4xNTQuOTAuMTgmMTE9MmEwMCUzQTIzYzYlM0FiMTg4JTNBYmUwMSUzQWIwNjQlM0E1ODlmJTNBOTYwNiUzQWQxOCYxMj1Nb3ppbGxhJTJGNS4wJTIwKFdpbmRvd3MlMjBOVCUyMDEwLjAlM0IlMjBXaW42NCUzQiUyMHg2NCklMjBBcHBsZVdlYktpdCUyRjUzNy4zNiUyMChLSFRNTCUyQyUyMGxpa2UlMjBHZWNrbyklMjBDaHJvbWUlMkYxMDUuMC4wLjAlMjBTYWZhcmklMkY1MzcuMzY=

Cleansing Emails Prior to Hashing

Prior to hashing an email address, you must cleanse the string by removing unnecessary characters:
  1. Remove leading and trailing spaces
  2. Convert all ASCII characters to lowercase
For email accounts ending in @gmail.com:
  1. Remove leading and trailing spaces.
  2. Convert all ASCII characters to lowercase.
  3. Remove . (ASCII code 46) from the username of the email address. lee.ann.smith@gmail.com normalizes to leeannsmith@gmail.com.
  4. Remove + (ASCII code 43) and all subsequent characters from the username of the email address. leeannsmith+school@gmail.com normalizes to leeannsmith@gmail.com.