Advertiser/Data Provider Integration Overview
This guide provides an overview of integration options for organizations that collect user data and push it to other EUID participants. Data collectors include advertisers, data on-boarders, measurement providers, identity graph providers, third-party data providers, and any other organizations that send data to other participants.
Advertiser/Data Provider Routes to Use EUID
Within the ad tech industry, advertisers use identity to build audiences, track conversions, and generate their graphs. As an advertiser, or as a data provider acting on behalf of an advertiser, the following table shows some examples of how you can accomplish some of these goals with EUID.
There are other ways that you can use EUID, outside these use cases. These are just some examples.
Send/Receive? | Action | Advantage/Result |
---|---|---|
Send in audiences | Send raw EUIDs via API or pixels | Create audiences. |
Send in conversions | Send raw EUIDs as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. |
Receive graph data | Receive raw EUIDs from graph/data providers via API or pixels | Build graph data. |
High-Level Steps
At a high level, the steps for advertisers and data providers integrating with EUID are as follows:
If your implementation uses a version of the POST /identity/map endpoint earlier than version 3, see Using POST /identity/map Version 2. If you're using this version, we recommend you upgrade as soon as possible to take advantage of the enhancements.
Summary of Implementation Options
The following table shows the implementation options that are available for advertisers and data providers, for each of the high-level steps. Some steps are managed solely as part of your own custom implementation; some steps can be managed by one or more of the EUID implementation options available. For details, click the link on each step.
High-Level Step | Implementation Options |
---|---|
1: Generate Raw EUIDs from Personal Data | Use any of the following options to map personal data to raw EUIDs:
|
2: Store Raw EUIDs and Refresh Timestamps | Custom (your choice). |
3: Manipulate or Combine Raw EUIDs | Custom (your choice). |
4: Send Stored Raw EUIDs to DSPs to Create Audiences or Conversions | Custom (your choice). |
5: Monitor for Raw EUID Refresh | Use the refresh timestamp (r field) returned from the POST /identity/map endpoint to determine when to refresh Raw EUIDs. |
6: Monitor for Opt-Out Status | API call to the POST /optout/status endpoint. |
Integration Diagram
The following diagram outlines the steps that data collectors must complete to map personal data to raw EUIDs for audience building and targeting.
Personal data refers to a user's normalized email address or phone number, or the normalized and SHA-256-hashed email address or phone number.
To keep your EUID-based audience information accurate and up to date, follow these integration steps every day.
For details about the different parts of the diagram, refer to the following sections.
1: Generate Raw EUIDs from Personal Data
You can generate raw EUIDs from personal data, or receive EUIDs from another EUID participant such as a data provider acting on your behalf.
To generate raw EUIDs, use one of the following options:
-
One of the EUID SDKs:
- Python SDK: See Map Personal Data to Raw EUIDs.
- Java SDK: See Usage for Advertisers/Data Providers.
-
Snowflake: See Map Personal Data.
-
HTTP endpoints: POST /identity/map. For details, see Generate Raw EUIDs from Personal Data.
2: Store Raw EUIDs and Refresh Timestamps
The response from Step 1, Generate Raw EUIDs from Personal Data, contains mapping information. We recommend that you store the following information returned in Step 1:
- Cache the mapping between personal data and raw EUID (
u
field). - Store the refresh timestamp (
r
field) to know when the raw EUID could refresh. - Optionally store the previous raw EUID (
p
field) if provided for users whose EUID was refreshed within the last 90 days.
3: Manipulate or Combine Raw EUIDs
Use the raw EUIDs you received in Step 1. For example, you might do one or more of the following:
- Do some manipulation: for example, combine raw EUIDs you generated from personal data and raw EUIDs received from another participant such as an advertiser or data provider.
- Add new raw EUIDs into an existing audience.
4: Send Stored Raw EUIDs to DSPs to Create Audiences or Conversions
Use the raw EUIDs for some purpose such as:
- Sending stored raw EUIDs to DSPs to create audiences and conversions.
- Using the raw EUIDs for measurement.
For example, you could send the (raw EUID (u
field) returned in Step 1 to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw EUIDs to build an audience.
You could also send conversion information via API or pixels for measurement (attribution) or for retargeting.
5: Monitor for Raw EUID Refresh
A raw EUID is an identifier for a user at a specific moment in time. The raw EUID for a specific user changes roughly once per year as part of the EUID refresh process.
The v3 Identity Map API provides a refresh timestamp (r
field) in the response that indicates when each raw EUID might refresh. Use this timestamp to determine when to regenerate raw EUIDs for your stored data. It is guaranteed that it won't refresh before that time.
We recommend checking for refresh opportunities daily. To determine whether to refresh a raw EUID:
-
Compare the current time with the refresh timestamp (
r
field) you stored from the POST /identity/map response. -
If the current time is greater than or equal to the refresh timestamp, regenerate the raw EUID by calling POST /identity/map again with the same personal data.
This approach ensures your raw EUIDs remain current and valid for audience targeting and measurement.
6: Monitor for Opt-Out Status
It's important to honor user opt-out status. Periodically, monitor for opt-out status, to be sure that you don't continue using raw EUIDs for users that have recently opted out.
There are two ways that you can check with the EUID Operator Service to make sure you have the latest opt-out information:
-
Call the POST /identity/map endpoint to check for opt-outs. If the personal data has been opted out, no raw EUID is generated.
-
Check the opt-out status of raw EUIDs using the POST /optout/status endpoint.
For details about the EUID opt-out workflow and how users can opt out, see User Opt-Out.
Using POST /identity/map Version 2
The following information is relevant only to integration approaches that use an earlier version of the POST /identity/map
endpoint, version 2, and is provided for reference only. New implementations should use the latest version: see High-Level Steps.
The key differences when using v2 of the Identity Map API are:
- Step 2: Store salt bucket IDs instead of refresh timestamps
- Step 5: Monitor for salt bucket rotations instead of using refresh timestamps
All other steps (1, 3, 4, and 6) are the same as described in the v3 implementation: see High-Level Steps.
Integration Diagram (v2)
The following diagram outlines the v2 integration flow. Note that the main differences are in Step 2 (storing salt bucket IDs) and Step 5 (monitoring salt bucket rotations).
Store Raw EUIDs and Salt Bucket IDs (v2)
This step replaces Step 2 in the v3 implementation.
The response from Step 1 contains mapping information. We recommend that you store the following information returned in Step 1:
- Cache the mapping between personal data (
identifier
), raw EUID (advertising_id
), and salt bucket (bucket_id
). - Store the timestamp for when you received the response data. Later, you can compare this timestamp with the
last_updated
timestamp returned in Step 5.
Monitor for Salt Bucket Rotations for Your Stored Raw EUIDs (v2)
This step replaces Step 5 in the v3 implementation.
A raw EUID is an identifier for a user at a specific moment in time. The raw EUID for a specific user changes roughly once per year, as a result of the salt bucket rotation.
Even though each salt bucket is updated approximately once per year, individual bucket updates are spread over the year. Approximately 1/365th of all salt buckets are rotated daily. Based on this, we recommend checking salt bucket rotation regularly, on a cadence that aligns with your audience refreshes. For example, if you refresh weekly, check for salt bucket updates weekly.
If the salt bucket has been rotated, regenerate the raw EUID. For details, see Determine whether the salt bucket has been rotated.
For instructions for monitoring for salt bucket rotations, refer to one of the following:
-
Python SDK: Monitor Rotated Salt Buckets.
-
Snowflake: Monitor for Salt Bucket Rotation and Regenerate Raw EUIDs.
-
HTTP endpoints: Monitor for Salt Bucket Rotations for Your Stored Raw EUIDs (v2).
Determine whether the salt bucket has been rotated (v2)
To determine whether the salt bucket ID for a specific raw EUID has changed, follow these steps.
- Compare these two values:
-
The
last_updated
timestamp of eachbucket_id
returned as part of monitoring the salt bucket rotations (whatever option you choose). -
The timestamp of the raw EUID generation of the same
bucket_id
, which was returned in Step 1 and stored in Step 2.
- If the
last_updated
timestamp is more recent than the timestamp you recorded earlier, the salt bucket has been rotated. As a result, you'll need to regenerate any raw EUIDs associated with thisbucket_id
, following Step 1, Generate Raw EUIDs from Personal Data.
FAQs
For a list of frequently asked questions for advertisers and data providers using the EUID framework, see FAQs for Advertisers and Data Providers.