diff --git a/.idea/.gitignore b/.idea/.gitignore deleted file mode 100644 index 13566b81b..000000000 --- a/.idea/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -# Default ignored files -/shelf/ -/workspace.xml -# Editor-based HTTP Client requests -/httpRequests/ -# Datasource local storage ignored files -/dataSources/ -/dataSources.local.xml diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md index 781f25e91..604936e00 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -19,8 +19,8 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User This documentation is for version 2 of this endpoint, which is not the latest version. For the latest version, v3, see [POST /identity/map](post-identity-map.md). -:::note -If you're using an earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from v2 Identity Map](post-identity-map.md#migration-from-v2-identity-map). For deprecation information, see [Deprecation Schedule: Endpoint Versions](../ref-info/deprecation-schedule.md#endpoint-versions). +:::important +If you're using the v2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration from v2 Identity Map](post-identity-map.md#migration-from-v2-identity-map). For deprecation information, see [Deprecation Schedule: Endpoint Versions](../ref-info/deprecation-schedule.md#endpoint-versions). ::: ## Batch Size and Request Parallelization Requirements diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index a71142121..c89d35d97 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -213,7 +213,7 @@ The following sections provide general information and guidance for migrating to The following table shows key differences between the versions. -| Feature | v2 Implementation | v3 Implementation | +| Feature | V2 Implementation | V3 Implementation | |:-------------------------------|:--------------------------------------------|:-------------------------------------------| | Endpoints Required | `/v2/identity/map` + `/v2/identity/buckets` | `/v3/identity/map` only | | Identity Types per Request | Single identity type only | Multiple identity types | @@ -225,7 +225,7 @@ The following table shows key differences between the versions. To upgrade from an earlier version to version 3, follow these steps: 1. [Update Endpoint URL](#1-update-endpoint-url) -2. [Update v3 Response Parsing Logic](#2-update-v3-response-parsing-logic) +2. [Update V3 Response Parsing Logic](#2-update-v3-response-parsing-logic) 3. [Replace Salt Bucket Monitoring with Refresh Timestamp Logic](#3-replace-salt-bucket-monitoring-with-refresh-timestamp-logic) #### 1. Update Endpoint URL @@ -244,7 +244,7 @@ url = '/v3/identity/map' Update the logic for parsing the response, as shown in the following example. -v2 Response Parsing: +V2 Response Parsing: ```python # v2: Process mapped/unmapped objects with identifier lookup for item in response['body']['mapped']: @@ -255,7 +255,7 @@ for item in response['body']['mapped']: store_mapping(original_identifier, raw_uid, bucket_id) ``` -v3 Response Parsing: +V3 Response Parsing: ```python # v3: Process array-indexed responses for index, item in enumerate(response['body']['email']): diff --git a/docs/guides/integration-advertiser-dataprovider-overview.md b/docs/guides/integration-advertiser-dataprovider-overview.md index ed1e775c5..ad77d0850 100644 --- a/docs/guides/integration-advertiser-dataprovider-overview.md +++ b/docs/guides/integration-advertiser-dataprovider-overview.md @@ -191,7 +191,7 @@ For instructions for monitoring for salt bucket rotations, refer to one of the f - Python SDK: [Monitor Rotated Salt Buckets](../sdks/sdk-ref-python.md#monitor-rotated-salt-buckets). -- Snowflake: [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](integration-snowflake-before-july-2025.md#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s). +- Snowflake: [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](integration-snowflake.md#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s). - HTTP endpoints: [Monitor for Salt Bucket Rotations for Your Stored Raw UID2s (v2)](integration-advertiser-dataprovider-endpoints.md#monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s-v2). diff --git a/docs/guides/integration-snowflake-before-july-2025.md b/docs/guides/integration-snowflake-before-july-2025.md deleted file mode 100644 index 6a926c540..000000000 --- a/docs/guides/integration-snowflake-before-july-2025.md +++ /dev/null @@ -1,702 +0,0 @@ ---- -title: Snowflake Integration Guide (Pre-July 2025) -sidebar_label: Snowflake (Before July 2025) -pagination_label: Snowflake Integration -description: Information about integrating with UID2 through the UID2 Share in Snowflake. -hide_table_of_contents: false -sidebar_position: 04 -displayed_sidebar: docs ---- - -import Link from '@docusaurus/Link'; - -# Snowflake Integration Guide (Pre-July 2025) - -[Snowflake](https://www.snowflake.com/) is a cloud data warehousing solution, where you as a partner can store your data and integrate with the UID2 framework. Using Snowflake, UID2 enables you to securely share consumer identifier data without exposing sensitive directly identifying information (DII). Even though you have the option to query the Operator Web Services directly for the consumer identifier data, the Snowflake UID2 integration offers a more seamless experience. - -:::important -This document is for anyone using the Snowflake marketplace listing published prior to July 2025. For documentation on the newer version of identity map published in July 2025, see [Snowflake Integration Guide](integration-snowflake.md). If you're using the earlier implementation, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration information, see [Migration Guide](integration-snowflake.md#migration-guide). -::: - -## Snowflake Marketplace Listing - -The following listing for UID2 is available on the Snowflake marketplace: -- [Unified ID 2.0: Advertiser and Data Provider Identity Solution](https://app.snowflake.com/marketplace/listing/GZT0ZRYXTN8/unified-id-2-0-unified-id-2-0-advertiser-and-data-provider-identity-solution) - -:::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). -::: - -## Functionality - -The following table summarizes the functionality available with the UID2 Snowflake 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 | -| :--- | :--- | :--- | :--- | :--- | -| ✅ | ✅ | —* | — | ✅ | - -*You cannot use Snowflake to generate a UID2 token directly from DII. However, you can convert DII to a raw UID2, and then encrypt the raw UID2 into a UID2 token. - -:::note -If you're a publisher who is sharing UID2 tokens in the bidstream, see [Tokenized Sharing in the Bidstream](../sharing/sharing-tokenized-from-data-bid-stream.md). -::: - -## Changes from Previous Version - -The February 2025 update to the UID2 Snowflake Marketplace integration includes updates and enhancements. One key change is that it includes a single listing and data share that combines the capabilities of the two previous data shares, one for Advertisers and one for Data Providers. This simplifies the integration for all participants. - -:::note -These changes assume that your code integration uses the version of Snowflake functions published before February 2025: see [Snowflake Integration (Pre-Feb 2025)](integration-snowflake-before-february-2025.md). If you're using an even earlier version, that uses the `FN_T_UID2_IDENTITY_MAP_EMAIL` and `FN_T_UID2_IDENTITY_MAP_EMAIL_HASH` functions, you could follow the instructions in the [Migration Guide section in the earlier guide](integration-snowflake-before-february-2025.md#migration-guide), and then upgrade again to the current version. However, in this scenario we recommend that you follow the instructions in this guide and upgrade in one step. For details, see [Migration Guide](#migration-guide). -::: - -The following table shows details of the changes to the Snowflake functions, from the previous version. - -| Old function | New function | Fields in old function | Fields in new function | Comments | -| :-- | :-- | :-- | :-- | :-- | -| `FN_T_UID2_IDENTITY_MAP` | `FN_T_IDENTITY_MAP` | `UID2` | `UID` | For details, see [Map DII](#map-dii).| -| `FN_T_UID2_ENCRYPT` | `FN_T_ENCRYPT` | `UID2_TOKEN` | `UID_TOKEN` | For details, see [Encrypt Tokens](#encrypt-tokens).| -| `FN_T_UID2_DECRYPT` | `FN_T_DECRYPT` | `UID2_TOKEN` | `UID_TOKEN` | For details, see [Decrypt Tokens](#decrypt-tokens).| - -The following table shows details of the changes to the Snowflake views, from the previous version. - -| Old view | New view | Comments | -| :-- | :-- | :-- | -| `UID2_SALT_BUCKETS` | `SALT_BUCKETS` | For details, see [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s). | - -## Workflow Diagram - -The following diagram and table illustrate the different parts of the UID2 integration process in Snowflake, and the workflow. - -![Snowflake Integration Architecture](images/uid2-snowflake-integration-architecture-drawio.png) - -|Partner Snowflake Account|UID2 Snowflake Account|UID2 Core Opt-Out Cloud Setup| -| :--- | :--- | :--- | -|As a partner, you set up a Snowflake account to host your data and engage in UID2 integration by consuming functions and views through the UID2 Share. | UID2 integration, hosted in a Snowflake account, grants you access to authorized functions and views that draw data from private tables. You can’t access the private tables. The UID2 Share reveals only essential data needed for you to perform UID2-related tasks.
**NOTE**: We store salts and encryption keys in the private tables. No DII is stored at any point. |ETL (Extract Transform Load) jobs constantly update the UID2 Core/Optout Snowflake storage with internal data that powers the UID2 Operator Web Services. The data used by the Operator Web Services is also available through the UID2 Share. | -|When you use shared functions and views, you pay Snowflake for transactional computation costs. |These private tables, secured in the UID2 Snowflake account, automatically synchronize with the UID2 Core/Optout Snowflake storage that holds internal data used to complete UID2-related tasks. | | - -## Access the UID2 Share - -Access to the UID2 Share is available through the following listing on the [Snowflake Data Marketplace](https://www.snowflake.com/data-marketplace/): - -- [Unified ID 2.0: Advertiser and Data Provider Identity Solution](https://app.snowflake.com/marketplace/listing/GZT0ZRYXTN8/unified-id-2-0-unified-id-2-0-advertiser-and-data-provider-identity-solution) - - -:::important -To be able to request data, you must use the `ACCOUNTADMIN` role or another role with the `CREATE DATABASE` and `IMPORT SHARE` privileges in your Snowflake account. -::: - -To request access to the UID2 Share, complete the following steps: - -1. Log in to the Snowflake Data Marketplace and select the UID2 listing: - - [Unified ID 2.0: Advertiser and Data Provider Identity Solution](https://app.snowflake.com/marketplace/listing/GZT0ZRYXTN8/unified-id-2-0-unified-id-2-0-advertiser-and-data-provider-identity-solution) -2. In the **Personalized Data** section, click **Request Data**. -3. Follow the onscreen instructions to verify and provide your contact details and other required information. -4. If you are an existing client of The Trade Desk, include your partner and advertiser IDs issued by The Trade Desk in the **Message** field of the data request form. -5. Submit the form. - -After your request is received, a UID2 administrator will contact you with the appropriate access instructions. For details about managing data requests in Snowflake, see the [Snowflake documentation](https://docs.snowflake.com/en/user-guide/data-marketplace-consumer.html). - -## Shared Objects - -You can map DII to UID2s by using the following function: - -- `FN_T_IDENTITY_MAP` (for details, see [Map DII](#map-dii)) - -The following function is deprecated in favor of `FN_T_IDENTITY_MAP`. You can still use it if you are on the previous Snowflake version (see [Snowflake Integration (Pre-Feb 2025)](integration-snowflake-before-february-2025.md)), but we recommend upgrading as soon as possible: - -- `FN_T_UID2_IDENTITY_MAP` (deprecated) - -:::note -If you are using the deprecated function, and need help migrating to the newer function, see [Migration Guide](#migration-guide). -::: - -To identify the UID2s that you must regenerate, use the `SALT_BUCKETS` view from the UID2 Share. For details, see [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s). - -The following functions are also available, for UID2 sharing participants: -- `FN_T_ENCRYPT` (See [Encrypt Tokens](#encrypt-tokens)) -- `FN_T_DECRYPT` (See [Decrypt Tokens](#decrypt-tokens)) - -For details, see [Usage for UID2 Sharers](#usage-for-uid2-sharers). - -### Database and Schema Names - -The following sections include query examples for each solution, which are identical except for the database and schema name variables: - -``` -{DATABASE_NAME}.{SCHEMA_NAME} -``` - -For example: - -```sql -select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP('validate@example.com', 'email')); -``` - -All query examples use the following default values for each name variable: - -| Variable | Default Value | Comments | -|:------------------|:-------------------|:------------------------------------------------------------------------------------------------------------------------------------------| -| `{DATABASE_NAME}` | `UID2_PROD_UID_SH` | If needed, you can change the default database name when creating a new database after you are granted access to the selected UID2 Share. | -| `{SCHEMA_NAME}` | `UID` | This is an immutable name. | - -### Map DII - -To map all types of DII, use the `FN_T_IDENTITY_MAP` function. - -If the DII is an email address, the service normalizes the data using the UID2 [Email Address Normalization](../getting-started/gs-normalization-encoding.md#email-address-normalization) rules. - -If the DII is a phone number, you must normalize it before sending it to the service, using the UID2 [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization) rules. - -| Argument | Data Type | Description | -|:-------------|:-------------|:------------------------------------------------------------------------------------------| -| `INPUT` | varchar(256) | The DII to map to the UID2 and salt bucket ID. | -| `INPUT_TYPE` | varchar(256) | The type of DII to map. Allowed values: `email`, `email_hash`, `phone`, and `phone_hash`. | - -A successful query returns the following information for the specified DII. - -| Column Name | Data Type | Description | -|:------------|:----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `UID` | TEXT | The value is one of the following: | -| `BUCKET_ID` | TEXT | The value is one of the following: | -| `UNMAPPED` | TEXT | The value is one of the following: | - -#### Values for the UNMAPPED Column - -The following table shows possible values for the `UNMAPPED` column. - -| 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`. | - -#### Examples - -Mapping request examples in this section: - -- [Single Unhashed Email](#mapping-request-example---single-unhashed-email) -- [Multiple Unhashed Emails](#mapping-request-example---multiple-unhashed-emails) -- [Single Unhashed Phone Number](#mapping-request-example---single-unhashed-phone-number) -- [Multiple Unhashed Phone Numbers](#mapping-request-example---multiple-unhashed-phone-numbers) -- [Single Hashed Email](#mapping-request-example---single-hashed-email) -- [Multiple Hashed Emails](#mapping-request-example---multiple-hashed-emails) -- [Single Hashed Phone Number](#mapping-request-example---single-hashed-phone-number) -- [Multiple Hashed Phone Numbers](#mapping-request-example---multiple-hashed-phone-numbers) - -:::note -The input and output data in these examples is fictitious, for illustrative purposes only. The values provided are not real values. -::: - -#### Mapping Request Example - Single Unhashed Email - -The following query illustrates how to map a single email address, using the [default database and schema names](#database-and-schema-names). - -```sql -select UID, BUCKET_ID, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP('validate@example.com', 'email')); -``` - -Query results for a single email: - -``` -+----------------------------------------------+------------+----------+ -| UID | BUCKET_ID | UNMAPPED | -+----------------------------------------------+------------+----------+ -| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | -+----------------------------------------------+------------+----------+ -``` - -#### Mapping Request Example - Multiple Unhashed Emails - -The following query illustrates how to map multiple email addresses, using the [default database and schema names](#database-and-schema-names). - -```sql -select a.ID, a.EMAIL, m.UID, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN( - select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(EMAIL, 'email') t) m - on a.ID=m.ID; -``` - -Query results for multiple emails: - -The following table identifies each item in the response, including `NULL` values for `NULL` or improperly formatted emails. - -```sh -+----+----------------------+----------------------------------------------+------------+--------------------+ -| ID | EMAIL | UID | BUCKET_ID | UNMAPPED | -+----+----------------------+----------------------------------------------+------------+--------------------+ -| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | -| 2 | test@uidapi.com | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL | -| 3 | invalid-email | NULL | NULL | INVALID IDENTIFIER | -| 4 | NULL | NULL | NULL | INVALID IDENTIFIER | -+----+----------------------+----------------------------------------------+------------+--------------------+ -``` - -#### Mapping Request Example - Single Unhashed Phone Number - -The following query illustrates how to map a phone number, using the [default database and schema names](#database-and-schema-names). - -You must normalize phone numbers using the UID2 [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization) rules. - -```sql -select UID, BUCKET_ID, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP('+12345678901', 'phone')); -``` - -Query results for a single phone number: - -``` -+----------------------------------------------+------------+----------+ -| UID | BUCKET_ID | UNMAPPED | -+----------------------------------------------+------------+----------+ -| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | -+----------------------------------------------+------------+----------+ -``` - -#### Mapping Request Example - Multiple Unhashed Phone Numbers - -The following query illustrates how to map multiple phone numbers, using the [default database and schema names](#database-and-schema-names). - -You must normalize phone numbers using the UID2 [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization) rules. - -```sql -select a.ID, a.PHONE, m.UID, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN( - select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(PHONE, 'phone') t) m - on a.ID=m.ID; -``` - -Query results for multiple phone numbers: - -The following table identifies each item in the response, including `NULL` values for `NULL` or invalid phone numbers. - -``` -+----+--------------+----------------------------------------------+------------+--------------------+ -| ID | PHONE | UID | BUCKET_ID | UNMAPPED | -+----+--------------+----------------------------------------------+------------+--------------------+ -| 1 | +12345678901 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | -| 2 | +61491570006 | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL | -| 3 | 1234 | NULL | NULL | INVALID IDENTIFIER | -| 4 | NULL | NULL | NULL | INVALID IDENTIFIER | -+----+--------------+----------------------------------------------+------------+--------------------+ -``` - -#### Mapping Request Example - Single Hashed Email - -The following query illustrates how to map a single email address hash, using the [default database and schema names](#database-and-schema-names). - -```sql -select UID, BUCKET_ID, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('validate@example.com', 256)), 'email_hash')); -``` - -Query results for a single hashed email: - -``` -+----------------------------------------------+------------+----------+ -| UID | BUCKET_ID | UNMAPPED | -+----------------------------------------------+------------+----------+ -| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | -+----------------------------------------------+------------+----------+ -``` - -#### Mapping Request Example - Multiple Hashed Emails - -The following query illustrates how to map multiple email address hashes, using the [default database and schema names](#database-and-schema-names). - -```sql -select a.ID, a.EMAIL_HASH, m.UID, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN( - select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(EMAIL_HASH, 'email_hash') t) m - on a.ID=m.ID; -``` - -Query results for multiple hashed emails: - -The following table identifies each item in the response, including `NULL` values for `NULL` hashes. - -``` -+----+----------------------------------------------+----------------------------------------------+------------+--------------------+ -| ID | EMAIL_HASH | UID | BUCKET_ID | UNMAPPED | -+----+----------------------------------------------+----------------------------------------------+------------+--------------------+ -| 1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | -| 2 | NULL | NULL | NULL | INVALID IDENTIFIER | -| 3 | /XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g= | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL | -+----+----------------------------------------------+----------------------------------------------+------------+--------------------+ -``` - -#### Mapping Request Example - Single Hashed Phone Number - -The following query illustrates how to map a single phone number hash, using the [default database and schema names](#database-and-schema-names). - -```sql -select UID, BUCKET_ID, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('+12345678901', 256)), 'phone_hash')); -``` - -Query results for a single hashed phone number: - -``` -+----------------------------------------------+------------+----------+ -| UID | BUCKET_ID | UNMAPPED | -+----------------------------------------------+------------+----------+ -| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | -+----------------------------------------------+------------+----------+ -``` - -#### Mapping Request Example - Multiple Hashed Phone Numbers - -The following query illustrates how to map multiple phone number hashes, using the [default database and schema names](#database-and-schema-names). - -```sql -select a.ID, a.PHONE_HASH, m.UID, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN( - select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(PHONE_HASH, 'phone_hash') t) m - on a.ID=m.ID; -``` - -Query results for multiple hashed phone numbers: - -The following table identifies each item in the response, including `NULL` values for `NULL` hashes. - -``` -+----+----------------------------------------------+----------------------------------------------+------------+--------------------+ -| ID | PHONE_HASH | UID | BUCKET_ID | UNMAPPED | -+----+----------------------------------------------+----------------------------------------------+------------+--------------------+ -| 1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | -| 2 | NULL | NULL | NULL | INVALID IDENTIFIER | -| 3 | /XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g= | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL | -+----+----------------------------------------------+----------------------------------------------+------------+--------------------+ -``` - -### Monitor for Salt Bucket Rotation and Regenerate Raw UID2s - -The `SALT_BUCKETS` view query returns the date and time when the salt buckets for the raw UID2s were last updated. A salt value is used when generating UID2s. When the salt in the bucket is updated, the previously generated UID2 becomes outdated and doesn’t match the UID2 generated by other parties for the same user. - -To determine which UID2s need regeneration, compare the timestamps of when they were generated to the most recent timestamp of the salt bucket update. - -| Column Name | Data Type | Description | -|:-----------------------|:--------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `BUCKET_ID` | TEXT | The ID of the salt bucket. This ID parallels the `BUCKET_ID` returned by the identity map function. Use the `BUCKET_ID` as the key to do a join query between the function call results and results from this view call. | -| `LAST_SALT_UPDATE_UTC` | TIMESTAMP_NTZ | The last time the salt in the bucket was updated. This value is expressed in UTC. | - -The following example shows an input table and the query used to find the UID2s in the table that must be regenerated because the salt bucket was updated. - -#### Targeted Input Table - -In this example scenario, the advertiser/data provider has stored the UID2s in a table named `AUDIENCE_WITH_UID2`. The last column, `LAST_UID2_UPDATE_UTC`, is used to record the time at which a UID2 was generated. If no UID2 has been generated, the value is `NULL`, as shown in the third example. The advertiser/data provider can use this timestamp value to determine which UID2s need to be regenerated. - -```sql -select * from AUDIENCE_WITH_UID2; -``` -``` -+----+----------------------+----------------------------------------------+------------+-------------------------+ -| ID | EMAIL | UID2 | BUCKET_ID | LAST_UID2_UPDATE_UTC | -+----+----------------------+----------------------------------------------+------------+-------------------------+ -| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | 2025-02-01 00:00:00.000 | -| 2 | test1@uidapi.com | Q4A5ZBuBCYfuV3Wd8Fdsx2+i33v7jyFcQbcMG/LH4eM= | ad1ANEmVZ | 2025-02-03 00:00:00.000 | -| 3 | test2@uidapi.com | NULL | NULL | NULL | -+----+----------------------+----------------------------------------------+------------+-------------------------+ -``` - -To find missing or outdated UID2s, use the following query example, which uses the [default database and schema names](#database-and-schema-names). - -```sql -select a.*, b.LAST_SALT_UPDATE_UTC - from AUDIENCE_WITH_UID2 a LEFT OUTER JOIN UID2_PROD_UID_SH.UID.SALT_BUCKETS b - on a.BUCKET_ID=b.BUCKET_ID - where a.LAST_UID2_UPDATE_UTC < b.LAST_SALT_UPDATE_UTC or a.UID2 IS NULL; -``` - -Query results: - -The following table identifies each item in the response. The result includes an email, `UID2`, `BUCKET_ID`, `LAST_UID2_UPDATE_UTC`, and `LAST_SALT_UPDATE_UTC` as shown in the ID 1 example in the table. No information is returned for ID 2 because the corresponding UID2 was generated after the last bucket update. For ID 3, `NULL` values are returned due to a missing UID2. - -``` -+----+----------------------+----------------------------------------------+------------+-------------------------+-------------------------+ -| ID | EMAIL | UID2 | BUCKET_ID | LAST_UID2_UPDATE_UTC | LAST_SALT_UPDATE_UTC | -+----+----------------------+----------------------------------------------+------------+-------------------------+-------------------------+ -| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | 2025-02-01 00:00:00.000 | 2025-02-02 00:00:00.000 | -| 3 | test2@uidapi.com | NULL | NULL | NULL | NULL | -+----+----------------------+----------------------------------------------+------------+-------------------------+-------------------------+ -``` - -## Usage for UID2 Sharers - -A UID2 sharing participant is a company that takes part in sharing, either as a sender or a receiver, to share UID2s with another participant. - -Advertisers and data providers can share UID2s with other authorized UID2 sharing participants via Snowflake (tokenized sharing). They can encrypt [raw UID2s](../ref-info/glossary-uid#gl-raw-uid2) into UID2 tokens and then send them to another participant for sharing in pixels (see [Tokenized Sharing in Pixels](../sharing/sharing-tokenized-from-data-pixel.md)). If you are not sending data in pixels within Snowflake, you can take part in UID2 sharing as long as you follow the requirements laid out in [Security Requirements for UID2 Sharing](../sharing/sharing-security.md). - -:::caution -The UID2 token generated during this process is for sharing only—you cannot use it in the bidstream. There is a different workflow for generating tokens for the bidstream: see [Tokenized Sharing in the Bidstream](../sharing/sharing-tokenized-from-data-bid-stream.md). -::: - -If you are not sending data in pixels or in the bidstream within Snowflake, you can also take part in raw UID2 sharing as long as you follow the requirements laid out in [Security Requirements for UID2 Sharing](../sharing/sharing-security.md). - -The following activities support tokenized sharing: - -- [Encrypt Tokens](#encrypt-tokens) -- [Decrypt Tokens](#decrypt-tokens) - -### Encrypt Tokens - -To encrypt raw UID2s to UID2 tokens, use the `FN_T_ENCRYPT` function. - -|Argument|Data Type|Description| -| :--- | :--- | :--- | -| `RAW_UID2` | varchar(128) | The raw UID2 to encrypt to a UID2 token. | - -A successful query returns the following information for the specified raw UID2. - -|Column Name|Data Type|Description| -| :--- | :--- | :--- | -| `UID_TOKEN` | TEXT | The value is one of the following: | -| `ENCRYPTION_STATUS` | TEXT | The value is one of the following: | - -#### Values for the ENCRYPTION_STATUS Column - -The following table shows possible values for the `ENCRYPTION_STATUS` column. - -| Value | Meaning | -| :-- | :-- | -| `NULL` | The raw UID2 was successfully encrypted. | -| `MISSING_OR_INVALID_RAW_UID2` | The raw UID2 is `NULL`. | -| `INVALID_RAW_UID2` | The raw UID2 is invalid. | -| `MISMATCHING_IDENTITY_SCOPE` | The raw UID2 belongs to an incorrect identity scope; for example, EUID is passed in where UID2 is expected. | -| `NOT_AUTHORIZED_FOR_MASTER_KEY` | The caller does not have access to the required encryption keys. Contact the UID2 administrator. | -| `NOT_AUTHORIZED_FOR_SITE_KEY` | The caller does not have access to the required encryption keys. Contact the UID2 administrator. | - -#### Encrypt Token Request Example - Single Raw UID2 - -The following query illustrates how to encrypt a single raw UID2 to a UID2 token, using the [default database and schema names](#database-and-schema-names). - -```sql -select UID_TOKEN, ENCRYPTION_STATUS from table(UID2_PROD_UID_SH.UID.FN_T_ENCRYPT('2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU=')); -``` - -Query results for a single raw UID2: - -``` -+------------------------+-------------------+ -| UID_TOKEN | ENCRYPTION_STATUS | -+--------------------------------------------+ -| A41234 | NULL | -+--------------------------------------------+ -``` - -#### Encrypt Token Request Example - Multiple Raw UID2s - -The following query illustrates how to encrypt multiple raw UID2s, using the [default database and schema names](#database-and-schema-names). - -```sql -select a.RAW_UID2, t.UID_TOKEN, t.ENCRYPTION_STATUS from AUDIENCE_WITH_UID2 a, lateral UID2_PROD_UID_SH.UID.FN_T_ENCRYPT(a.RAW_UID2) t; -``` - -Query results for multiple raw UID2s: - -The following table identifies each item in the response, including `NULL` values for `NULL` raw UID2s. - -``` -+----+----------------------------------------------+-----------------------+-----------------------------+ -| ID | RAW_UID2 | UID_TOKEN | ENCRYPTION_STATUS | -+----+----------------------------------------------+-----------------------+-----------------------------+ -| 1 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | A41234 | NULL | -| 2 | NULL | NULL | MISSING_OR_INVALID_RAW_UID2 | -| 3 | BXJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g5 | B45678 | NULL | -+----+----------------------------------------------+-----------------------+-----------------------------+ -``` - -### Decrypt Tokens - -To decrypt UID2 tokens to raw UID2s, use the `FN_T_DECRYPT` function. - -| Argument | Data Type | Description | -|:------------|:-------------|:-----------------------------------------| -| `UID_TOKEN` | varchar(512) | The UID2 token to decrypt to a raw UID2. | - -A successful query returns the following information for the specified UID2 token. - -| Column Name |Data Type|Description| -|:--------------------| :--- | :--- | -| `UID` | TEXT | The value is one of the following:
  • Decryption successful: The raw UID2 corresponding to the UID2 token.
  • Decryption not successful: `NULL`.
