Advertiser/Data Provider Integration Overview

This guide provides an overview of integration options for organizations that collect user data and push it to other UID2 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 UID2

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 UID2.

note

There are other ways that you can use UID2, outside these use cases. These are just some examples.

Send/Receive?	Action	Advantage/Result
Send in audiences	Send UID2s via API or pixels	Create audiences.
Send in conversions	Send UID2s as conversion information	Use conversion information for measurement (attribution) or for retargeting via API or pixels.
Receive graph data	Receive UID2s 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 UID2 are as follows:

1. Generate Raw UID2s from DII

2. Store Raw UID2s and Salt Bucket IDs

3. Manipulate or Combine Raw UID2s

4. Send Stored Raw UID2s to DSPs to Create Audiences or Conversions

5. Monitor for Salt Bucket Rotations for Your Stored Raw UID2s

6. Monitor for Opt-Out Status

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 UID2 implementation options available. For details, click the link on each step.

High-Level Step	Implementation Options
1: Generate Raw UID2s from DII	Use any of the following options to map DII to raw UID2s: One of these UID2 SDKs: Python SDK: Map DII to Raw UID2s Java SDK: Usage for Advertisers/Data Providers Snowflake: Map DII AWS Entity Resolution: AWS Entity Resolution Integration Guide HTTP endpoints: POST /identity/map
2: Store Raw UID2s and Salt Bucket IDs	Custom (your choice).
3: Manipulate or Combine Raw UID2s	Custom (your choice).
4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions	Custom (your choice).
5: Monitor for Salt Bucket Rotations for Your Stored Raw UID2s	Any of the following options: Python SDK: see SDK for Python Reference Guide Snowflake: see Snowflake Integration Guide, section titled Monitor for Salt Bucket Rotation and Regenerate Raw UID2s Raw HTTP endpoint: POST /identity/buckets
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 DII to raw UID2s for audience building and targeting.

DII 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 UID2-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 UID2s from DII

You can generate raw UID2s from directly identifying information (DII), or receive UID2s from another UID2 participant such as a data provider acting on your behalf.

To generate raw UID2s, use one of the following options:

• One of the UID2 SDKs:

  • Python SDK: See Map DII to Raw UID2s.
  • Java SDK: See Usage for Advertisers/Data Providers.

• Snowflake: See Map DII.

• AWS Entity Resolution: See AWS Entity Resolution Integration Guide.

• HTTP endpoints: POST /identity/map. For details, see Generate Raw UID2s from DII.

2: Store Raw UID2s and Salt Bucket IDs

The response from Step 1, Generate Raw UID2s from DII, contains mapping information. We recommend that you store the following information returned in Step 1:

• Cache the mapping between DII (identifier), raw UID2 (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 UID2s.

3: Manipulate or Combine Raw UID2s

Use the UID2s you received in Step 1. For example, you might do one or more of the following:

• Do some manipulation: for example, combine UID2s you generated from DII and UID2s received from another participant such as an advertiser or data provider.
• Add new UID2s into an existing audience.

4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions

Use the raw UID2s for some purpose such as:

• Sending stored raw UID2s to DSPs to create audiences and conversions.
• Using the raw UID2s for measurement.

For example, you could send the advertising_id (raw UID2) returned in Step 1-b 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 UID2s to build an audience.

You could also send conversion information via API or pixels for measurement (attribution) or for retargeting.

5: Monitor for Salt Bucket Rotations for Your Stored Raw UID2s

A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least 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 UID2. 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 UID2s.

• HTTP endpoints: Monitor for Salt Bucket Rotations for Your Stored Raw UID2s.

note

For AWS Entity Resolution, there is no way to do salt bucket monitoring. As an alternative, you could regenerate raw UID2s periodically using the AWS Entity Resolution service.

Determine whether the salt bucket has been rotated

To determine whether the salt bucket ID for a specific raw UID2 has changed, follow these steps.

1. Compare these two values:

   • The last_updated timestamp of each bucket_id returned as part of monitoring the salt bucket rotations (whatever option you choose).

   • The timestamp of the raw UID2 generation of the same bucket_id, which was returned in Step 1 and stored in Step 2.

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 UID2s associated with this bucket_id, following Step 1, Generate Raw UID2s from DII.

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 UID2s for users that have recently opted out.

There are two ways that you can check with the UID2 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 DII has been opted out, no raw UID2 is generated.

• Check the opt-out status of raw UID2s using the POST /optout/status endpoint.

For details about the UID2 opt-out workflow and how users can opt out, see User Opt-Out.

FAQs

For a list of frequently asked questions for advertisers and data providers using the UID2 framework, see FAQs for Advertisers and Data Providers.