diff --git a/docs/guides/integration-advertiser-dataprovider-endpoints.md b/docs/guides/integration-advertiser-dataprovider-endpoints.md index c834ea151..c4d7948c4 100644 --- a/docs/guides/integration-advertiser-dataprovider-endpoints.md +++ b/docs/guides/integration-advertiser-dataprovider-endpoints.md @@ -11,7 +11,7 @@ import Link from '@docusaurus/Link'; # Advertiser/Data Provider Integration to HTTP Endpoints -This guide covers integration steps for advertisers and data providers to integrate with UID2 by writing code to call UID2 HTTP endpoints, rather than using another implementation option such as an SDK, Snowflake, or AWS Entity Resolution. +This guide covers integration steps for advertisers and data providers to integrate with UID2 by writing code to call UID2 HTTP endpoints, rather than using another implementation option such as an SDK, Snowflake, Databricks, or AWS Entity Resolution. :::tip For a summary of all integration options and steps for advertisers and data providers, see [Advertiser/Data Provider Integration Overview](integration-advertiser-dataprovider-overview.md). diff --git a/docs/guides/integration-advertiser-dataprovider-overview.md b/docs/guides/integration-advertiser-dataprovider-overview.md index dff199a95..f30bb6524 100644 --- a/docs/guides/integration-advertiser-dataprovider-overview.md +++ b/docs/guides/integration-advertiser-dataprovider-overview.md @@ -53,7 +53,7 @@ The following table shows the implementation options that are available for adve | High-Level Step | Implementation Options | | --- | --- | -| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | Use any of the following options to map DII to raw UID2s: | +| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | Use any of the following options to map DII to raw UID2s: | | [2: Store Raw UID2s and Refresh Timestamps](#2-store-raw-uid2s-and-refresh-timestamps) | Custom (your choice). | | [3: Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s) | Custom (your choice). | | [4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) | Custom (your choice). | @@ -87,6 +87,8 @@ To generate raw UID2s, use one of the following options: - Snowflake: See [Map DII](integration-snowflake.md#map-dii). +- Databricks: See [Map DII](integration-databricks.md#map-dii). + - AWS Entity Resolution: See [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md). - HTTP endpoints: [POST /identity/map](../endpoints/post-identity-map.md). For details, see [Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii). diff --git a/docs/guides/integration-databricks.md b/docs/guides/integration-databricks.md new file mode 100644 index 000000000..5104e0716 --- /dev/null +++ b/docs/guides/integration-databricks.md @@ -0,0 +1,196 @@ +--- +title: Databricks Integration +sidebar_label: Databricks +pagination_label: Databricks Integration +description: Information about integrating with UID2 through Databricks. +hide_table_of_contents: false +sidebar_position: 04 +displayed_sidebar: docs +--- + +import Link from '@docusaurus/Link'; + +# Databricks Clean Rooms Integration Guide + +This guide is for advertisers and data providers who want to convert their user data to raw UID2s in a Databricks environment. + +## Integration Overview + +This solution enables you to securely share consumer identifier data without exposing sensitive directly identifying information (DII), by processing your data in an instance of the [Databricks Clean Rooms](https://docs.databricks.com/aws/en/clean-rooms/) feature. This feature provides a secure and privacy-protecting environment for working on sensitive data. + +When you've set up the Databricks Clean Rooms environment, you establish a trust relationship with the UID2 service and allow the service to convert your data, which you share in the clean room, to raw UID2s. + + + +## Functionality + +The following table summarizes the functionality available with the UID2 Databricks integration. + +| Encrypt Raw UID2 to UID2 Token for Sharing | Decrypt UID2 Token to Raw UID2 | Generate UID2 Token from DII | Refresh UID2 Token | Map DII to Raw UID2s | +| :--- | :--- | :--- | :--- | :--- | +| — | — | — | — | ✅ | + +## Key Benefits + +Here are some key benefits of integrating with Databricks for your UID2 processing: + +- Native support for managing UID2 workflows within a Databricks data clean room. +- Secure identity interoperability between partner datasets. +- Direct lineage and observability for all UID2-related transformations and joins, for auditing and traceability. +- Streamlined integration between UID2 identifiers and The Trade Desk activation ecosystem. +- Self-service support for marketers and advertisers through Databricks. + +## Integration Steps + +At a high level, the following are the steps to set up your Databricks integration and process your data: + +1. [Create a clean room for UID2 collaboration](#create-clean-room-for-uid2-collaboration). +1. [Send your Databricks sharing identifier to your UID2 contact](#send-sharing-identifier-to-uid2-contact). +1. [Add data to the clean room](#add-data-to-the-clean-room). +1. [Map DII](#map-dii) by running the clean room notebook. + +### Create Clean Room for UID2 Collaboration + +As a starting point, create a Databricks Clean Rooms environment—a secure environment for you to collaborate with UID2 to process your data. + +Follow the steps in [Create clean rooms](https://docs.databricks.com/aws/en/clean-rooms/create-clean-room) in the Databricks documentation. Use the correct sharing identifier based on the [UID2 environment](../getting-started/gs-environments) you want to connect to: see [UID2 Sharing Identifiers](#uid2-sharing-identifiers). + +:::important +After you've created a clean room, you cannot change its collaborators. If you have the option to set clean room collaborator aliases—for example, if you’re using the Databricks Python SDK to create the clean room—your collaborator alias must be `creator` and the UID2 collaborator alias must be `collaborator`. If you’re creating the clean room using the Databricks web UI, the correct collaborator aliases are set for you. +::: + +### Send Sharing Identifier to UID2 Contact + +Before you can use the clean room notebook, you'll need to send your Databricks sharing identifier to your UID2 contact. + +The sharing identifier is a string in this format: `::`. + +Follow these steps: + +1. Find the sharing identifier for the Unity Catalog metastore that is attached to the Databricks workspace where you’ll work with the clean room. + + For information on how to find this value, see [Finding a Sharing Identifier](#finding-a-sharing-identifier). +1. Send the sharing identifier to your UID2 contact. + +### Add Data to the Clean Room + +Add one or more tables or views to the clean room. You can use any names for the schema, tables, and views. Tables and views must follow the schema detailed in [Input Table](#input-table ). + +### Map DII + +Run the `identity_map_v3` Databricks Clean Rooms [notebook](https://docs.databricks.com/aws/en/notebooks/) to map email addresses, phone numbers, or their respective hashes to raw UID2s. + +A successful notebook run results in raw UID2s populated in the output table. For details, see [Output Table](#output-table). + +## Running the Clean Rooms Notebook + +This section provides details to help you use your Databricks Clean Rooms environment to process your DII into raw UID2s, including the following: + +- [Notebook Parameters](#notebook-parameters) +- [Input Table](#input-table) +- [DII Format and Normalization](#dii-format-and-normalization) +- [Output Table](#output-table) +- [Output Table Schema](#output-table-schema) + +### Notebook Parameters + +You can use the `identity_map_v3` notebook to map DII in any table or view that you've added to the `creator` catalog of the clean room. + +The notebook has two parameters, `input_schema` and `input_table`. Together, these two parameters identify the table or view in the clean room that contains the DII to be mapped. + +For example, to map DII in the clean room table named `creator.default.emails`, set `input_schema` to `default` and `input_table` to `emails`. + +| Parameter Name | Description | +| :--- | :--- | +| `input_schema` | The schema containing the table or view. | +| `input_table` | The name you specify for the table or view containing the DII to be mapped. | + +### Input Table + +The input table or view must have the two columns shown in the following table. The table or view can have additional columns, but the notebook doesn't use any additional columns, only these two. + +| Column Name | Data Type | Description | +| :--- | :--- | :--- | +| `INPUT` | string | The DII to map. | +| `INPUT_TYPE` | string | The type of DII to map. Allowed values: `email`, `email_hash`, `phone`, and `phone_hash`. | + +### DII Format and Normalization + +The normalization requirements depend on the type of DII you're processing, as follows: + +- **Email address**: The notebook automatically normalizes the data using the UID2 [Email Address Normalization](../getting-started/gs-normalization-encoding#email-address-normalization) rules. +- **Phone number**: You must normalize the phone number before mapping it with the notebook, using the UID2 [Phone Number Normalization](../getting-started/gs-normalization-encoding#phone-number-normalization) rules. + +### Output Table + +If the clean room has an output catalog, the mapped DII is written to a table in the output catalog. Output tables are stored for 30 days. + +For details, see [Overview of output tables](https://docs.databricks.com/aws/en/clean-rooms/output-tables#overview-of-output-tables) in the Databricks documentation. + +### Output Table Schema + +The following table provides information about the structure of the output data, including field names and values. + +| Column Name | Data Type | Description | +| :--- | :--- | :--- | +| `UID` | string | The value is one of the following:
  • **DII was successfully mapped**: The UID2 associated with the DII.
  • **Otherwise**: `NULL`.