| -| `SITE_ID` | INT | The value is one of the following:
  • Decryption successful: The identifier of the UID2 participant that encrypted the token.
  • Decryption not successful: `NULL`.
| -| `DECRYPTION_STATUS` | TEXT | The value is one of the following:
  • Decryption successful: `NULL`.
  • Decryption not successful: The reason why the UID2 token was not decrypted; for example, `EXPIRED_TOKEN`.
    For details, see [Values for the DECRYPTION_STATUS Column](#values-for-the-decryption_status-column).
| - -:::note -In most circumstances where UID2 token cannot be successfully decrypted, the function will not return any rows at all. -::: - -#### Values for the DECRYPTION_STATUS Column - -Possible values for `DECRYPTION_STATUS` are: - -| Value | Meaning | -| :-- | :-- | -| `NULL` | The UID2 token was successfully decrypted. | -| `EXPIRED_TOKEN` | The UID2 token is beyond its designated lifetime—the token has expired. | - -#### Decrypt Token Request Example—Single UID2 Token - -The following query illustrates how to decrypt a single UID2 token to a raw UID2, using the [default database and schema names](#database-and-schema-names). - -```sql -select UID, SITE_ID, DECRYPTION_STATUS from table(UID2_PROD_UID_SH.UID.FN_T_DECRYPT('A41234')); -``` - -Query results for a single UID2 token: - -``` -+----------------------------------------------+-------------------+ -| UID | DECRYPTION_STATUS | -+----------------------------------------------+-------------------+ -| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | NULL | -+----------------------------------------------+-------------------+ -``` - -#### Decrypt Token Request Example—Multiple UID2 Tokens - -The following query illustrates how to decrypt multiple UID2 tokens, using the [default database and schema names](#database-and-schema-names). - -```sql -select a.ID, b.UID, b.SITE_ID, CASE WHEN b.UID IS NULL THEN 'DECRYPT_FAILED' ELSE b.DECRYPTION_STATUS END as DECRYPTION_STATUS - from TEST_IMPRESSION_DATA a LEFT OUTER JOIN ( - select ID, t.* from TEST_IMPRESSION_DATA, lateral UID2_PROD_UID_SH.UID.FN_T_DECRYPT(UID_TOKEN) t) b - on a.ID=b.ID; -``` - -Query results for multiple UID2 tokens: - -The following table identifies each item in the response, including `NULL` values for `NULL` and expired UID2 tokens. - -``` -+----+----------------------------------------------+----------+-------------------+ -| ID | UID | SITE_ID | DECRYPTION_STATUS | -+----+----------------------------------------------+----------+-------------------+ -| 1 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | 12345 | NULL | -| 2 | NULL | NULL | DECRYPT_FAILED | -| 3 | BXJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g5 | 23456 | NULL | -| 4 | NULL | NULL | EXPIRED_TOKEN | -| 5 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | 12345 | NULL | -+----+----------------------------------------------+----------+-------------------+ -``` - -### UID2 Sharing Example - -The following instructions provide an example of how sharing works for a sender and a receiver both using Snowflake. In this example scenario an advertiser (the sender) has an audience table with raw UID2s -(`AUDIENCE_WITH_UID2S`) and wants to make data in the table available to a data provider (the receiver) using the [Snowflake Secure Data Sharing](https://docs.snowflake.com/en/user-guide/data-sharing-intro) feature. - -#### Sender Instructions - - 1. Create a new table named `AUDIENCE_WITH_UID2_TOKENS`. - 2. Encrypt the raw UID2s in the `AUDIENCE_WITH_UID2S` table and store the result in the `AUDIENCE_WITH_UID2_TOKENS` table. For example, the following query could help achieve this task: - ```sql - insert into AUDIENCE_WITH_UID2_TOKENS select a.ID, t.UID_TOKEN from AUDIENCE_WITH_UID2S a, lateral UID2_PROD_UID_SH.UID.FN_T_ENCRYPT(a.RAW_UID2) t; - ``` - 3. Create a secure share and grant it access to the `AUDIENCE_WITH_UID2_TOKENS` table. - 4. Grant the receiver access to the secure share. - -:::warning -To help prevent UID2 tokens from expiring during sharing, send the newly encrypted UID2 tokens to the receiver as soon as possible. -::: - -#### Receiver Instructions - - 1. Create a database from the secure share that the sender provided access to. - 2. Create a new table named `RECEIVED_AUDIENCE_WITH_UID2`. - 3. Decrypt tokens from the shared `AUDIENCE_WITH_UID2_TOKENS` table and store the result in the `RECEIVED_AUDIENCE_WITH_UID2` table. For example, the following query could be used to achieve this: - ```sql - insert into RECEIVED_AUDIENCE_WITH_UID2 - select a.ID, b.UID, CASE WHEN b.UID IS NULL THEN 'DECRYPT_FAILED' ELSE b.DECRYPTION_STATUS END as DECRYPTION_STATUS - from AUDIENCE_WITH_UID2_TOKENS a LEFT OUTER JOIN ( - select ID, t.* from AUDIENCE_WITH_UID2_TOKENS, lateral UID2_PROD_UID_SH.UID.FN_T_DECRYPT(UID_TOKEN) t) b - on a.ID=b.ID; - ``` - -:::warning -To help prevent UID2 tokens from expiring, decrypt the UID2 tokens as soon as they become available from the sender. -::: - -## Migration Guide - -This section includes the following information to help you upgrade to the new UID2 Snowflake Marketplace functionality: - -- [Accessing the New Data Share](#accessing-the-new-data-share) -- [Changing Existing Code](#changing-existing-code) - -### Accessing the New Data Share - -To access the new data share, follow the instructions in [Access the UID2 Share](#access-the-uid2-share). - -### Changing Existing Code - -For a summary of changes, see [Changes from Previous Version](#changes-from-previous-version). The code snippets in this section are before/after examples of how the earlier functions might be implemented, and how you could update to use the new function. - -#### Example for Mapping Unhashed Emails - -Before: - -```sql -select UID2, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_IDENTITY_MAP(EMAIL, 'email')); -``` - -After: - -```sql -select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP(EMAIL, 'email')); -``` - -#### Example for Mapping Unhashed Phone Numbers - -Before: - -```sql -select UID2, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_IDENTITY_MAP(PHONE_NUMBER, 'phone')); -``` - -After: - -```sql -select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP(PHONE_NUMBER, 'phone')); -``` - -#### Example for Monitoring Salt Bucket Rotation and Regenerating Raw UID2s - -The following queries use the same example table, `AUDIENCE_WITH_UID2`, that we used in [Targeted Input Table](#targeted-input-table). - -Before: - -```sql -select a.*, b.LAST_SALT_UPDATE_UTC - from AUDIENCE_WITH_UID2 a LEFT OUTER JOIN {DATABASE_NAME}.{SCHEMA_NAME}.UID2_SALT_BUCKETS b - on a.BUCKET_ID=b.BUCKET_ID - where a.LAST_UID2_UPDATE_UTC < b.LAST_SALT_UPDATE_UTC or a.UID2 IS NULL; -``` - -After: - -```sql -select a.*, b.LAST_SALT_UPDATE_UTC - from AUDIENCE_WITH_UID2 a LEFT OUTER JOIN {DATABASE_NAME}.{SCHEMA_NAME}.SALT_BUCKETS b - on a.BUCKET_ID=b.BUCKET_ID - where a.LAST_UID2_UPDATE_UTC < b.LAST_SALT_UPDATE_UTC or a.UID2 IS NULL; -``` - -#### Example for Token Encryption - -Before: - -```sql -select UID2_TOKEN, ENCRYPTION_STATUS from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_ENCRYPT('2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU=')); -``` - -After: - -```sql -select UID_TOKEN, ENCRYPTION_STATUS from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_ENCRYPT('2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU=')); -``` - -#### Example for Token Decryption - -Before: - -```sql -select UID2, SITE_ID, DECRYPTION_STATUS from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_DECRYPT('A41234')); -``` - -After: -```sql -select UID, SITE_ID, DECRYPTION_STATUS from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_DECRYPT('A41234')); -``` diff --git a/docs/guides/integration-snowflake-before-february-2025.md b/docs/guides/integration-snowflake-previous.md similarity index 98% rename from docs/guides/integration-snowflake-before-february-2025.md rename to docs/guides/integration-snowflake-previous.md index 54e54a6f1..e6398681d 100644 --- a/docs/guides/integration-snowflake-before-february-2025.md +++ b/docs/guides/integration-snowflake-previous.md @@ -1,6 +1,6 @@ --- -title: Snowflake Integration (Pre-Feb 2025) -sidebar_label: Snowflake (Before Feb 2025) +title: Snowflake Integration (Earlier Listings) +sidebar_label: Snowflake (earlier version) pagination_label: Snowflake Integration description: Information about integrating with UID2 through the UID2 Share in Snowflake (earlier listings, separate for Advertiser and Data Provider). hide_table_of_contents: false @@ -10,12 +10,12 @@ displayed_sidebar: docs import Link from '@docusaurus/Link'; -# Snowflake Integration Guide (Pre-Feb 2025) +# Snowflake Integration Guide (Version Prior to February 2025) [Snowflake](https://www.snowflake.com/) is a cloud data warehousing solution, where you as a partner can store your data and integrate with the UID2 framework. Using Snowflake, UID2 enables you to securely share consumer identifier data without exposing sensitive directly identifying information (DII). Even though you have the option to query the Operator Web Services directly for the consumer identifier data, the Snowflake UID2 integration offers a more seamless experience. :::important -This document is for anyone using the separate advertiser and data provider Snowflake marketplace listings published prior to February 2025. For documentation on the latest version, see [Snowflake Integration Guide](integration-snowflake.md). If you're using any earlier implementation, we recommend that you migrate to the latest version to take advantage of the updates and enhancements. For migration information, see [Migration Guide](integration-snowflake-before-july-2025.md#migration-guide). +This document is for anyone using the separate advertiser and data provider Snowflake marketplace listings published prior to February 2025. For documentation on the newer, combined listing published in February 2025, see [Snowflake Integration Guide](integration-snowflake.md). If you're using the earlier implementation, we recommend that you migrate to the newer version to take advantage of the updates and enhancements. For migration information, see [Migration Guide](integration-snowflake.md#migration-guide). ::: The Snowflake marketplace listings for this implementation were separate for advertisers and for data providers. Those listings were removed following the publication of the updated version in February 2025. @@ -509,7 +509,7 @@ After: FN_T_UID2_IDENTITY_MAP(EMAIL, 'email') ``` -#### Example for mapping hashed emails +#### Example for mapping unhashed emails Before: diff --git a/docs/guides/integration-snowflake.md b/docs/guides/integration-snowflake.md index 43a1795ef..d80b6403a 100644 --- a/docs/guides/integration-snowflake.md +++ b/docs/guides/integration-snowflake.md @@ -15,7 +15,7 @@ import Link from '@docusaurus/Link'; [Snowflake](https://www.snowflake.com/) is a cloud data warehousing solution, where you as a partner can store your data and integrate with the UID2 framework. Using Snowflake, UID2 enables you to securely share consumer identifier data without exposing sensitive directly identifying information (DII). Even though you have the option to query the Operator Web Services directly for the consumer identifier data, the Snowflake UID2 integration offers a more seamless experience. :::important -This document is for those using the combined advertiser and data provider Snowflake marketplace listing published in February 2025. If you're using one of the earlier listings, which were separate for advertiser and data provider (that is, you subscribed prior to February 2025), see [Snowflake Integration (Pre-Feb 2025)](integration-snowflake-before-february-2025.md). If you're using the earlier implementation, we recommend that you migrate to the newer version to take advantage of the updates and enhancements: for details, see [Changes from Previous Version](#changes-from-previous-version). For migration information, see [Migration Guide](#migration-guide). +This document is for those using the combined advertiser and data provider Snowflake marketplace listing published in February 2025. If you're using one of the earlier listings, which were separate for advertiser and data provider (that is, you subscribed prior to February 2025), see [Snowflake Integration Guide (Version Prior to February 2025)](integration-snowflake-previous.md). If you're using the earlier implementation, we recommend that you migrate to the newer version to take advantage of the updates and enhancements: for details, see [Changes from Previous Version](#changes-from-previous-version). For migration information, see [Migration Guide](#migration-guide). ::: ## Snowflake Marketplace Listing @@ -43,25 +43,25 @@ If you're a publisher who is sharing UID2 tokens in the salt buckets for rotation. -- **Previous UID2 Access**: You have access to previous raw UID2s for 90 days after rotation for campaign measurement. +| Old view | New view | Comments | +| :-- | :-- | :-- | +| `UID2_SALT_BUCKETS` | `SALT_BUCKETS` | For details, see [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s). | ## Workflow Diagram @@ -71,7 +71,7 @@ The following diagram and table illustrate the different parts of the UID2 integ |Partner Snowflake Account|UID2 Snowflake Account|UID2 Core Opt-Out Cloud Setup| | :--- | :--- | :--- | -|As a partner, you set up a Snowflake account to host your data and engage in UID2 integration by consuming functions and views through the UID2 Share. | UID2 integration, hosted in a Snowflake account, grants you access to authorized functions and views that draw data from private tables. You can't access the private tables. The UID2 Share reveals only essential data needed for you to perform UID2-related tasks.
**NOTE**: We store salts and encryption keys in the private tables. No DII is stored at any point. |ETL (Extract Transform Load) jobs constantly update the UID2 Core/Optout Snowflake storage with internal data that powers the UID2 Operator Web Services. The data used by the Operator Web Services is also available through the UID2 Share. | +|As a partner, you set up a Snowflake account to host your data and engage in UID2 integration by consuming functions and views through the UID2 Share. | UID2 integration, hosted in a Snowflake account, grants you access to authorized functions and views that draw data from private tables. You can’t access the private tables. The UID2 Share reveals only essential data needed for you to perform UID2-related tasks.
**NOTE**: We store salts and encryption keys in the private tables. No DII is stored at any point. |ETL (Extract Transform Load) jobs constantly update the UID2 Core/Optout Snowflake storage with internal data that powers the UID2 Operator Web Services. The data used by the Operator Web Services is also available through the UID2 Share. | |When you use shared functions and views, you pay Snowflake for transactional computation costs. |These private tables, secured in the UID2 Snowflake account, automatically synchronize with the UID2 Core/Optout Snowflake storage that holds internal data used to complete UID2-related tasks. | | ## Access the UID2 Share @@ -100,17 +100,17 @@ After your request is received, a UID2 administrator will contact you with the a You can map DII to UID2s by using the following function: -- `FN_T_IDENTITY_MAP_V3` (for details, see [Map DII](#map-dii)) +- `FN_T_IDENTITY_MAP` (for details, see [Map DII](#map-dii)) -The following function is deprecated in favor of `FN_T_IDENTITY_MAP_V3`. You can still use it if you are on the previous Snowflake version (see [Snowflake Integration Guide (Pre-July 2025)](integration-snowflake-before-july-2025.md)), but we recommend upgrading as soon as possible: +The following function is deprecated in favor of `FN_T_IDENTITY_MAP`. You can still use it if you are on the previous Snowflake version (see [Snowflake Integration Guide (Version Prior to February 2025)](integration-snowflake-previous.md)), but we recommend upgrading as soon as possible: -- `FN_T_IDENTITY_MAP` (deprecated) +- `FN_T_UID2_IDENTITY_MAP` (deprecated) :::note If you are using the deprecated function, and need help migrating to the newer function, see [Migration Guide](#migration-guide). ::: -To identify the UID2s that you must regenerate, monitor the `REFRESH_FROM` timestamps returned by the `FN_T_IDENTITY_MAP_V3` function. For details, see [Monitor Raw UID2 Refresh and Regenerate Raw UID2s](#monitor-raw-uid2-refresh-and-regenerate-raw-uid2s). +To identify the UID2s that you must regenerate, use the `SALT_BUCKETS` view from the UID2 Share. For details, see [Monitor for Salt Bucket Rotation and Regenerate Raw UID2s](#monitor-for-salt-bucket-rotation-and-regenerate-raw-uid2s). The following functions are also available, for UID2 sharing participants: - `FN_T_ENCRYPT` (See [Encrypt Tokens](#encrypt-tokens)) @@ -129,7 +129,7 @@ The following sections include query examples for each solution, which are ident For example: ```sql -select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP_V3('validate@example.com', 'email')); +select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP('validate@example.com', 'email')); ``` All query examples use the following default values for each name variable: @@ -141,25 +141,24 @@ All query examples use the following default values for each name variable: ### Map DII -To map all types of DII, use the `FN_T_IDENTITY_MAP_V3` function. +To map all types of DII, use the `FN_T_IDENTITY_MAP` function. If the DII is an email address, the service normalizes the data using the UID2 [Email Address Normalization](../getting-started/gs-normalization-encoding.md#email-address-normalization) rules. If the DII is a phone number, you must normalize it before sending it to the service, using the UID2 [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization) rules. -| Argument | Data Type | Description | -|:-------------|:-------------|:--------------------------------------------------------------------------------------------| -| `INPUT` | varchar(256) | The DII to map to the UID2, refresh timestamp and previous UID2 for 90 days after rotation. | -| `INPUT_TYPE` | varchar(256) | The type of DII to map. Allowed values: `email`, `email_hash`, `phone`, and `phone_hash`. | +| Argument | Data Type | Description | +|:-------------|:-------------|:------------------------------------------------------------------------------------------| +| `INPUT` | varchar(256) | The DII to map to the UID2 and salt bucket ID. | +| `INPUT_TYPE` | varchar(256) | The type of DII to map. Allowed values: `email`, `email_hash`, `phone`, and `phone_hash`. | A successful query returns the following information for the specified DII. -| Column Name | Data Type | Description | -|:---------------|:----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `UID` | TEXT | The value is one of the following:
  • DII was successfully mapped: The UID2 associated with the DII.
  • DII was not successfully mapped: `NULL`.
| -| `PREV_UID` | TEXT | The value is one of the following:
  • DII was successfully mapped and a previous UID2 exists: The previous UID2 for this DII. Previous UID2s are available for 90 days after rotation.
  • No previous UID2 exists or DII was not successfully mapped: `NULL`.
| -| `REFRESH_FROM` | TIMESTAMP | The value is one of the following:
  • DII was successfully mapped: The timestamp (in epoch seconds) indicating when this UID2 should be refreshed.
  • DII was not successfully mapped: `NULL`.
| -| `UNMAPPED` | TEXT | The value is one of the following:
  • DII was successfully mapped: `NULL`.
  • DII was not successfully mapped: 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).
