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
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
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
An IAB TechLab Tokenization Framework token (e.g. uid2)
Optional

Deriving the Partner Data (pd) Value

Suppose you have an email address for a user, in this example it is myuser@domain.com, and want to share it with ID5 to strengthen the value of the UID we respond with. You also have your own user id for this user that you can share: möller&françois (note: we discourage the use of special characters in the IDs, this is just for illustration purposes). Except for values that are sha256-hashed, in general other values should be URL-encoded (according to RFC 3986) using UTF-8 charset. 

First, perform a sha256 hash of the email, resulting in a string:
b50ca08271795a8e7e4012813f23d505193d75c0f2e2bb99baa63aa822f66ed3
Next, create the raw pd string containing the keys 1 (for the hashed email) and 5 (for the URL-encoded user id), separated by &’s (the order doesn’t matter):
1=b50ca08271795a8e7e4012813f23d505193d75c0f2e2bb99baa63aa822f66ed3&5=m%C3%B6ller%26fran%C3%A7ois
Finally, URL-safe base64 (RFC 4648) the entire raw pd string, resulting in the final pd value:
MT1iNTBjYTA4MjcxNzk1YThlN2U0MDEyODEzZjIzZDUwNTE5M2Q3NWMwZjJlMmJiOTliYWE2M2FhODIyZjY2ZWQzJjU9bSVDMyVCNmxsZXIlMjZmcmFuJUMzJUE3b2lz
This string can be passed to ID5 in the pd field in any of our integrations.

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.