| +| `PREV_UID` | string | The value is one of the following:
  • **DII was successfully mapped and the current raw UID2 was rotated in the last 90 days**: the previous raw UID2.
  • **Otherwise**: `NULL`.
| +| `REFRESH_FROM` | timestamp | The value is one of the following:
  • **DII was successfully mapped**: The timestamp indicating when this UID2 should be refreshed.
  • **Otherwise**: `NULL`.
| +| `UNMAPPED` | string | The value is one of the following:
  • **DII was successfully mapped**: `NULL`.
  • **Otherwise**: The reason why the identifier was not mapped: `OPTOUT`, `INVALID IDENTIFIER`, or `INVALID INPUT TYPE`.
    For details, see [Values for the UNMAPPED Column](#values-for-the-unmapped-column).
| + +#### Values for the UNMAPPED Column + +The following table shows possible values for the `UNMAPPED` column in the output table schema. + +| Value | Meaning | +| :--- | :--- | +| `NULL` | The DII was successfully mapped. | +| `OPTOUT` | The user has opted out. | +| `INVALID IDENTIFIER` | The email address or phone number is invalid. | +| `INVALID INPUT TYPE` | The value of `INPUT_TYPE` is invalid. Valid values for `INPUT_TYPE` are: `email`, `email_hash`, `phone`, `phone_hash`. | + +## Testing in the Integ Environment + +If you'd like to test the Databricks Clean Rooms implementation before signing a UID2 POC, you can ask your UID2 contact for access in the integ (integration) environment. This environment is for testing only, and has no production data. + +In the request, include your sharing identifier. + +While you're waiting to hear back, you can complete the following actions: +- Create the clean room, using the UID2 sharing identifier for the integration environment. +- Put your assets into the clean room. + +For details, see [Integration Steps](#integration-steps). + +When your access is ready, your UID2 contact notifies you. + +## Reference + +This section includes the following reference information: + +- [UID2 Sharing Identifiers](#uid2-sharing-identifiers) +- [Finding a Sharing Identifier](#finding-a-sharing-identifier) + +### UID2 Sharing Identifiers + +UID2 sharing identifiers can change. Before creating a new clean room, check this section to make sure you have the latest sharing identifier. + +| Environment | UID2 Sharing Identifier | +| :--- | :--- | +| Production | `aws:us-east-2:21149de7-a9e9-4463-b4e0-066f4b033e5d:673872910525611:010d98a6-8cf2-4011-8bf7-ca45940bc329` | +| Integration | `aws:us-east-2:4651b4ea-b29c-42ec-aecb-2377de70bbd4:2366823546528067:c15e03bf-a348-4189-92e5-68b9a7fb4018` | + +### Finding a Sharing Identifier + +To find the sharing identifier for your UID2 contact, follow these steps: + +In your Databricks workspace, in the Catalog Explorer, click **Catalog**. + +At the top, click the gear icon and select **Delta Sharing**. + +On the **Shared with me** tab, in the upper right, click your Databricks sharing organization and then select **Copy sharing identifier**. + +For details, see [Request the recipient's sharing identifier](https://docs.databricks.com/aws/en/delta-sharing/create-recipient#step-1-request-the-recipients-sharing-identifier) in the Databricks documentation. diff --git a/docs/guides/summary-guides.md b/docs/guides/summary-guides.md index 4c2ca4727..8111111ca 100644 --- a/docs/guides/summary-guides.md +++ b/docs/guides/summary-guides.md @@ -101,7 +101,8 @@ The following documentation resources are available for advertisers and data pro | Integration Guide | Content Description | | :--- | :--- | | [Advertiser/Data Provider Overview](integration-advertiser-dataprovider-overview.md) | This guide provides an overview of integration options for organizations that collect user data and push it to other UID2 participants. | -| [Snowflake Integration Guide](integration-snowflake.md) | Instructions for generating UID2s from emails within Snowflake. | +| [Snowflake Integration Guide](integration-snowflake.md) | Instructions for generating UID2s from emails or phone numbers within Snowflake. | +| [Databricks Clean Rooms Integration Guide](integration-databricks.md) | Instructions for generating UID2s from emails or phone numbers in a Databricks Clean Rooms environment. | | [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) | Instructions for integrating with the UID2 framework using AWS Entity Resolution. | | [Advertiser/Data Provider Integration to HTTP Endpoints](integration-advertiser-dataprovider-endpoints.md) | This guide covers integration steps for advertisers and data providers to integrate with UID2 by writing code to call UID2 HTTP endpoints, rather than using another implementation option such as an SDK, Snowflake, or AWS Entity Resolution. | | [Client-Side Integration Guide for JavaScript](integration-javascript-client-side.md) | A guide for advertisers and data providers who want to use this SDK for adding a UID2 token to their tracking pixels. | diff --git a/docs/overviews/overview-advertisers.md b/docs/overviews/overview-advertisers.md index bd4b5151d..c9a9b5eb1 100644 --- a/docs/overviews/overview-advertisers.md +++ b/docs/overviews/overview-advertisers.md @@ -75,7 +75,8 @@ The following documentation resources are available for advertisers and data pro | Integration Type| Documentation | Content Description | | :--- | :--- | :--- | | Overview of integration options for organizations that collect user data and push it to other UID2 participants | [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) | This guide covers integration workflows for mapping identity for audience-building and targeting. | -| Snowflake | [Snowflake Integration Guide](../guides/integration-snowflake.md) | This guide provides instructions for generating UID2s from emails within Snowflake. | +| Snowflake | [Snowflake Integration Guide](../guides/integration-snowflake.md) | This guide provides instructions for generating UID2s from emails or phone numbers within Snowflake. | +| Databricks Clean Rooms | [Databricks Clean Rooms Integration Guide](../guides/integration-databricks.md) | This guide provides instructions for generating UID2s from emails or phone numbers in a Databricks Clean Rooms environment. | | AWS Entity Resolution | [AWS Entity Resolution Integration Guide](../guides/integration-aws-entity-resolution.md) | This guide provides instructions for integrating with the UID2 framework using AWS Entity Resolution. | | Integration steps for organizations that collect user data and push it to other UID2 participants, using UID2 HTTP endpoints only | [Advertiser/Data Provider Integration to HTTP Endpoints](../guides/integration-advertiser-dataprovider-endpoints.md) | This guide covers integration steps for advertisers and data providers to integrate with UID2 by writing code to call UID2 HTTP endpoints, rather than using another implementation option such as an SDK, Snowflake, or AWS Entity Resolution. | | Integration steps for advertisers and data providers who want to use the client-side JavaScript SDK for adding a UID2 token to their tracking pixels. | [Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md) | This guide provides instructions for generating UID2 tokens (advertising tokens) using only JavaScript client-side changes. | diff --git a/docs/overviews/overview-data-providers.md b/docs/overviews/overview-data-providers.md index 9da97cbfa..a3b807c45 100644 --- a/docs/overviews/overview-data-providers.md +++ b/docs/overviews/overview-data-providers.md @@ -80,7 +80,8 @@ The following documentation resources are available for advertisers and data pro | Integration Type| Documentation | Content Description | | :--- | :--- | :--- | | Overview of integration options for organizations that collect user data and push it to other UID2 participants | [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) | This guide covers integration workflows for mapping identity for audience-building and targeting. | -| Snowflake | [Snowflake Integration Guide](../guides/integration-snowflake.md) | This guide provides instructions for generating UID2s from emails within Snowflake. | +| Snowflake | [Snowflake Integration Guide](../guides/integration-snowflake.md) | This guide provides instructions for generating UID2s from emails or phone numbers within Snowflake. | +| Databricks Clean Rooms | [Databricks Clean Rooms Integration Guide](../guides/integration-databricks.md) | This guide provides instructions for generating UID2s from emails or phone numbers in a Databricks Clean Rooms environment. | | AWS Entity Resolution | [AWS Entity Resolution Integration Guide](../guides/integration-aws-entity-resolution.md) | This guide provides instructions for integrating with the UID2 framework using AWS Entity Resolution. | | Integration steps for organizations that collect user data and push it to other UID2 participants, using UID2 HTTP endpoints only | [Advertiser/Data Provider Integration to HTTP Endpoints](../guides/integration-advertiser-dataprovider-endpoints.md) | This guide covers integration steps for advertisers and data providers to integrate with UID2 by writing code to call UID2 HTTP endpoints, rather than using another implementation option such as an SDK, Snowflake, or AWS Entity Resolution. | | Integration steps for advertisers and data providers who want to use the client-side JavaScript SDK for adding a UID2 token to their tracking pixels. | [Client-Side Integration Guide for JavaScript](../guides/integration-javascript-client-side.md) | This guide provides instructions for generating UID2 tokens (advertising tokens) using only JavaScript client-side changes. | diff --git a/docs/ref-info/updates-doc.md b/docs/ref-info/updates-doc.md index 539cb71c9..a61fe8735 100644 --- a/docs/ref-info/updates-doc.md +++ b/docs/ref-info/updates-doc.md @@ -20,6 +20,24 @@ Check out the latest updates to our UID2 documentation resources. Use the Tags toolbar to view a subset of documentation updates. ::: +## Q4 2025 + +The following documents were released in this quarter. + + + +### Databricks Integration Guide + +November 25, 2025 + +We've added an integration guide for the UID2 Databricks integration. + +For details, see [UID2 Databricks Clean Rooms Integration Guide](../guides/integration-databricks.md). + + + + + ## Q3 2025 The following documents were released in this quarter. @@ -37,13 +55,13 @@ We updated the following additional implementations and corresponding documentat - Python SDK: see [SDK for Python Reference Guide](../sdks/sdk-ref-python.md) - Snowflake: see [Snowflake Integration Guide](../guides/integration-snowflake.md) - + -### Identity Map v3 +### Identity Map v3 (Endpoint Doc) July 11, 2025 diff --git a/docs/summary-doc-v2.md b/docs/summary-doc-v2.md index e844ace25..3124b91ff 100644 --- a/docs/summary-doc-v2.md +++ b/docs/summary-doc-v2.md @@ -18,5 +18,5 @@ For details on using the API, see the following pages. | :--- | :--- | | [Encrypting Requests and Decrypting Responses](getting-started/gs-encryption-decryption.md) | The high-level request-response workflow for the UID2 APIs, requirements for encrypting requests and decrypting responses, and respective script examples in different programming languages. | | [Endpoints](endpoints/summary-endpoints.md) | The API reference for managing identity tokens and mapping email addresses, phone numbers, or hashes to their UID2s and salt bucket IDs used to generate the UID2s.
NOTE: The integration environment and the production environment require different [API keys](ref-info/glossary-uid.md#gl-api-key). | -| [Integration Guides](guides/summary-guides.md) | The UID2 integration workflows for UID2 participants, such as publishers, DSPs, advertisers, and data providers, as well as Operator Enterprise Partners, such as Microsoft Azure, AWS, and Snowflake. | +| [Integration Guides](guides/summary-guides.md) | The UID2 integration workflows for UID2 participants, such as publishers, DSPs, advertisers, and data providers, as well as Operator Enterprise Partners, such as Microsoft Azure, AWS, Snowflake, and Databricks. | | [SDKs](sdks/summary-sdks.md) | Links to documentation for using UID2 SDKs. | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-databricks.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-databricks.md new file mode 100644 index 000000000..5104e0716 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-databricks.md @@ -0,0 +1,196 @@ +--- +title: Databricks Integration +sidebar_label: Databricks +pagination_label: Databricks Integration +description: Information about integrating with UID2 through Databricks. +hide_table_of_contents: false +sidebar_position: 04 +displayed_sidebar: docs +--- + +import Link from '@docusaurus/Link'; + +# Databricks Clean Rooms Integration Guide + +This guide is for advertisers and data providers who want to convert their user data to raw UID2s in a Databricks environment. + +## Integration Overview + +This solution enables you to securely share consumer identifier data without exposing sensitive directly identifying information (DII), by processing your data in an instance of the [Databricks Clean Rooms](https://docs.databricks.com/aws/en/clean-rooms/) feature. This feature provides a secure and privacy-protecting environment for working on sensitive data. + +When you've set up the Databricks Clean Rooms environment, you establish a trust relationship with the UID2 service and allow the service to convert your data, which you share in the clean room, to raw UID2s. + + + +## Functionality + +The following table summarizes the functionality available with the UID2 Databricks integration. + +| Encrypt Raw UID2 to UID2 Token for Sharing | Decrypt UID2 Token to Raw UID2 | Generate UID2 Token from DII | Refresh UID2 Token | Map DII to Raw UID2s | +| :--- | :--- | :--- | :--- | :--- | +| — | — | — | — | ✅ | + +## Key Benefits + +Here are some key benefits of integrating with Databricks for your UID2 processing: + +- Native support for managing UID2 workflows within a Databricks data clean room. +- Secure identity interoperability between partner datasets. +- Direct lineage and observability for all UID2-related transformations and joins, for auditing and traceability. +- Streamlined integration between UID2 identifiers and The Trade Desk activation ecosystem. +- Self-service support for marketers and advertisers through Databricks. + +## Integration Steps + +At a high level, the following are the steps to set up your Databricks integration and process your data: + +1. [Create a clean room for UID2 collaboration](#create-clean-room-for-uid2-collaboration). +1. [Send your Databricks sharing identifier to your UID2 contact](#send-sharing-identifier-to-uid2-contact). +1. [Add data to the clean room](#add-data-to-the-clean-room). +1. [Map DII](#map-dii) by running the clean room notebook. + +### Create Clean Room for UID2 Collaboration + +As a starting point, create a Databricks Clean Rooms environment—a secure environment for you to collaborate with UID2 to process your data. + +Follow the steps in [Create clean rooms](https://docs.databricks.com/aws/en/clean-rooms/create-clean-room) in the Databricks documentation. Use the correct sharing identifier based on the [UID2 environment](../getting-started/gs-environments) you want to connect to: see [UID2 Sharing Identifiers](#uid2-sharing-identifiers). + +:::important +After you've created a clean room, you cannot change its collaborators. If you have the option to set clean room collaborator aliases—for example, if you’re using the Databricks Python SDK to create the clean room—your collaborator alias must be `creator` and the UID2 collaborator alias must be `collaborator`. If you’re creating the clean room using the Databricks web UI, the correct collaborator aliases are set for you. +::: + +### Send Sharing Identifier to UID2 Contact + +Before you can use the clean room notebook, you'll need to send your Databricks sharing identifier to your UID2 contact. + +The sharing identifier is a string in this format: `::`. + +Follow these steps: + +1. Find the sharing identifier for the Unity Catalog metastore that is attached to the Databricks workspace where you’ll work with the clean room. + + For information on how to find this value, see [Finding a Sharing Identifier](#finding-a-sharing-identifier). +1. Send the sharing identifier to your UID2 contact. + +### Add Data to the Clean Room + +Add one or more tables or views to the clean room. You can use any names for the schema, tables, and views. Tables and views must follow the schema detailed in [Input Table](#input-table ). + +### Map DII + +Run the `identity_map_v3` Databricks Clean Rooms [notebook](https://docs.databricks.com/aws/en/notebooks/) to map email addresses, phone numbers, or their respective hashes to raw UID2s. + +A successful notebook run results in raw UID2s populated in the output table. For details, see [Output Table](#output-table). + +## Running the Clean Rooms Notebook + +This section provides details to help you use your Databricks Clean Rooms environment to process your DII into raw UID2s, including the following: + +- [Notebook Parameters](#notebook-parameters) +- [Input Table](#input-table) +- [DII Format and Normalization](#dii-format-and-normalization) +- [Output Table](#output-table) +- [Output Table Schema](#output-table-schema) + +### Notebook Parameters + +You can use the `identity_map_v3` notebook to map DII in any table or view that you've added to the `creator` catalog of the clean room. + +The notebook has two parameters, `input_schema` and `input_table`. Together, these two parameters identify the table or view in the clean room that contains the DII to be mapped. + +For example, to map DII in the clean room table named `creator.default.emails`, set `input_schema` to `default` and `input_table` to `emails`. + +| Parameter Name | Description | +| :--- | :--- | +| `input_schema` | The schema containing the table or view. | +| `input_table` | The name you specify for the table or view containing the DII to be mapped. | + +### Input Table + +The input table or view must have the two columns shown in the following table. The table or view can have additional columns, but the notebook doesn't use any additional columns, only these two. + +| Column Name | Data Type | Description | +| :--- | :--- | :--- | +| `INPUT` | string | The DII to map. | +| `INPUT_TYPE` | string | The type of DII to map. Allowed values: `email`, `email_hash`, `phone`, and `phone_hash`. | + +### DII Format and Normalization + +The normalization requirements depend on the type of DII you're processing, as follows: + +- **Email address**: The notebook automatically normalizes the data using the UID2 [Email Address Normalization](../getting-started/gs-normalization-encoding#email-address-normalization) rules. +- **Phone number**: You must normalize the phone number before mapping it with the notebook, using the UID2 [Phone Number Normalization](../getting-started/gs-normalization-encoding#phone-number-normalization) rules. + +### Output Table + +If the clean room has an output catalog, the mapped DII is written to a table in the output catalog. Output tables are stored for 30 days. + +For details, see [Overview of output tables](https://docs.databricks.com/aws/en/clean-rooms/output-tables#overview-of-output-tables) in the Databricks documentation. + +### Output Table Schema + +The following table provides information about the structure of the output data, including field names and values. + +| Column Name | Data Type | Description | +| :--- | :--- | :--- | +| `UID` | string | The value is one of the following:
  • **DII was successfully mapped**: The UID2 associated with the DII.
  • **Otherwise**: `NULL`.
| +| `PREV_UID` | string | The value is one of the following:
  • **DII was successfully mapped and the current raw UID2 was rotated in the last 90 days**: the previous raw UID2.
  • **Otherwise**: `NULL`.
| +| `REFRESH_FROM` | timestamp | The value is one of the following:
  • **DII was successfully mapped**: The timestamp indicating when this UID2 should be refreshed.
  • **Otherwise**: `NULL`.
| +| `UNMAPPED` | string | The value is one of the following:
  • **DII was successfully mapped**: `NULL`.
  • **Otherwise**: The reason why the identifier was not mapped: `OPTOUT`, `INVALID IDENTIFIER`, or `INVALID INPUT TYPE`.
    For details, see [Values for the UNMAPPED Column](#values-for-the-unmapped-column).
| + +#### Values for the UNMAPPED Column + +The following table shows possible values for the `UNMAPPED` column in the output table schema. + +| Value | Meaning | +| :--- | :--- | +| `NULL` | The DII was successfully mapped. | +| `OPTOUT` | The user has opted out. | +| `INVALID IDENTIFIER` | The email address or phone number is invalid. | +| `INVALID INPUT TYPE` | The value of `INPUT_TYPE` is invalid. Valid values for `INPUT_TYPE` are: `email`, `email_hash`, `phone`, `phone_hash`. | + +## Testing in the Integ Environment + +If you'd like to test the Databricks Clean Rooms implementation before signing a UID2 POC, you can ask your UID2 contact for access in the integ (integration) environment. This environment is for testing only, and has no production data. + +In the request, include your sharing identifier. + +While you're waiting to hear back, you can complete the following actions: +- Create the clean room, using the UID2 sharing identifier for the integration environment. +- Put your assets into the clean room. + +For details, see [Integration Steps](#integration-steps). + +When your access is ready, your UID2 contact notifies you. + +## Reference + +This section includes the following reference information: + +- [UID2 Sharing Identifiers](#uid2-sharing-identifiers) +- [Finding a Sharing Identifier](#finding-a-sharing-identifier) + +### UID2 Sharing Identifiers + +UID2 sharing identifiers can change. Before creating a new clean room, check this section to make sure you have the latest sharing identifier. + +| Environment | UID2 Sharing Identifier | +| :--- | :--- | +| Production | `aws:us-east-2:21149de7-a9e9-4463-b4e0-066f4b033e5d:673872910525611:010d98a6-8cf2-4011-8bf7-ca45940bc329` | +| Integration | `aws:us-east-2:4651b4ea-b29c-42ec-aecb-2377de70bbd4:2366823546528067:c15e03bf-a348-4189-92e5-68b9a7fb4018` | + +### Finding a Sharing Identifier + +To find the sharing identifier for your UID2 contact, follow these steps: + +In your Databricks workspace, in the Catalog Explorer, click **Catalog**. + +At the top, click the gear icon and select **Delta Sharing**. + +On the **Shared with me** tab, in the upper right, click your Databricks sharing organization and then select **Copy sharing identifier**. + +For details, see [Request the recipient's sharing identifier](https://docs.databricks.com/aws/en/delta-sharing/create-recipient#step-1-request-the-recipients-sharing-identifier) in the Databricks documentation. diff --git a/sidebars.js b/sidebars.js index 927ef691e..bff237bd5 100644 --- a/sidebars.js +++ b/sidebars.js @@ -236,7 +236,8 @@ const fullSidebar = [ ], }, - 'guides/integration-aws-entity-resolution', + 'guides/integration-databricks', + 'guides/integration-aws-entity-resolution', 'guides/integration-advertiser-dataprovider-endpoints', ], }, @@ -408,6 +409,7 @@ const sidebars = { 'guides/integration-advertiser-dataprovider-overview', 'guides/integration-snowflake', 'guides/integration-snowflake-previous', + 'guides/integration-databricks', 'guides/integration-aws-entity-resolution', 'guides/advertiser-dataprovider-endpoints', 'DSP Integrations', @@ -494,7 +496,8 @@ const sidebars = { 'Advertiser/Data Provider Integrations', 'guides/integration-advertiser-dataprovider-overview', 'guides/integration-snowflake', - 'guides/integration-snowflake-integration-snowflake-previous', + 'guides/integration-snowflake-previous', + 'guides/integration-databricks', 'guides/integration-aws-entity-resolution', 'guides/advertiser-dataprovider-endpoints', 'sharing/sharing-bid-stream'