| +| Column Name | Data Type | Description | +|:------------|:----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `UID` | TEXT | The value is one of the following:
  • DII was successfully mapped: The UID2 associated with the DII.
  • DII was not successfully mapped: `NULL`.
| +| `BUCKET_ID` | TEXT | The value is one of the following:
  • DII was successfully mapped: The ID of the salt bucket used to generate the UID2. This ID maps to the bucket ID in the `SALT_BUCKETS` view.
  • DII was not successfully mapped: `NULL`.
| +| `UNMAPPED` | TEXT | The value is one of the following:
  • DII was successfully mapped: `NULL`.
  • DII was not successfully mapped: 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 @@ -194,17 +193,17 @@ The input and output data in these examples is fictitious, for illustrative purp The following query illustrates how to map a single email address, using the [default database and schema names](#database-and-schema-names). ```sql -select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3('validate@example.com', 'email')); +select UID, BUCKET_ID, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP('validate@example.com', 'email')); ``` Query results for a single email: ``` -+----------------------------------------------+--------------------------------------------------+--------------+----------+ -| UID | PREV_UID | REFRESH_FROM | UNMAPPED | -+----------------------------------------------+--------------------------------------------------+--------------+----------+ -| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL | -+----------------------------------------------+--------------------------------------------------+--------------+----------+ ++----------------------------------------------+------------+----------+ +| UID | BUCKET_ID | UNMAPPED | ++----------------------------------------------+------------+----------+ +| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | ++----------------------------------------------+------------+----------+ ``` #### Mapping Request Example - Multiple Unhashed Emails @@ -212,8 +211,8 @@ Query results for a single email: The following query illustrates how to map multiple email addresses, using the [default database and schema names](#database-and-schema-names). ```sql -select a.ID, a.EMAIL, m.UID, m.PREV_UID, m.REFRESH_FROM, m.UNMAPPED from AUDIENCE a LEFT JOIN( - select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(EMAIL, 'email') t) m +select a.ID, a.EMAIL, m.UID, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN( + select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(EMAIL, 'email') t) m on a.ID=m.ID; ``` @@ -221,16 +220,15 @@ Query results for multiple emails: The following table identifies each item in the response, including `NULL` values for `NULL` or improperly formatted emails. -``` -+----+----------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ -| ID | EMAIL | UID | PREV_UID | REFRESH_FROM | UNMAPPED | -+----+----------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ -| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL | -| 2 | test@uidapi.com | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | NULL | 1735689600 | NULL | -| 3 | optout@example.com | NULL | NULL | NULL | OPTOUT | -| 4 | invalid-email | NULL | NULL | NULL | INVALID IDENTIFIER | -| 5 | NULL | NULL | NULL | NULL | INVALID IDENTIFIER | -+----+----------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ +```sh ++----+----------------------+----------------------------------------------+------------+--------------------+ +| ID | EMAIL | UID | BUCKET_ID | UNMAPPED | ++----+----------------------+----------------------------------------------+------------+--------------------+ +| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | +| 2 | test@uidapi.com | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL | +| 3 | invalid-email | NULL | NULL | INVALID IDENTIFIER | +| 4 | NULL | NULL | NULL | INVALID IDENTIFIER | ++----+----------------------+----------------------------------------------+------------+--------------------+ ``` #### Mapping Request Example - Single Unhashed Phone Number @@ -240,17 +238,17 @@ The following query illustrates how to map a phone number, using the [default da You must normalize phone numbers using the UID2 [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization) rules. ```sql -select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3('+12345678901', 'phone')); +select UID, BUCKET_ID, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP('+12345678901', 'phone')); ``` Query results for a single phone number: ``` -+----------------------------------------------+----------+--------------+----------+ -| UID | PREV_UID | REFRESH_FROM | UNMAPPED | -+----------------------------------------------+----------+--------------+----------+ -| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | NULL | 1735689600 | NULL | -+----------------------------------------------+----------+--------------+----------+ ++----------------------------------------------+------------+----------+ +| UID | BUCKET_ID | UNMAPPED | ++----------------------------------------------+------------+----------+ +| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | ++----------------------------------------------+------------+----------+ ``` #### Mapping Request Example - Multiple Unhashed Phone Numbers @@ -260,8 +258,8 @@ The following query illustrates how to map multiple phone numbers, using the [de You must normalize phone numbers using the UID2 [Phone Number Normalization](../getting-started/gs-normalization-encoding.md#phone-number-normalization) rules. ```sql -select a.ID, a.PHONE, m.UID, m.PREV_UID, m.REFRESH_FROM, m.UNMAPPED from AUDIENCE a LEFT JOIN( - select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(PHONE, 'phone') t) m +select a.ID, a.PHONE, m.UID, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN( + select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(PHONE, 'phone') t) m on a.ID=m.ID; ``` @@ -270,15 +268,14 @@ Query results for multiple phone numbers: The following table identifies each item in the response, including `NULL` values for `NULL` or invalid phone numbers. ``` -+----+--------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ -| ID | PHONE | UID | PREV_UID | REFRESH_FROM | UNMAPPED | -+----+--------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ -| 1 | +12345678901 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL | -| 2 | +61491570006 | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | NULL | 1735689600 | NULL | -| 3 | +56789123001 | NULL | NULL | NULL | OPTOUT | -| 4 | 1234 | NULL | NULL | NULL | INVALID IDENTIFIER | -| 5 | NULL | NULL | NULL | NULL | INVALID IDENTIFIER | -+----+--------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ ++----+--------------+----------------------------------------------+------------+--------------------+ +| ID | PHONE | UID | BUCKET_ID | UNMAPPED | ++----+--------------+----------------------------------------------+------------+--------------------+ +| 1 | +12345678901 | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | +| 2 | +61491570006 | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL | +| 3 | 1234 | NULL | NULL | INVALID IDENTIFIER | +| 4 | NULL | NULL | NULL | INVALID IDENTIFIER | ++----+--------------+----------------------------------------------+------------+--------------------+ ``` #### Mapping Request Example - Single Hashed Email @@ -286,17 +283,17 @@ The following table identifies each item in the response, including `NULL` value The following query illustrates how to map a single email address hash, using the [default database and schema names](#database-and-schema-names). ```sql -select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(BASE64_ENCODE(SHA2_BINARY('validate@example.com', 256)), 'email_hash')); +select UID, BUCKET_ID, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('validate@example.com', 256)), 'email_hash')); ``` Query results for a single hashed email: ``` -+----------------------------------------------+----------------------------------------------+--------------+----------+ -| UID | PREV_UID | REFRESH_FROM | UNMAPPED | -+----------------------------------------------+----------------------------------------------+--------------+----------+ -| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL | -+----------------------------------------------+----------------------------------------------+--------------+----------+ ++----------------------------------------------+------------+----------+ +| UID | BUCKET_ID | UNMAPPED | ++----------------------------------------------+------------+----------+ +| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | ++----------------------------------------------+------------+----------+ ``` #### Mapping Request Example - Multiple Hashed Emails @@ -304,8 +301,8 @@ Query results for a single hashed email: The following query illustrates how to map multiple email address hashes, using the [default database and schema names](#database-and-schema-names). ```sql -select a.ID, a.EMAIL_HASH, m.UID, m.PREV_UID, m.REFRESH_FROM, m.UNMAPPED from AUDIENCE a LEFT JOIN( - select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(EMAIL_HASH, 'email_hash') t) m +select a.ID, a.EMAIL_HASH, m.UID, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN( + select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(EMAIL_HASH, 'email_hash') t) m on a.ID=m.ID; ``` @@ -314,14 +311,13 @@ Query results for multiple hashed emails: The following table identifies each item in the response, including `NULL` values for `NULL` hashes. ``` -+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ -| ID | EMAIL_HASH | UID | PREV_UID | REFRESH_FROM | UNMAPPED | -+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ -| 1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL | -| 2 | /XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g= | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | NULL | 1735689600 | NULL | -| 2 | UebesrNN0bQkm/QR7Jx7eav+UDXN5Gbq3zs1fLBMRy0= | NULL | NULL | 1735689600 | OPTOUT | -| 4 | NULL | NULL | NULL | NULL | INVALID IDENTIFIER | -+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ ++----+----------------------------------------------+----------------------------------------------+------------+--------------------+ +| ID | EMAIL_HASH | UID | BUCKET_ID | UNMAPPED | ++----+----------------------------------------------+----------------------------------------------+------------+--------------------+ +| 1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | +| 2 | NULL | NULL | NULL | INVALID IDENTIFIER | +| 3 | /XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g= | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL | ++----+----------------------------------------------+----------------------------------------------+------------+--------------------+ ``` #### Mapping Request Example - Single Hashed Phone Number @@ -329,17 +325,17 @@ The following table identifies each item in the response, including `NULL` value The following query illustrates how to map a single phone number hash, using the [default database and schema names](#database-and-schema-names). ```sql -select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(BASE64_ENCODE(SHA2_BINARY('+12345678901', 256)), 'phone_hash')); +select UID, BUCKET_ID, UNMAPPED from table(UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('+12345678901', 256)), 'phone_hash')); ``` Query results for a single hashed phone number: ``` -+----------------------------------------------+----------------------------------------------+--------------+----------+ -| UID | PREV_UID | REFRESH_FROM | UNMAPPED | -+----------------------------------------------+----------------------------------------------+--------------+----------+ -| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL | -+----------------------------------------------+----------------------------------------------+--------------+----------+ ++----------------------------------------------+------------+----------+ +| UID | BUCKET_ID | UNMAPPED | ++----------------------------------------------+------------+----------+ +| 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | ++----------------------------------------------+------------+----------+ ``` #### Mapping Request Example - Multiple Hashed Phone Numbers @@ -347,8 +343,8 @@ Query results for a single hashed phone number: The following query illustrates how to map multiple phone number hashes, using the [default database and schema names](#database-and-schema-names). ```sql -select a.ID, a.PHONE_HASH, m.UID, m.PREV_UID, m.REFRESH_FROM, m.UNMAPPED from AUDIENCE a LEFT JOIN( - select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP_V3(PHONE_HASH, 'phone_hash') t) m +select a.ID, a.PHONE_HASH, m.UID, m.BUCKET_ID, m.UNMAPPED from AUDIENCE a LEFT JOIN( + select ID, t.* from AUDIENCE, lateral UID2_PROD_UID_SH.UID.FN_T_IDENTITY_MAP(PHONE_HASH, 'phone_hash') t) m on a.ID=m.ID; ``` @@ -357,64 +353,65 @@ Query results for multiple hashed phone numbers: The following table identifies each item in the response, including `NULL` values for `NULL` hashes. ``` -+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ -| ID | PHONE_HASH | UID | PREV_UID | REFRESH_FROM | UNMAPPED | -+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ -| 1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | vP9zK2mL7fR4tY8qN3wE6xB0dH5jA1sC+nI/oGuMeVa= | 1735689600 | NULL | -| 2 | /XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g= | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | NULL | 1735689600 | NULL | -| 2 | UebesrNN0bQkm/QR7Jx7eav+UDXN5Gbq3zs1fLBMRy0= | NULL | NULL | 1735689600 | OPTOUT | -| 4 | NULL | NULL | NULL | NULL | INVALID IDENTIFIER | -+----+----------------------------------------------+----------------------------------------------+----------------------------------------------+--------------+--------------------+ ++----+----------------------------------------------+----------------------------------------------+------------+--------------------+ +| ID | PHONE_HASH | UID | BUCKET_ID | UNMAPPED | ++----+----------------------------------------------+----------------------------------------------+------------+--------------------+ +| 1 | LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI= | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL | +| 2 | NULL | NULL | NULL | INVALID IDENTIFIER | +| 3 | /XJSTajB68SCUyuc3ePyxSLNhxrMKvJcjndq8TuwW5g= | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL | ++----+----------------------------------------------+----------------------------------------------+------------+--------------------+ ``` -### Monitor Raw UID2 Refresh and Regenerate Raw UID2s +### Monitor for Salt Bucket Rotation and Regenerate Raw UID2s -The `FN_T_IDENTITY_MAP_V3` function returns refresh timestamps (`REFRESH_FROM`) that indicate when each UID2 should be refreshed. +The `SALT_BUCKETS` view query returns the date and time when the salt buckets for the raw UID2s were last updated. A salt value is used when generating UID2s. When the salt in the bucket is updated, the previously generated UID2 becomes outdated and doesn’t match the UID2 generated by other parties for the same user. -To determine which UID2s need regeneration, compare the current time to the `REFRESH_FROM` timestamps returned by the function. +To determine which UID2s need regeneration, compare the timestamps of when they were generated to the most recent timestamp of the salt bucket update. -| Column Name | Data Type | Description | -|:------------------|:--------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `UID` | TEXT | The UID2 associated with the DII. This is the current UID2 value returned by the identity mapping function. | -| `REFRESH_FROM` | TIMESTAMP | The timestamp (in epoch seconds) indicating when this UID2 should be refreshed. Compare this value to the current time to determine if regeneration is needed. | +| Column Name | Data Type | Description | +|:-----------------------|:--------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `BUCKET_ID` | TEXT | The ID of the salt bucket. This ID parallels the `BUCKET_ID` returned by the identity map function. Use the `BUCKET_ID` as the key to do a join query between the function call results and results from this view call. | +| `LAST_SALT_UPDATE_UTC` | TIMESTAMP_NTZ | The last time the salt in the bucket was updated. This value is expressed in UTC. | -The following example shows an input table and the query used to find the UID2s in the table that must be regenerated because their refresh time has been reached. +The following example shows an input table and the query used to find the UID2s in the table that must be regenerated because the salt bucket was updated. #### Targeted Input Table -In this example scenario, the advertiser/data provider has stored the UID2s in a table named `AUDIENCE_WITH_UID2`. The `REFRESH_FROM` column contains the timestamp when each UID2 should be refreshed. If no UID2 has been generated, the value is `NULL`, as shown in the third example. The advertiser/data provider can compare these timestamps to the current time to determine which UID2s need to be regenerated. +In this example scenario, the advertiser/data provider has stored the UID2s in a table named `AUDIENCE_WITH_UID2`. The last column, `LAST_UID2_UPDATE_UTC`, is used to record the time at which a UID2 was generated. If no UID2 has been generated, the value is `NULL`, as shown in the third example. The advertiser/data provider can use this timestamp value to determine which UID2s need to be regenerated. ```sql select * from AUDIENCE_WITH_UID2; ``` ``` -+----+----------------------+----------------------------------------------+--------------+ -| ID | EMAIL | UID2 | REFRESH_FROM | -+----+----------------------+----------------------------------------------+--------------+ -| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | 1735689600 | -| 2 | test1@uidapi.com | Q4A5ZBuBCYfuV3Wd8Fdsx2+i33v7jyFcQbcMG/LH4eM= | 1735776000 | -| 3 | test2@uidapi.com | NULL | NULL | -+----+----------------------+----------------------------------------------+--------------+ ++----+----------------------+----------------------------------------------+------------+-------------------------+ +| ID | EMAIL | UID2 | BUCKET_ID | LAST_UID2_UPDATE_UTC | ++----+----------------------+----------------------------------------------+------------+-------------------------+ +| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | 2025-02-01 00:00:00.000 | +| 2 | test1@uidapi.com | Q4A5ZBuBCYfuV3Wd8Fdsx2+i33v7jyFcQbcMG/LH4eM= | ad1ANEmVZ | 2025-02-03 00:00:00.000 | +| 3 | test2@uidapi.com | NULL | NULL | NULL | ++----+----------------------+----------------------------------------------+------------+-------------------------+ ``` -To find missing or outdated UID2s, use the following query example. +To find missing or outdated UID2s, use the following query example, which uses the [default database and schema names](#database-and-schema-names). ```sql -select * from AUDIENCE_WITH_UID2 - where REFRESH_FROM <= DATE_PART(epoch_second, CURRENT_TIMESTAMP()) or UID2 IS NULL; +select a.*, b.LAST_SALT_UPDATE_UTC + from AUDIENCE_WITH_UID2 a LEFT OUTER JOIN UID2_PROD_UID_SH.UID.SALT_BUCKETS b + on a.BUCKET_ID=b.BUCKET_ID + where a.LAST_UID2_UPDATE_UTC < b.LAST_SALT_UPDATE_UTC or a.UID2 IS NULL; ``` Query results: -The following table identifies each item in the response. The result includes UID2s that need to be refreshed because their `REFRESH_FROM` timestamp has passed, or UID2s that are missing. ID 1 is returned because its refresh time (1735689600) is in the past (assuming current time is later). ID 2 is not returned because its refresh time hasn't been reached yet. ID 3 is returned due to a missing UID2. +The following table identifies each item in the response. The result includes an email, `UID2`, `BUCKET_ID`, `LAST_UID2_UPDATE_UTC`, and `LAST_SALT_UPDATE_UTC` as shown in the ID 1 example in the table. No information is returned for ID 2 because the corresponding UID2 was generated after the last bucket update. For ID 3, `NULL` values are returned due to a missing UID2. ``` -+----+----------------------+----------------------------------------------+--------------+ -| ID | EMAIL | UID2 | REFRESH_FROM | -+----+----------------------+----------------------------------------------+--------------+ -| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | 1735689600 | -| 3 | test2@uidapi.com | NULL | NULL | -+----+----------------------+----------------------------------------------+--------------+ ++----+----------------------+----------------------------------------------+------------+-------------------------+-------------------------+ +| ID | EMAIL | UID2 | BUCKET_ID | LAST_UID2_UPDATE_UTC | LAST_SALT_UPDATE_UTC | ++----+----------------------+----------------------------------------------+------------+-------------------------+-------------------------+ +| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | 2025-02-01 00:00:00.000 | 2025-02-02 00:00:00.000 | +| 3 | test2@uidapi.com | NULL | NULL | NULL | NULL | ++----+----------------------+----------------------------------------------+------------+-------------------------+-------------------------+ ``` ## Usage for UID2 Sharers @@ -526,9 +523,9 @@ In most circumstances where UID2 token cannot be successfully decrypted, the fun Possible values for `DECRYPTION_STATUS` are: -| Value | Meaning | -| :-------------- | :---------------------------------------------------------------------------- | -| `NULL` | The UID2 token was successfully decrypted. | +| Value | Meaning | +| :-- | :-- | +| `NULL` | The UID2 token was successfully decrypted. | | `EXPIRED_TOKEN` | The UID2 token is beyond its designated lifetime—the token has expired. | #### Decrypt Token Request Example—Single UID2 Token @@ -614,28 +611,31 @@ To help prevent UID2 tokens from expiring, decrypt the UID2 tokens as soon as th ## Migration Guide -This section provides information to help you upgrade from the previous version to the new UID2 Snowflake functionality with v3 functions. +This section includes the following information to help you upgrade to the new UID2 Snowflake Marketplace functionality: -:::note -If you're upgrading from a version earlier than February 2025, see [Migration Guide](integration-snowflake-before-july-2025.md#migration-guide) in the documentation for the February 2025 update. -::: +- [Accessing the New Data Share](#accessing-the-new-data-share) +- [Changing Existing Code](#changing-existing-code) + +### Accessing the New Data Share + +To access the new data share, follow the instructions in [Access the UID2 Share](#access-the-uid2-share). ### Changing Existing Code -For a summary of changes, see [Changes from Previous Version](#changes-from-previous-version). The code snippets in this section are before/after examples of how the earlier functions might be implemented, and how you could update to use the new function. The key change is migrating from `FN_T_IDENTITY_MAP` to `FN_T_IDENTITY_MAP_V3`, which provides refresh timestamps instead of salt bucket IDs and includes previous UID2 access. +For a summary of changes, see [Changes from Previous Version](#changes-from-previous-version). The code snippets in this section are before/after examples of how the earlier functions might be implemented, and how you could update to use the new function. #### Example for Mapping Unhashed Emails Before: ```sql -select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP(EMAIL, 'email')); +select UID2, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_IDENTITY_MAP(EMAIL, 'email')); ``` After: ```sql -select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP_V3(EMAIL, 'email')); +select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP(EMAIL, 'email')); ``` #### Example for Mapping Unhashed Phone Numbers @@ -643,20 +643,29 @@ select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_ Before: ```sql -select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP(PHONE_NUMBER, 'phone')); +select UID2, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_IDENTITY_MAP(PHONE_NUMBER, 'phone')); ``` After: ```sql -select UID, PREV_UID, REFRESH_FROM, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP_V3(PHONE_NUMBER, 'phone')); +select UID, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_IDENTITY_MAP(PHONE_NUMBER, 'phone')); ``` -#### Example for Monitoring UID2 Refresh and Regenerating Raw UID2s +#### Example for Monitoring Salt Bucket Rotation and Regenerating Raw UID2s -The v3 function provides refresh timestamps directly, eliminating the need to monitor salt buckets. Instead of joining with salt bucket views, you can compare the current timestamp against the `REFRESH_FROM` timestamp returned by the function. +The following queries use the same example table, `AUDIENCE_WITH_UID2`, that we used in [Targeted Input Table](#targeted-input-table). -Before (using salt bucket monitoring): +Before: + +```sql +select a.*, b.LAST_SALT_UPDATE_UTC + from AUDIENCE_WITH_UID2 a LEFT OUTER JOIN {DATABASE_NAME}.{SCHEMA_NAME}.UID2_SALT_BUCKETS b + on a.BUCKET_ID=b.BUCKET_ID + where a.LAST_UID2_UPDATE_UTC < b.LAST_SALT_UPDATE_UTC or a.UID2 IS NULL; +``` + +After: ```sql select a.*, b.LAST_SALT_UPDATE_UTC @@ -665,9 +674,29 @@ select a.*, b.LAST_SALT_UPDATE_UTC where a.LAST_UID2_UPDATE_UTC < b.LAST_SALT_UPDATE_UTC or a.UID2 IS NULL; ``` -After (using refresh timestamp monitoring): +#### Example for Token Encryption + +Before: + +```sql +select UID2_TOKEN, ENCRYPTION_STATUS from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_ENCRYPT('2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU=')); +``` + +After: ```sql -select * from AUDIENCE_WITH_UID2 - where REFRESH_FROM <= DATE_PART(epoch_second, CURRENT_TIMESTAMP()) or UID2 IS NULL; +select UID_TOKEN, ENCRYPTION_STATUS from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_ENCRYPT('2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU=')); +``` + +#### Example for Token Decryption + +Before: + +```sql +select UID2, SITE_ID, DECRYPTION_STATUS from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_DECRYPT('A41234')); +``` + +After: +```sql +select UID, SITE_ID, DECRYPTION_STATUS from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_DECRYPT('A41234')); ``` diff --git a/docs/ref-info/deprecation-schedule.md b/docs/ref-info/deprecation-schedule.md index 4b70b92ec..a16cf7c2b 100644 --- a/docs/ref-info/deprecation-schedule.md +++ b/docs/ref-info/deprecation-schedule.md @@ -41,7 +41,7 @@ The latest ZIP file is available in the Assets section at the bottom of the link | Q3 2024 | [v5.38.104](https://github.com/IABTechLab/uid2-operator/releases/tag/v5.38.104) | 5.38.104 | September 12, 2024 | Mar 31, 2026 | | Q2 2024 | [v5.37.12](https://github.com/IABTechLab/uid2-operator/releases/tag/v5.37.12) | 5.37.12 | June 12, 2024 | Sep 30, 2025 | -For documentation, see [UID2 Private Operator for AWS Integration Guide](../guides/operator-guide-aws-marketplace.md). +For documentation, see [UID2 Private Operator for AWS Integration Guide](..\guides\operator-guide-aws-marketplace.md). ### Private Operator for GCP @@ -55,7 +55,7 @@ The latest ZIP file is linked in the GCP Download column in the following table. | Q3 2024 | [v5.38.104](https://github.com/IABTechLab/uid2-operator/releases/tag/v5.38.104) | [gcp-oidc-deployment-files-5.38.104.zip](https://github.com/IABTechLab/uid2-operator/releases/download/v5.38.104/gcp-oidc-deployment-files-5.38.104.zip) | September 12, 2024 | Mar 31, 2026 | | Q2 2024 | [v5.37.12](https://github.com/IABTechLab/uid2-operator/releases/tag/v5.37.12) | [gcp-oidc-deployment-files-5.37.12.zip](https://github.com/IABTechLab/uid2-operator/releases/download/v5.37.12/gcp-oidc-deployment-files-5.37.12.zip) | June 12, 2024 | Sep 30, 2025 | -For documentation, see [UID2 Private Operator for GCP Integration Guide](../guides/operator-private-gcp-confidential-space.md). +For documentation, see [UID2 Private Operator for GCP Integration Guide](..\guides\operator-private-gcp-confidential-space.md). ### Private Operator for Azure @@ -69,7 +69,7 @@ The latest ZIP file is linked in the Azure Download column in the following tabl | Q3 2024 | [v5.38.104](https://github.com/IABTechLab/uid2-operator/releases/tag/v5.38.104) | [azure-cc-deployment-files-5.38.104.zip](https://github.com/IABTechLab/uid2-operator/releases/download/v5.38.104/azure-cc-deployment-files-5.38.104.zip) | September 12, 2024 | Mar 31, 2026 | | Q2 2024 | [v5.37.12](https://github.com/IABTechLab/uid2-operator/releases/tag/v5.37.12) | [azure-cc-deployment-files-5.37.12.zip](https://github.com/IABTechLab/uid2-operator/releases/download/v5.37.12/azure-cc-deployment-files-5.37.12.zip) | June 12, 2024 | Sep 30, 2025 | -For documentation, see [UID2 Private Operator for Azure Integration Guide](../guides/operator-guide-azure-enclave.md). +For documentation, see [UID2 Private Operator for Azure Integration Guide](..\guides\operator-guide-azure-enclave.md).