From a4c487c06788777c9d9ec4f69520d8e630735422 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Fri, 6 Jun 2025 16:15:08 -0400 Subject: [PATCH 01/28] Add POST /identity/map v3 --- docs/endpoints/post-identity-map-v2.md | 207 ++++++++++++++++++ docs/endpoints/post-identity-map.md | 16 +- .../current/endpoints/post-identity-map-v2.md | 203 +++++++++++++++++ .../current/endpoints/post-identity-map.md | 10 +- sidebars.js | 17 +- 5 files changed, 446 insertions(+), 7 deletions(-) create mode 100644 docs/endpoints/post-identity-map-v2.md create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md new file mode 100644 index 000000000..9ec72f006 --- /dev/null +++ b/docs/endpoints/post-identity-map-v2.md @@ -0,0 +1,207 @@ +--- +title: POST /identity/map (v2) +description: Maps DII to raw UID2s and salt bucket IDs. +hide_table_of_contents: false +sidebar_position: 08 +--- + +import Link from '@docusaurus/Link'; + +# POST /identity/map (v2) + +:::important +This documentation is for earlier versions of the `POST /identity/map` endpoint. If you're using an earlier version, we recommend upgrading. No specific migration steps are needed. For the latest version, v3, see [POST /identity/map](post-identity-map.md). +::: + +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information. + +Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). + +For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). + +## Version + +This documentation is for version 2 of this endpoint. + +## Batch Size and Request Parallelization Requirements + +Here's what you need to know: + +- The maximum request size is 1MB. +- To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch. +- Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. +- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). + +## Request Format + +`POST '{environment}/v2/identity/map'` + +For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md). + +:::important +You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). +::: + +### Path Parameters + +| Path Parameter | Data Type | Attribute | Description | +| :--- | :--- | :--- | :--- | +| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`
Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). | + +:::note +The integration environment and the production environment require different API keys. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials). +::: + +### Unencrypted JSON Body Parameters + +:::important +You must include only **one** of the following four conditional parameters as a key-value pair in the JSON body of the request when encrypting it. +::: + +| Body Parameter | Data Type | Attribute | Description | +| :--- | :--- | :--- | :--- | +| `email` | string array | Conditionally Required | The list of email addresses to be mapped. | +| `email_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email addresses to be mapped. | +| `phone` | string array | Conditionally Required | The list of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | +| `phone_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | + +### Request Examples + +The following are unencrypted JSON request body examples for each parameter, one of which you should include in your requests to the `POST /identity/map` endpoint: + +```json +{ + "email":[ + "user@example.com", + "user2@example.com" + ] +} +``` +```json +{ + "email_hash":[ + "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", + "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU=" + ] +} +``` +```json +{ + "phone":[ + "+12345678901", + "+441234567890" + ] +} +``` +```json +{ + "phone_hash":[ + "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=" + ] +} +``` + +Here's an encrypted request example to the `POST /identity/map` endpoint for a phone number: + +```sh +echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret] +``` + +For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). + +## Decrypted JSON Response Format + +:::note +The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted. +::: + +A successful decrypted response returns the raw UID2s and salt bucket IDs for the specified email addresses, phone numbers, or their respective hashes. + +```json +{ + "body":{ + "mapped": [ + { + "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "a30od4mNRd" + }, + { + "identifier": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=", + "advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=", + "bucket_id": "ad1ANEmVZ" + } + ] + }, + "status":"success" +} +``` + +If some identifiers are considered invalid, they are included in the response in an "unmapped" list. In this case, the response status is still "success". If all identifiers are mapped, the "unmapped" list is not included in the response. + +```json +{ + "body":{ + "mapped": [ + { + "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "a30od4mNRd" + } + ], + "unmapped": [ + { + "identifier": "some@malformed@email@hash", + "reason": "invalid identifier" + } + ] + }, + "status":"success" +} +``` + +If some identifiers have opted out from the UID2 ecosystem, the opted-out identifiers are moved to the "unmapped" list along with any invalid identifiers found. In this case, the response status is still "success". + +```json +{ + "body":{ + "mapped": [ + { + "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "a30od4mNRd" + } + ], + "unmapped": [ + { + "identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", + "reason": "optout" + } + ] + }, + "status":"success" +} +``` + +### Response Body Properties + +The response body includes the properties shown in the following table. + +| Property | Data Type | Description | +| :--- | :--- | :--- | +| `identifier` | string | The email address, phone number, or respective hash specified in the request body. | +| `advertising_id` | string | The corresponding advertising ID (raw UID2). | +| `bucket_id` | string | The ID of the salt bucket used to generate the raw UID2. | + +### Response Status Codes + +The following table lists the `status` property values and their HTTP status code equivalents. + +| Status | HTTP Status Code | Description | +| :--- | :--- | :--- | +| `success` | 200 | The request was successful. The response will be encrypted. | +| `client_error` | 400 | The request had missing or invalid parameters.| +| `unauthorized` | 401 | The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested operation. | + +If the `status` value is anything other than `success`, the `message` field provides additional information about the issue. diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 70b2bfb7c..2b51298f2 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -1,6 +1,6 @@ --- title: POST /identity/map -description: Maps DII to raw UID2s and salt bucket IDs. +description: Maps DII to raw UID2s. hide_table_of_contents: false sidebar_position: 08 --- @@ -9,12 +9,20 @@ import Link from '@docusaurus/Link'; # POST /identity/map -Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information. +[**TO BE UPDATED. VERSION SECTION ADDED BUT THE REST NEEDS UPDATING**] + +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information. Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). +## Version + +This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. No specific migration steps are needed. + +If needed, documentation is also available for the previous version, v2: see [POST /identity/map (v2)](post-identity-map-v2.md). + ## Batch Size and Request Parallelization Requirements Here's what you need to know: @@ -108,7 +116,7 @@ For details, and code examples in different programming languages, see [Encrypti The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted. ::: -A successful decrypted response returns the raw UID2s and salt bucket IDs for the specified email addresses, phone numbers, or their respective hashes. +A successful decrypted response returns the raw UID2s for the specified email addresses, phone numbers, or their respective hashes. ```json { @@ -184,7 +192,7 @@ The response body includes the properties shown in the following table. | :--- | :--- | :--- | | `identifier` | string | The email address, phone number, or respective hash specified in the request body. | | `advertising_id` | string | The corresponding advertising ID (raw UID2). | -| `bucket_id` | string | The ID of the salt bucket used to generate the raw UID2. | +| `TODO` | string | TODO: NEW VALUES | ### Response Status Codes diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md new file mode 100644 index 000000000..99f0bcda2 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md @@ -0,0 +1,203 @@ +--- +title: POST /identity/map (v2) +description: DII を raw UID2 とソルトバケット ID にマッピング。 +hide_table_of_contents: false +sidebar_position: 08 +--- + +import Link from '@docusaurus/Link'; + +# POST /identity/map (v2) + +:::important +This documentation is for earlier versions of the `POST /identity/map` endpoint. If you're using an earlier version, we recommend upgrading. No specific migration steps are needed. For the latest version, v3, see [POST /identity/map](post-identity-map.md). +::: + +複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 と salt bucket IDs にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます + +Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) を参照してください。 + +UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳細は、[User Opt-Out](../getting-started/gs-opt-out.md) を参照してください。 + +## Batch Size and Request Parallelization Requirements + +知っておくべきことは以下のとおりです: + +- リクエストの最大サイズは 1MB です。 +- 大量のメールアドレス、電話番号、またはそれぞれのハッシュをマップするには、1 バッチあたり最大 5,000 アイテムのバッチサイズで、それらを *連続した* バッチで送信してください。 +- Private Operator を使用している場合を除き、バッチを並行して送信しないでください。つまり、単一の HTTP 接続を使用して、[directly identifying information (DII)](../ref-info/glossary-uid.md#gl-dii) を連続してマッピングしてください。 +- メールアドレス、電話番号、またはそれぞれのハッシュのマッピングを必ず保存してください。
マッピングを保存しないと、数百万のメールアドレスや電話番号をマッピングする必要がある場合に、処理時間が大幅に増加する可能性があります。しかし、実際に更新が必要なマッピングのみを再計算することで、毎日更新が必要な raw UID2 の数は約 1/365 となり、総処理時間を短縮できます。[Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) と [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers) も参照してください。 + +## Request Format + +`POST '{environment}/v2/identity/map'` + +認証の詳細は、 [Authentication and Authorization](../getting-started/gs-auth.md) を参照してください。 + +:::important +すべてのリクエストを秘密鍵で暗号化する必要があります。詳細といくつかのプログラミング言語でのコードの例は、[リクエストの暗号化とレスポンスの復号化](../getting-started/gs-encryption-decryption.md) を参照してください。 +::: + +### Path Parameters + +| Path Parameter | Data Type | Attribute | Description | +| :--- | :--- | :--- | :--- | +| `{environment}` | string | 必須 | テスト (インテグレーション) 環境: `https://operator-integ.uidapi.com`
本番環境: `https://prod.uidapi.com`
リージョンごとのオペレーターを含む全リストは [Environments](../getting-started/gs-environments.md) を参照してください。 | + +:::note +インテグレーション環境と本番環境では、異なる API Key が必要です。各環境の認証情報を取得する方法については、[Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials) を参照してください。 +::: + +### Unencrypted JSON Body Parameters + +:::important +リクエストを暗号化するときは、以下の 4 つの条件パラメータのうち、**1つ** だけをリクエストの JSON ボディにキーと値のペアとして含める必要がります。 +::: + +| Body Parameter | Data Type | Attribute | Description | +| :--- | :--- | :--- | :--- | +| `email` | string array | 条件付きで必要 | マッピングするメールアドレスのリストです。 | +| `email_hash` | string array | 条件付きで必要 | マッピングする [SHA-256 ハッシュし、Base64 エンコード](../getting-started/gs-normalization-encoding.md#email-address-normalization) した [正規化](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) 済みメールアドレスのリストです。 | +| `phone` | string array | 条件付きで必要 | マッピングする [正規化](../getting-started/gs-normalization-encoding.md#phone-number-normalization) 済み電話番号のリストです。 | +| `phone_hash` | string array | 条件付きで必要 | マッピングする [SHA-256 ハッシュし、Base64 エンコード](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) した [正規化](../getting-started/gs-normalization-encoding.md#phone-number-normalization) 済み電話番号のリストです。 | + +### Request Examples + +以下は、各パラメータの暗号化されていない JSON リクエストボディの例です。このうちの 1 つを、`POST /identity/map` エンドポイントへのリクエストに含める必要があります: + +```json +{ + "email": [ + "user@example.com", + "user2@example.com" + ] +} +``` +```json +{ + "email_hash": [ + "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", + "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU=" + ] +} +``` +```json +{ + "phone": [ + "+12345678901", + "+441234567890" + ] +} +``` +```json +{ + "phone_hash": [ + "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=" + ] +} +``` + +以下は、電話番号に対する `POST /identity/map` エンドポイントへの暗号化リクエストの例です: + +```sh +echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret] +``` + +詳細といくつかのプログラミング言語でのコードの例は、[リクエストの暗号化とレスポンスの復号化](../getting-started/gs-encryption-decryption.md) を参照してください。 + +## Decrypted JSON Response Format + +:::note +レスポンスは、HTTP ステータスコードが 200 の場合のみ暗号化されます。それ以外の場合、レスポンスは暗号化されません。 +::: + +復号化に成功すると、指定したメールアドレス、電話番号、またはそれぞれのハッシュに対する raw UID2 とソルトバケット ID が返されます。 + +```json +{ + "body": { + "mapped": [ + { + "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "a30od4mNRd" + }, + { + "identifier": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=", + "advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=", + "bucket_id": "ad1ANEmVZ" + } + ] + }, + "status": "success" +} +``` + +一部の識別子が無効と判断された場合、それらの識別子は "unmapped" リストとしてレスポンスに含まれる。この場合でも、レスポンスステータスは "success" となります。すべての識別子がマッピングされた場合、"unmapped"リストはレスポンスに含まれません。 + +```json +{ + "body": { + "mapped": [ + { + "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "a30od4mNRd" + } + ], + "unmapped": [ + { + "identifier": "some@malformed@email@hash", + "reason": "invalid identifier" + } + ] + }, + "status": "success" +} +``` + +一部の識別子が UID2 エコシステムからオプトアウトしている場合、オプトアウトした識別子は、見つかった無効な識別子とともに "unmapped" リストに移動されます。この場合でも、レスポンスステータスは "success" です。 + +```json +{ + "body": { + "mapped": [ + { + "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "a30od4mNRd" + } + ], + "unmapped": [ + { + "identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", + "reason": "optout" + } + ] + }, + "status": "success" +} +``` + +### Response Body Properties + +レスポンスボディには、次の表に示すプロパティが含まれます。 + +| Property | Data Type | Description | +| :--- | :--- | :--- | +| `identifier` | string | リクエストボディで指定されたメールアドレス、電話番号、またはそれぞれのハッシュです。 | +| `advertising_id` | string | 対応する Advertising ID (raw UID2) です。 | +| `bucket_id` | string | raw UID2 の生成に使用したソルトバケットの ID です。 | + +### Response Status Codes + +次の表は、`status` プロパティの値と、それに対応する HTTP ステータスコードの一覧です。 + +| Status | HTTP Status Code | Description | +| :--- | :--- | :--- | +| `success` | 200 | リクエストは成功しました。レスポンスは暗号化されています。 | +| `client_error` | 400 | リクエストに不足している、または無効なパラメータがありました。 | +| `unauthorized` | 401 | クエストにベアラートークンが含まれていない、無効なベアラートークンが含まれている、またはリクエストされた操作を実行するのに許可されていないベアラートークンが含まれていた。 | + +`status` の値が `success` 以外であれば、`message` フィールドにその問題に関する追加情報が表示されます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md index 3fec46ef5..1791dde46 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md @@ -1,6 +1,6 @@ --- title: POST /identity/map -description: DII を raw UID2 とソルトバケット ID にマッピング。 +description: Maps DII to raw UID2s. hide_table_of_contents: false sidebar_position: 08 --- @@ -9,12 +9,20 @@ import Link from '@docusaurus/Link'; # POST /identity/map +[**TO BE UPDATED. VERSION SECTION ADDED BUT THE REST NEEDS UPDATING**] + 複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 と salt bucket IDs にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) を参照してください。 UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳細は、[User Opt-Out](../getting-started/gs-opt-out.md) を参照してください。 +## Version + +This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. No specific migration steps are needed. + +If needed, documentation is also available for the previous version, v2: see [POST /identity/map (v2)](post-identity-map-v2.md). + ## Batch Size and Request Parallelization Requirements 知っておくべきことは以下のとおりです: diff --git a/sidebars.js b/sidebars.js index 637ae41a6..f053c4e74 100644 --- a/sidebars.js +++ b/sidebars.js @@ -309,7 +309,7 @@ const fullSidebar = [ { type: 'category', - label: 'Endpoints (v2)', + label: 'Endpoints', link: { type: 'doc', id: 'endpoints/summary-endpoints', @@ -320,7 +320,18 @@ const fullSidebar = [ 'endpoints/post-token-validate', 'endpoints/post-token-refresh', 'endpoints/post-identity-buckets', - 'endpoints/post-identity-map', + { + type: 'category', + label: 'POST /identity/map', + link: { + type: 'doc', + id: 'endpoints/post-identity-map', + }, + collapsed: true, + items: [ + 'endpoints/post-identity-map-v2', + ], + }, 'endpoints/post-optout-status', ], }, @@ -398,7 +409,9 @@ const sidebars = { 'DSP Integrations', 'guides/dsp-guide', 'endpoints/post-identity-buckets', + 'POST /identity/map', 'endpoints/post-identity-map', + 'endpoints/post-identity-map-v2', 'endpoints/post-optout-status' ), From 4bb0bbf45a762a133c63f48551953a43f9404409 Mon Sep 17 00:00:00 2001 From: sophia chen Date: Wed, 11 Jun 2025 11:56:18 +1000 Subject: [PATCH 02/28] initial update of identity map docs with v3 fields --- docs/endpoints/post-identity-map.md | 143 ++++++++++++---------------- 1 file changed, 62 insertions(+), 81 deletions(-) diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 2b51298f2..2a2ecef67 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -9,9 +9,10 @@ import Link from '@docusaurus/Link'; # POST /identity/map -[**TO BE UPDATED. VERSION SECTION ADDED BUT THE REST NEEDS UPDATING**] - -Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information. +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to: +* check for updates opt-out information +* check when an advertisting ID may be refreshed +* map the previous advertising ID for advertising IDs that are less than 90 days old Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). @@ -55,49 +56,49 @@ The integration environment and the production environment require different
  • Date: Wed, 11 Jun 2025 14:48:24 +1000 Subject: [PATCH 03/28] small fixes --- docs/endpoints/post-identity-map.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 2a2ecef67..45f351c16 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -9,10 +9,7 @@ import Link from '@docusaurus/Link'; # POST /identity/map -Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to: -* check for updates opt-out information -* check when an advertisting ID may be refreshed -* map the previous advertising ID for advertising IDs that are less than 90 days old +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when an advertisting ID may be refreshed or view the previous advertising ID for advertising IDs that are less than 90 days old. Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). @@ -148,8 +145,8 @@ Identifiers that cannot be mapped to an advertising ID are mapped to an error ob { "body":{ "email": [ - { "e": "INVALID" }, - { "e": "OPTOUT" } + { "e": "invalid identifier" }, + { "e": "optout" } ], "email_hash": [], "phone": [], @@ -163,17 +160,17 @@ Identifiers that cannot be mapped to an advertising ID are mapped to an error ob For successfully mapped DIIs, the response body includes the properties shown in the following table. -| Property | Data Type | Description | -|:---------|:---------------|:--------------------------------------------------------------------------------------------------------------------------------------| -| `u` | string | The advertising ID (raw UID2) of the DII given in the request. | -| `p` | string or null | The previous advertising ID if the current ID has been refreshed in the last 90 days. `null` if the current ID is older than 90 days. | -| `r` | number | The Unix timestamp (in milliseconds) that indicates when the advertising ID may be refreshed. | +| Property | Data Type | Description | +|:---------|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------| +| `u` | string | The advertising ID (raw UID2) of the DII given in the request. | +| `p` | string | The previous advertising ID if the current ID has been refreshed in the last 90 days. `Null` if the current ID is older than 90 days. | +| `r` | number | The Unix timestamp (in milliseconds) that indicates when the advertising ID may be refreshed. | For unsuccessfully mapped DIIs, the response body includes the properties shown in the following table. | Property | Data Type | Description | |:---------|:----------|:-----------------------------------------------------------------------------------------------| -| `e` | string | The reason for being unable to map the DII to an advertising ID. One of: "OPTOUT", "INVALID". | +| `e` | string | The reason for being unable to map the DII to an advertising ID. | ### Response Status Codes From e1146d6e975c3ec95a7f674093d63d895ff76da2 Mon Sep 17 00:00:00 2001 From: sophia chen Date: Wed, 11 Jun 2025 17:10:11 +1000 Subject: [PATCH 04/28] added more detail on response properties --- docs/endpoints/post-identity-map.md | 58 ++++++++++++++--------------- 1 file changed, 28 insertions(+), 30 deletions(-) diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 45f351c16..a57edfcdf 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -9,7 +9,7 @@ import Link from '@docusaurus/Link'; # POST /identity/map -Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when an advertisting ID may be refreshed or view the previous advertising ID for advertising IDs that are less than 90 days old. +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when an advertisting ID may be refreshed, or view the previous advertising ID for advertising IDs that are less than 90 days old. Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). @@ -32,7 +32,7 @@ Here's what you need to know: ## Request Format -`POST '{environment}/v2/identity/map'` +`POST '{environment}/v3/identity/map'` For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md). @@ -56,19 +56,20 @@ The integration environment and the production environment require different
  • Date: Wed, 11 Jun 2025 17:37:18 +1000 Subject: [PATCH 05/28] small fix --- docs/endpoints/post-identity-map.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index a57edfcdf..64a3e5f27 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -63,7 +63,6 @@ You can include one or more of the following four parameters as a key-value pair | `phone` | array of DII objects | Conditionally Required | The list of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | | `phone_hash` | array of DII objects | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | -#### DII Object Each DII i.e. email address, email hash, phone or phone hash, is input as a DII object. @@ -116,6 +115,7 @@ The response is encrypted only if the HTTP status code is 200. Otherwise, the re ::: A successful decrypted response returns the raw UID2s for the specified email addresses, phone numbers, or their respective hashes in the same array order that was given. + Identifiers that cannot be mapped to an advertising ID are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping will occur if the identifier is considered invalid or if the identifier has opted out from the UID2 ecosystem. In these cases, the response status is still "success". ```json @@ -154,7 +154,6 @@ Identifiers that cannot be mapped to an advertising ID are mapped to an error ob | `phone` | array of mapped DII objects | Conditionally Required | The list of mapped DII objects corresponding to the list of given phone numbers. | | `phone_hash` | array of mapped DII objects | Conditionally Required | The list of mapped DII objects corresponding to the list of given phone number hashes. | -#### Mapped DII Objects For successfully mapped DIIs, the mapped object includes the properties shown in the following table. From e2669aa6f58681b662fbaac05f71fb89240fd01e Mon Sep 17 00:00:00 2001 From: sophia chen Date: Wed, 11 Jun 2025 17:42:45 +1000 Subject: [PATCH 06/28] added example previous uid --- docs/endpoints/post-identity-map.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 64a3e5f27..1c2f03995 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -124,7 +124,7 @@ Identifiers that cannot be mapped to an advertising ID are mapped to an error ob "email": [ { "u": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "p": null, + "p": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", "r": 1735689600000 }, { From b5f24e1c4ee38e9751fe7a6aa9b2eab163f6dcb1 Mon Sep 17 00:00:00 2001 From: sophia chen Date: Thu, 12 Jun 2025 10:25:14 +1000 Subject: [PATCH 07/28] fixed wording --- docs/endpoints/post-identity-map.md | 52 ++++++++++++++--------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 1c2f03995..a4bb7ac25 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -9,7 +9,7 @@ import Link from '@docusaurus/Link'; # POST /identity/map -Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when an advertisting ID may be refreshed, or view the previous advertising ID for advertising IDs that are less than 90 days old. +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when an advertising ID can be refreshed, or view the previous advertising ID if the current one is less than 90 days old. Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). @@ -53,22 +53,22 @@ The integration environment and the production environment require different
  • Date: Fri, 13 Jun 2025 14:43:31 +1000 Subject: [PATCH 08/28] removed dii object in request --- .idea/.gitignore | 8 +++++ docs/endpoints/post-identity-map-v2.md | 2 +- docs/endpoints/post-identity-map.md | 48 +++++++++++--------------- 3 files changed, 30 insertions(+), 28 deletions(-) create mode 100644 .idea/.gitignore diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 000000000..13566b81b --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,8 @@ +# 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 9ec72f006..4a389bb0c 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -10,7 +10,7 @@ import Link from '@docusaurus/Link'; # POST /identity/map (v2) :::important -This documentation is for earlier versions of the `POST /identity/map` endpoint. If you're using an earlier version, we recommend upgrading. No specific migration steps are needed. For the latest version, v3, see [POST /identity/map](post-identity-map.md). +This documentation is for earlier versions of the `POST /identity/map` endpoint. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. ::: Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information. diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index a4bb7ac25..8f547fe84 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -17,7 +17,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User ## Version -This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. No specific migration steps are needed. +This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. For migration steps, see [TODO]. If needed, documentation is also available for the previous version, v2: see [POST /identity/map (v2)](post-identity-map-v2.md). @@ -53,22 +53,16 @@ The integration environment and the production environment require different
  • * At least one of these fields must be provided ### Request Examples @@ -77,12 +71,12 @@ The following are unencrypted JSON request body examples to the `POST /identity/ ```json { "email":[ - {"i": "user@example.com"}, - {"i": "user2@example.com"} + "user@example.com", + "user2@example.com" ], "phone":[ - {"i": "+12345678901"}, - {"i": "+441234567890"} + "+12345678901", + "+441234567890" ] } ``` @@ -90,12 +84,12 @@ The following are unencrypted JSON request body examples to the `POST /identity/ ```json { "email_hash":[ - {"i": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="}, - {"i": "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU="} + "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", + "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU=" ], "phone_hash":[ - {"i": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4="}, - {"i": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ="} + "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=" ] } ``` @@ -103,7 +97,7 @@ The following are unencrypted JSON request body examples to the `POST /identity/ Here's an encrypted request example to the `POST /identity/map` endpoint for a phone number: ```sh -echo '{"phone": [{"i": "+12345678901"}, {"i": "+441234567890"}]}' | python3 uid2_request.py https://prod.uidapi.com/v3/identity/map [Your-Client-API-Key] [Your-Client-Secret] +echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v3/identity/map [Your-Client-API-Key] [Your-Client-Secret] ``` For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). @@ -165,9 +159,9 @@ For successfully mapped DII, the mapped object includes the properties shown in For unsuccessfully mapped DII, the mapped object includes the properties shown in the following table. -| Property | Data Type | Description | -|:---------|:----------|:------------------------------------------------------------------| -| `e` | string | The reason for being unable to map the DII to an advertising ID. | +| Property | Data Type | Description | +|:---------|:----------|:-----------------------------------------------------------------------------------------------------------------| +| `e` | string | The reason for being unable to map the DII to an advertising ID. Either one of "optout" or "invalid identifier". | ### Response Status Codes From cd95e488469ba1c3bdcf49243653b0154385d47b Mon Sep 17 00:00:00 2001 From: sophia chen Date: Fri, 13 Jun 2025 15:01:03 +1000 Subject: [PATCH 09/28] fixed response table --- .idea/.gitignore | 8 -------- .idea/workspace.xml | 4 ++++ docs/endpoints/post-identity-map.md | 26 +++++++++++++------------- 3 files changed, 17 insertions(+), 21 deletions(-) delete mode 100644 .idea/.gitignore create mode 100644 .idea/workspace.xml 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/.idea/workspace.xml b/.idea/workspace.xml new file mode 100644 index 000000000..1ac928b92 --- /dev/null +++ b/.idea/workspace.xml @@ -0,0 +1,4 @@ + + + {} + \ No newline at end of file diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index 8f547fe84..bd4122d13 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -56,13 +56,13 @@ The integration environment and the production environment require different
  • * At least one of these fields must be provided +| Body Parameter | Data Type | Attribute | Description | +|:---------------|:----------------------------|:-----------------------| :--- | +| `email` | string array | Conditionally Required | The list of email addresses to be mapped. | +| `email_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email addresses to be mapped. | +| `phone` | string array | Conditionally Required | The list of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | +| `phone_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | + ### Request Examples @@ -141,12 +141,12 @@ Identifiers that cannot be mapped to an advertising ID are mapped to an error ob ### Response Body Properties -| Body Parameter | Data Type | Attribute | Description | -|:---------------|:----------------------------|:-----------------------|:------------------------------------------------------------------------------------------------| -| `email` | array of mapped DII objects | Conditionally Required | The list of mapped DII objects corresponding to the list of emails in the request. | -| `email_hash` | array of mapped DII objects | Conditionally Required | The list of mapped DII objects corresponding to the list of email hashes in the request. | -| `phone` | array of mapped DII objects | Conditionally Required | The list of mapped DII objects corresponding to the list of phone numbers in the request. | -| `phone_hash` | array of mapped DII objects | Conditionally Required | The list of mapped DII objects corresponding to the list of phone number hashes in the request. | +| Body Parameter | Data Type | Description | +|:---------------|:----------------------------|:------------------------------------------------------------------------------------------------| +| `email` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of emails in the request. | +| `email_hash` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of email hashes in the request. | +| `phone` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of phone numbers in the request. | +| `phone_hash` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of phone number hashes in the request. | For successfully mapped DII, the mapped object includes the properties shown in the following table. From eaf3bdf666bd00d24c13830841d69343b03ebf35 Mon Sep 17 00:00:00 2001 From: sophia chen Date: Fri, 13 Jun 2025 15:01:58 +1000 Subject: [PATCH 10/28] removing unwanted files --- .idea/workspace.xml | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 .idea/workspace.xml diff --git a/.idea/workspace.xml b/.idea/workspace.xml deleted file mode 100644 index 1ac928b92..000000000 --- a/.idea/workspace.xml +++ /dev/null @@ -1,4 +0,0 @@ - - - {} - \ No newline at end of file From fc604d31c3b0d510b5581ebe75cedb1ad04949dd Mon Sep 17 00:00:00 2001 From: sophia chen Date: Fri, 13 Jun 2025 15:28:12 +1000 Subject: [PATCH 11/28] updated version section --- docs/endpoints/post-identity-map-v2.md | 2 +- .../current/endpoints/post-identity-map-v2.md | 2 +- .../current/endpoints/post-identity-map.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md index 4a389bb0c..cb4f35c2f 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -10,7 +10,7 @@ import Link from '@docusaurus/Link'; # POST /identity/map (v2) :::important -This documentation is for earlier versions of the `POST /identity/map` endpoint. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. +This documentation is for the earlier version of the `POST /identity/map` endpoint. If you're using this earlier version, we recommend upgrading. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. ::: Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md index 99f0bcda2..635433c50 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md @@ -10,7 +10,7 @@ import Link from '@docusaurus/Link'; # POST /identity/map (v2) :::important -This documentation is for earlier versions of the `POST /identity/map` endpoint. If you're using an earlier version, we recommend upgrading. No specific migration steps are needed. For the latest version, v3, see [POST /identity/map](post-identity-map.md). +This documentation is for the earlier version of the `POST /identity/map` endpoint. If you're using this earlier version, we recommend upgrading. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. ::: 複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 と salt bucket IDs にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md index 1791dde46..e7ecc4dbf 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md @@ -19,7 +19,7 @@ UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳 ## Version -This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. No specific migration steps are needed. +This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. For migration steps, see [TODO]. If needed, documentation is also available for the previous version, v2: see [POST /identity/map (v2)](post-identity-map-v2.md). From d3a8492d89194d58c11fc75ed7fec9723e2ef925 Mon Sep 17 00:00:00 2001 From: sophia chen Date: Fri, 13 Jun 2025 15:30:58 +1000 Subject: [PATCH 12/28] small word fix --- docs/endpoints/post-identity-map-v2.md | 2 +- .../current/endpoints/post-identity-map-v2.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md index cb4f35c2f..f4efff923 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -10,7 +10,7 @@ import Link from '@docusaurus/Link'; # POST /identity/map (v2) :::important -This documentation is for the earlier version of the `POST /identity/map` endpoint. If you're using this earlier version, we recommend upgrading. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. +This documentation is for an earlier version of the `POST /identity/map` endpoint. If you're using this earlier version, we recommend upgrading. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. ::: Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md index 635433c50..287154fc8 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md @@ -10,7 +10,7 @@ import Link from '@docusaurus/Link'; # POST /identity/map (v2) :::important -This documentation is for the earlier version of the `POST /identity/map` endpoint. If you're using this earlier version, we recommend upgrading. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. +This documentation is for an earlier version of the `POST /identity/map` endpoint. If you're using this earlier version, we recommend upgrading. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. ::: 複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 と salt bucket IDs にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます From ef811bf70d88b5684ac9ba785dd72e97b211b889 Mon Sep 17 00:00:00 2001 From: sophia chen Date: Fri, 13 Jun 2025 16:36:38 +1000 Subject: [PATCH 13/28] Removed mentions of migration --- docs/endpoints/post-identity-map-v2.md | 4 ---- docs/endpoints/post-identity-map.md | 2 +- .../current/endpoints/post-identity-map-v2.md | 4 ---- .../current/endpoints/post-identity-map.md | 2 +- 4 files changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md index f4efff923..cd749d42f 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -9,10 +9,6 @@ import Link from '@docusaurus/Link'; # POST /identity/map (v2) -:::important -This documentation is for an earlier version of the `POST /identity/map` endpoint. If you're using this earlier version, we recommend upgrading. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. -::: - Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information. Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index bd4122d13..6ec389955 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -17,7 +17,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User ## Version -This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. For migration steps, see [TODO]. +This documentation is for the latest version of this endpoint. If needed, documentation is also available for the previous version, v2: see [POST /identity/map (v2)](post-identity-map-v2.md). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md index 287154fc8..f4112b91f 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md @@ -9,10 +9,6 @@ import Link from '@docusaurus/Link'; # POST /identity/map (v2) -:::important -This documentation is for an earlier version of the `POST /identity/map` endpoint. If you're using this earlier version, we recommend upgrading. For the latest version, v3, see [POST /identity/map](post-identity-map.md). For migration steps, see [TODO]. -::: - 複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 と salt bucket IDs にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) を参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md index e7ecc4dbf..be1a38247 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md @@ -19,7 +19,7 @@ UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳 ## Version -This documentation is for the latest version of this endpoint. If you're using an earlier version, we recommend that you upgrade your integration. For migration steps, see [TODO]. +This documentation is for the latest version of this endpoint. If needed, documentation is also available for the previous version, v2: see [POST /identity/map (v2)](post-identity-map-v2.md). From 9872640ab0fa30c314cc9b4c85270192da5e6def Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Thu, 19 Jun 2025 14:42:35 +1000 Subject: [PATCH 14/28] Update content and links --- docs/endpoints/post-identity-map-v2.md | 2 +- ...dentity-map.md => post-identity-map-v3.md} | 14 ++++++------- docs/endpoints/summary-endpoints.md | 20 ++++++++++++++++--- docs/getting-started/gs-credentials.md | 2 +- docs/getting-started/gs-faqs.md | 8 ++++---- docs/getting-started/gs-opt-out.md | 2 +- docs/getting-started/gs-permissions.md | 2 +- ...ation-advertiser-dataprovider-endpoints.md | 10 +++++----- ...ration-advertiser-dataprovider-overview.md | 6 +++--- docs/ref-info/updates-doc.md | 2 +- docs/sdks/summary-sdks.md | 2 +- sidebars.js | 6 +++--- 12 files changed, 45 insertions(+), 31 deletions(-) rename docs/endpoints/{post-identity-map.md => post-identity-map-v3.md} (90%) diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md index cd749d42f..9b73c97ca 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -17,7 +17,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User ## Version -This documentation is for version 2 of this endpoint. +This documentation is for earlier version 2 of this endpoint. For documentation for the latest version 3 of this endpoint, see: [POST /identity/map (v3)](post-identity-map-v3.md). ## Batch Size and Request Parallelization Requirements diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map-v3.md similarity index 90% rename from docs/endpoints/post-identity-map.md rename to docs/endpoints/post-identity-map-v3.md index 6ec389955..11fa0b939 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map-v3.md @@ -7,9 +7,9 @@ sidebar_position: 08 import Link from '@docusaurus/Link'; -# POST /identity/map +# POST /identity/map (v3) -Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when an advertising ID can be refreshed, or view the previous advertising ID if the current one is less than 90 days old. +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when a UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old. Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). @@ -110,7 +110,7 @@ The response is encrypted only if the HTTP status code is 200. Otherwise, the re A successful decrypted response returns the raw UID2s for the specified email addresses, phone numbers, or their respective hashes. The sequence in the response matches the sequence in the request. -Identifiers that cannot be mapped to an advertising ID are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the identifier is considered invalid or if the identifier has opted out from the UID2 ecosystem. In these cases, the response status is still "success". +Identifiers that cannot be mapped to a raw UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the identifier is considered invalid or if the identifier has opted out from the UID2 ecosystem. In these cases, the response status is still "success". ```json { @@ -153,15 +153,15 @@ For successfully mapped DII, the mapped object includes the properties shown in | Property | Data Type | Description | |:---------|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------| -| `u` | string | The advertising ID (raw UID2) of the DII provided in the request. | -| `p` | string | The previous advertising ID if the current ID has been refreshed in the last 90 days. `Null` if the current ID is older than 90 days. | -| `r` | number | The Unix timestamp (in milliseconds) that indicates when the advertising ID can be refreshed. | +| `u` | string | The raw UID2 of the DII provided in the request. | +| `p` | string | The previous raw UID2 if the current ID has been refreshed in the last 90 days. `Null` if the current ID is older than 90 days. | +| `r` | number | The Unix timestamp (in milliseconds) that indicates when the raw UID2 can be refreshed. | For unsuccessfully mapped DII, the mapped object includes the properties shown in the following table. | Property | Data Type | Description | |:---------|:----------|:-----------------------------------------------------------------------------------------------------------------| -| `e` | string | The reason for being unable to map the DII to an advertising ID. Either one of "optout" or "invalid identifier". | +| `e` | string | The reason for being unable to map the DII to an raw UID2. Either one of "optout" or "invalid identifier". | ### Response Status Codes diff --git a/docs/endpoints/summary-endpoints.md b/docs/endpoints/summary-endpoints.md index b9ef57d8a..4107031ed 100644 --- a/docs/endpoints/summary-endpoints.md +++ b/docs/endpoints/summary-endpoints.md @@ -22,14 +22,28 @@ The following endpoints are for retrieving and managing UID2 tokens (identity to | [POST /token/validate](post-token-validate.md) | Used for testing, to validate that an advertising token (UID2) matches the specified email address, phone number, or the respective hash. | Required | Required | | [POST /token/refresh](post-token-refresh.md) | Generates a new token for a user for their refresh token from the [POST /token/generate](post-token-generate.md) response. | N/A | Required | -## Identity Maps +## Identity Map The following endpoints are used by advertisers and third-party data providers. Publishers do not need to use these endpoints. +### Latest V3 Identity Map Endpoint + +The following endpoint is part of the latest V3 Identity Map integration. + +Calling the /identity/buckets endpoint is no longer necessary when calling the latest Identity Map endpoint. + +| Endpoint | Description | Request Encryption | Response Decryption | +| :--- | :--- | :--- | :--- | +| [POST /identity/map (v3)](post-identity-map-v3.md) | Maps UID2s, previous UID2s and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | + +### Earlier V2 Identity Map Endpoints + +The following endpoints are part of the earlier V2 Identity Map integration. + | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | | [POST /identity/buckets](post-identity-buckets.md) | Monitors rotated salt buckets using their last updated timestamp. | Required | Required | -| [POST /identity/map](post-identity-map.md) | Retrieves raw UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | +| [POST /identity/map (v2)](post-identity-map-v2.md) | Maps UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | ## Opt-Out Status @@ -39,4 +53,4 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | -| [POST /optout/status](post-optout-status.md) | Checks the opt-out status of raw UID2s. This endpoint takes a list of raw UID2s as input, and returns the raw UID2s that have opted out, as well as the time that the opt-out took place. | Required | Required | +| [POST /optout/status](post-optout-status.md) | Checks the opt-out status of UID2s. This endpoint takes a list of UID2s as input, and returns the UID2s that have opted out, as well as the time that the opt-out took place. | Required | Required | diff --git a/docs/getting-started/gs-credentials.md b/docs/getting-started/gs-credentials.md index c703d163a..327c3a436 100644 --- a/docs/getting-started/gs-credentials.md +++ b/docs/getting-started/gs-credentials.md @@ -22,7 +22,7 @@ Each UID2 environment as well as the production environment, you'll get a separate set of credentials for each environment. See [Getting Your Credentials](#getting-your-credentials). In addition, in some cases, we recommend, but do not require, that you have a different set of credentials for a different scenario. For example: -- If you're a publisher who generates UID2 tokens (via [POST /token/generate](../endpoints/post-token-generate.md) or in some other way), but you also create/map raw UID2s on your own behalf (see [POST /identity/map](../endpoints/post-identity-map.md)), you might have separate credentials for each of these activities. +- If you're a publisher who generates UID2 tokens (via [POST /token/generate](../endpoints/post-token-generate.md) or in some other way), but you also create/map raw UID2s on your own behalf (see [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md)), you might have separate credentials for each of these activities. - If you're an advertiser, in a scenario where you allow multiple service providers to operate using your advertiser keys, you might choose to have separate credentials for each service provider. ## Getting Your Credentials diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md index bb5fc5d9c..12a763197 100644 --- a/docs/getting-started/gs-faqs.md +++ b/docs/getting-started/gs-faqs.md @@ -38,7 +38,7 @@ Yes. Through the [Transparency and Control Portal](https://www.transparentadvert No. None of the components of the UID2 service store any DII. -In addition, in almost all cases, UID2 doesn't store any values at all once the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/refresh](../endpoints/post-token-refresh.md), or [POST /identity/map](../endpoints/post-identity-map.md) call is complete. A necessary exception is the case where a user has opted out. In this scenario, UID2 stores a hashed, opaque value to indicate the opted-out user. The stored value cannot be reverse engineered back to the original value of the DII, but can be used to identify future requests for a UID2 generated from the same DII, which are therefore denied. +In addition, in almost all cases, UID2 doesn't store any values at all once the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/refresh](../endpoints/post-token-refresh.md), or [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) call is complete. A necessary exception is the case where a user has opted out. In this scenario, UID2 stores a hashed, opaque value to indicate the opted-out user. The stored value cannot be reverse engineered back to the original value of the DII, but can be used to identify future requests for a UID2 generated from the same DII, which are therefore denied. #### Does UID2 allow the processing of HIPAA-regulated data? @@ -203,7 +203,7 @@ Unless you are using a salt value that's used in generating the raw UID2. The salt values are rotated roughly once per year (for details, see [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)). If the salt value changes between one request and another, those two requests result in two different raw UID2, even when the DII is the same. @@ -219,7 +219,7 @@ For more information, see [Monitor for Salt Bucket Rotations for Your Stored Raw #### If two operators process the same DII, are the results the same? -Yes, if the request is for a raw UID2. As covered in the previous FAQ, [Does the same DII always result in the same raw UID2?](#does-the-same-dii-always-result-in-the-same-raw-uid2), if an advertiser or data provider sends the same DII to the UID2 Operator, by using an SDK or the [POST /identity/map](../endpoints/post-identity-map.md) endpoint, at the same time, the same raw UID2 is created. +Yes, if the request is for a raw UID2. As covered in the previous FAQ, [Does the same DII always result in the same raw UID2?](#does-the-same-dii-always-result-in-the-same-raw-uid2), if an advertiser or data provider sends the same DII to the UID2 Operator, by using an SDK or the [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) endpoint, at the same time, the same raw UID2 is created. The result is the same, regardless of the Operator and whether it's a Private Operator or a Public Operator. diff --git a/docs/getting-started/gs-opt-out.md b/docs/getting-started/gs-opt-out.md index 8eae31ecf..1036c7724 100644 --- a/docs/getting-started/gs-opt-out.md +++ b/docs/getting-started/gs-opt-out.md @@ -49,7 +49,7 @@ The following steps provide a high-level outline of the opt-out workflow intende | :--- | :--- | | Publishers | A publisher calling [POST /token/generate](../endpoints/post-token-generate.md) with the required `optout_check` parameter set to `1`, or [POST /token/refresh](../endpoints/post-token-refresh.md), receives the opt-out response instead of the UID2 token. | | DSPs | The UID2 Operator Service distributes information on all opted-out users to DSPs via a webhook provided for the purpose. For details, see [Honor User Opt-Outs](../guides/dsp-guide#honor-user-opt-outs).
    DSPs can also check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | - | Advertisers and data providers | The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. Another option is to check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | + | Advertisers and data providers | The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) endpoint. Another option is to check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | | Sharers | UID2 sharers can check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | This workflow allows users to opt out of personalized advertising based on their UID2 through the Transparency and Control Portal. diff --git a/docs/getting-started/gs-permissions.md b/docs/getting-started/gs-permissions.md index 4a76db34e..fa3a7b843 100644 --- a/docs/getting-started/gs-permissions.md +++ b/docs/getting-started/gs-permissions.md @@ -26,4 +26,4 @@ The following table lists the key permissions, the types of participants that co | Generator | Publishers | Permission to call the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/validate](../endpoints/post-token-validate.md), and [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints, to generate UID2 tokens from DII and to refresh them, using one of these integration methods:
    • A Prebid integration
    • The SDK for JavaScript
    • An integration that directly calls the applicable API endpoints for retrieving and managing UID2 tokens.
    | | Bidder | DSPs | Permission to decrypt UID2 tokens coming in from the bidstream from publishers into raw UID2s for bidding purposes. | | Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:
    • Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake
    • Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s.
    | -| Mapper | Advertisers
    Data Providers | Permission to use the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint to monitor rotated salt buckets and to use the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. | +| Mapper | Advertisers
    Data Providers | Permission to call the [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) endpoint to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s and refresh timestamps. Permission to use the earlier V2 Identity Map [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoints as well. | diff --git a/docs/guides/integration-advertiser-dataprovider-endpoints.md b/docs/guides/integration-advertiser-dataprovider-endpoints.md index 1f523e229..358c4c593 100644 --- a/docs/guides/integration-advertiser-dataprovider-endpoints.md +++ b/docs/guides/integration-advertiser-dataprovider-endpoints.md @@ -62,8 +62,8 @@ DII refers to a user's normalized email address or phone number, or the normaliz | Step | Endpoint | Description | | --- | --- | --- | -| 1-a | [POST /identity/map](../endpoints/post-identity-map.md) request | Send a request containing DII to the identity mapping endpoint. | -| 1-b | [POST /identity/map](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.
    The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). | +| 1-a | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) request | Send a request containing DII to the identity mapping endpoint. | +| 1-b | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.
    The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). | ### 2: Store Raw UID2s and Salt Bucket IDs @@ -105,8 +105,8 @@ The following table shows the steps for checking for salt bucket rotation. | --- | --- | --- | | 5-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the `POST /identity/buckets` endpoint for all salt buckets that have changed since a specific timestamp. | | 5-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The `POST /identity/buckets` endpoint returns a list of `bucket_id` and `last_updated` timestamps. | -| 5-c | [POST /identity/map](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.
    If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the `POST /identity/map` endpoint for a new raw UID2. | -| 5-d | [POST /identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. | +| 5-c | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.
    If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the `POST /identity/map (v2)` endpoint for a new raw UID2. | +| 5-d | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) | Store the new values returned for `advertising_id` and `bucket_id`. | #### Determine whether the salt bucket has been rotated @@ -126,7 +126,7 @@ It's important to honor user opt-out status. Periodically, monitor for opt-out s There are two ways that you can check with the UID2 Operator Service to make sure you have the latest opt-out information: -- Call the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. +- Call the [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. - Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. diff --git a/docs/guides/integration-advertiser-dataprovider-overview.md b/docs/guides/integration-advertiser-dataprovider-overview.md index 651abf6f2..bc0179b04 100644 --- a/docs/guides/integration-advertiser-dataprovider-overview.md +++ b/docs/guides/integration-advertiser-dataprovider-overview.md @@ -49,7 +49,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:
    • One of these UID2 SDKs:
      • Python SDK: [Map DII to Raw UID2s](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s)
      • Java SDK: [Usage for Advertisers/Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers)
    • Snowflake: [Map DII](integration-snowflake.md#map-dii)
    • AWS Entity Resolution: [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md)
    • HTTP endpoints: [POST /identity/map](../endpoints/post-identity-map.md)
    | +| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | Use any of the following options to map DII to raw UID2s:
    • One of these UID2 SDKs:
      • Python SDK: [Map DII to Raw UID2s](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s)
      • Java SDK: [Usage for Advertisers/Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers)
    • Snowflake: [Map DII](integration-snowflake.md#map-dii)
    • AWS Entity Resolution: [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md)
    • HTTP endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md)
    | | [2: Store Raw UID2s and Salt Bucket IDs](#2-store-raw-uid2s-and-salt-bucket-ids) | 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). | @@ -85,7 +85,7 @@ To generate raw UID2s, use one of the following options: - 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). +- HTTP endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md). For details, see [Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii). ### 2: Store Raw UID2s and Salt Bucket IDs @@ -150,7 +150,7 @@ It's important to honor user opt-out status. Periodically, monitor for opt-out s There are two ways that you can check with the UID2 Operator Service to make sure you have the latest opt-out information: -- Call the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. +- Call the [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. - Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. diff --git a/docs/ref-info/updates-doc.md b/docs/ref-info/updates-doc.md index 11722f23b..db75b8548 100644 --- a/docs/ref-info/updates-doc.md +++ b/docs/ref-info/updates-doc.md @@ -422,7 +422,7 @@ For details, see [UID2 Hashing Tool](../getting-started/gs-normalization-encodin February 28, 2024 -The Java SDK now supports Advertisers and Data Providers wanting to use the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. +The Java SDK now supports Advertisers and Data Providers wanting to use the [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) endpoint. For details, see the updated documentation in the *SDK for Java Reference Guide*: [Usage for Advertisers and Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers). diff --git a/docs/sdks/summary-sdks.md b/docs/sdks/summary-sdks.md index 7a4696fd9..0bdeebc1b 100644 --- a/docs/sdks/summary-sdks.md +++ b/docs/sdks/summary-sdks.md @@ -28,7 +28,7 @@ The following table summarizes the functionality available with each SDK. |Android | Client (Mobile) | — | — | ✅ | ✅ | — | — | |iOS | Client (Mobile) | — | — | ✅| ✅ |— | — | -*Advertisers and Data Providers who need to generate raw UID2s from DII can also do this via Snowflake (see [Snowflake Integration Guide](../guides/integration-snowflake.md)) or by using the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. +*Advertisers and Data Providers who need to generate raw UID2s from DII can also do this via Snowflake (see [Snowflake Integration Guide](../guides/integration-snowflake.md)) or by using the [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) endpoint. diff --git a/sidebars.js b/sidebars.js index f053c4e74..1e180d662 100644 --- a/sidebars.js +++ b/sidebars.js @@ -322,10 +322,10 @@ const fullSidebar = [ 'endpoints/post-identity-buckets', { type: 'category', - label: 'POST /identity/map', + label: 'POST /identity/map (v3)', link: { type: 'doc', - id: 'endpoints/post-identity-map', + id: 'endpoints/post-identity-map-v3', }, collapsed: true, items: [ @@ -410,7 +410,7 @@ const sidebars = { 'guides/dsp-guide', 'endpoints/post-identity-buckets', 'POST /identity/map', - 'endpoints/post-identity-map', + 'endpoints/post-identity-map-v3', 'endpoints/post-identity-map-v2', 'endpoints/post-optout-status' ), From afa8cdf6e59f3f94edd98ea2f328dc57a506f286 Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Thu, 19 Jun 2025 14:45:07 +1000 Subject: [PATCH 15/28] Rename --- .../endpoints/{post-identity-map.md => post-identity-map-v3.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename i18n/ja/docusaurus-plugin-content-docs/current/endpoints/{post-identity-map.md => post-identity-map-v3.md} (100%) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md similarity index 100% rename from i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md rename to i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md From 6ba50adb9d3a2ebf458f90b1c17bfd71a37cc4f4 Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Thu, 19 Jun 2025 14:46:05 +1000 Subject: [PATCH 16/28] Clean up --- sidebars.js | 1 - 1 file changed, 1 deletion(-) diff --git a/sidebars.js b/sidebars.js index 1e180d662..0c04fb100 100644 --- a/sidebars.js +++ b/sidebars.js @@ -409,7 +409,6 @@ const sidebars = { 'DSP Integrations', 'guides/dsp-guide', 'endpoints/post-identity-buckets', - 'POST /identity/map', 'endpoints/post-identity-map-v3', 'endpoints/post-identity-map-v2', 'endpoints/post-optout-status' From 4ed42b29efa9e9f58f3d8bdd98ccb387fb30939f Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Thu, 19 Jun 2025 14:50:51 +1000 Subject: [PATCH 17/28] Update --- docs/endpoints/post-identity-map-v3.md | 21 ++++++++++--------- .../current/endpoints/post-identity-map-v3.md | 1 + 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/endpoints/post-identity-map-v3.md b/docs/endpoints/post-identity-map-v3.md index 11fa0b939..c28add58e 100644 --- a/docs/endpoints/post-identity-map-v3.md +++ b/docs/endpoints/post-identity-map-v3.md @@ -1,15 +1,16 @@ --- title: POST /identity/map -description: Maps DII to raw UID2s. +description: Maps DII to UID2s. hide_table_of_contents: false sidebar_position: 08 +displayed_sidebar: docs --- import Link from '@docusaurus/Link'; # POST /identity/map (v3) -Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when a UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old. +Maps multiple email addresses, phone numbers, or their respective hashes to their UID2s. You can also use this endpoint to check for updates to opt-out information, check when a UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old. Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). @@ -19,7 +20,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User This documentation is for the latest version of this endpoint. -If needed, documentation is also available for the previous version, v2: see [POST /identity/map (v2)](post-identity-map-v2.md). +If needed, documentation is also available for the earlier version 2 of this endpoint, see: [POST /identity/map (v2)](post-identity-map-v2.md). ## Batch Size and Request Parallelization Requirements @@ -28,7 +29,7 @@ Here's what you need to know: - The maximum request size is 1MB. - To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch. - Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. -- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
    Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). +- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
    Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). ## Request Format @@ -108,9 +109,9 @@ For details, and code examples in different programming languages, see [Encrypti The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted. ::: -A successful decrypted response returns the raw UID2s for the specified email addresses, phone numbers, or their respective hashes. The sequence in the response matches the sequence in the request. +A successful decrypted response returns the UID2s for the specified email addresses, phone numbers, or their respective hashes. The sequence in the response matches the sequence in the request. -Identifiers that cannot be mapped to a raw UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the identifier is considered invalid or if the identifier has opted out from the UID2 ecosystem. In these cases, the response status is still "success". +Identifiers that cannot be mapped to a UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the identifier is considered invalid or if the identifier has opted out from the UID2 ecosystem. In these cases, the response status is still "success". ```json { @@ -153,15 +154,15 @@ For successfully mapped DII, the mapped object includes the properties shown in | Property | Data Type | Description | |:---------|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------| -| `u` | string | The raw UID2 of the DII provided in the request. | -| `p` | string | The previous raw UID2 if the current ID has been refreshed in the last 90 days. `Null` if the current ID is older than 90 days. | -| `r` | number | The Unix timestamp (in milliseconds) that indicates when the raw UID2 can be refreshed. | +| `u` | string | The UID2 of the DII provided in the request. | +| `p` | string | The previous UID2 if the current UID2 has been rotated in the last 90 days. `Null` if the current UID2 is older than 90 days. | +| `r` | number | The Unix timestamp (in milliseconds) that indicates when the UID2 can be refreshed. | For unsuccessfully mapped DII, the mapped object includes the properties shown in the following table. | Property | Data Type | Description | |:---------|:----------|:-----------------------------------------------------------------------------------------------------------------| -| `e` | string | The reason for being unable to map the DII to an raw UID2. Either one of "optout" or "invalid identifier". | +| `e` | string | The reason for being unable to map the DII to a UID2. Either one of "optout" or "invalid identifier". | ### Response Status Codes diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md index be1a38247..e5f604095 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md @@ -3,6 +3,7 @@ title: POST /identity/map description: Maps DII to raw UID2s. hide_table_of_contents: false sidebar_position: 08 +displayed_sidebar: docs --- import Link from '@docusaurus/Link'; From 9801714d920347c15a20f05b22d246153d1b3da2 Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Thu, 19 Jun 2025 15:02:01 +1000 Subject: [PATCH 18/28] Update title --- docs/endpoints/post-identity-map-v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/endpoints/post-identity-map-v3.md b/docs/endpoints/post-identity-map-v3.md index c28add58e..1e960f856 100644 --- a/docs/endpoints/post-identity-map-v3.md +++ b/docs/endpoints/post-identity-map-v3.md @@ -1,5 +1,5 @@ --- -title: POST /identity/map +title: POST /identity/map (v3) description: Maps DII to UID2s. hide_table_of_contents: false sidebar_position: 08 From 7c2af7ee8e2ed42644fbae36f72d77e53dca87c6 Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Thu, 19 Jun 2025 15:19:50 +1000 Subject: [PATCH 19/28] Clarity --- docs/endpoints/post-identity-map-v3.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/endpoints/post-identity-map-v3.md b/docs/endpoints/post-identity-map-v3.md index 1e960f856..ddab802ab 100644 --- a/docs/endpoints/post-identity-map-v3.md +++ b/docs/endpoints/post-identity-map-v3.md @@ -109,9 +109,11 @@ For details, and code examples in different programming languages, see [Encrypti The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted. ::: -A successful decrypted response returns the UID2s for the specified email addresses, phone numbers, or their respective hashes. The sequence in the response matches the sequence in the request. +A successful decrypted response returns the current UID2s, previous UID2s (where applicable) and refresh timestamps for the specified email addresses, phone numbers, or their respective hashes. -Identifiers that cannot be mapped to a UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the identifier is considered invalid or if the identifier has opted out from the UID2 ecosystem. In these cases, the response status is still "success". +The response arrays preserve the order of input arrays. Each element in the response array maps directly to the element at the same index in the corresponding request array. This ensures that results can be reliably associated with their corresponding inputs based on array position. + +DIIs that cannot be mapped to a UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the DII is considered invalid or if the DII has opted out from the UID2 ecosystem. In these cases, the response status is still "success". ```json { From 774cbcdeafa1b3074ac5e606ae1749b7972430aa Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Fri, 20 Jun 2025 13:01:30 +1000 Subject: [PATCH 20/28] Update Japanese translation links --- .../current/endpoints/post-identity-map-v3.md | 202 +----------------- .../current/endpoints/summary-endpoints.md | 2 +- .../current/getting-started/gs-credentials.md | 2 +- .../current/getting-started/gs-faqs.md | 8 +- .../current/getting-started/gs-opt-out.md | 2 +- .../current/getting-started/gs-permissions.md | 2 +- ...ation-advertiser-dataprovider-endpoints.md | 10 +- ...ration-advertiser-dataprovider-overview.md | 6 +- .../current/ref-info/updates-doc.md | 2 +- .../current/sdks/summary-sdks.md | 2 +- .../sharing/sharing-tokenized-overview.md | 2 +- 11 files changed, 21 insertions(+), 219 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md index e5f604095..6bcf50f14 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md @@ -1,6 +1,6 @@ --- -title: POST /identity/map -description: Maps DII to raw UID2s. +title: POST /identity/map (v3) +description: Maps DII to UID2s. hide_table_of_contents: false sidebar_position: 08 displayed_sidebar: docs @@ -8,201 +8,3 @@ displayed_sidebar: docs import Link from '@docusaurus/Link'; -# POST /identity/map - -[**TO BE UPDATED. VERSION SECTION ADDED BUT THE REST NEEDS UPDATING**] - -複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 と salt bucket IDs にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます - -Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) を参照してください。 - -UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳細は、[User Opt-Out](../getting-started/gs-opt-out.md) を参照してください。 - -## Version - -This documentation is for the latest version of this endpoint. - -If needed, documentation is also available for the previous version, v2: see [POST /identity/map (v2)](post-identity-map-v2.md). - -## Batch Size and Request Parallelization Requirements - -知っておくべきことは以下のとおりです: - -- リクエストの最大サイズは 1MB です。 -- 大量のメールアドレス、電話番号、またはそれぞれのハッシュをマップするには、1 バッチあたり最大 5,000 アイテムのバッチサイズで、それらを *連続した* バッチで送信してください。 -- Private Operator を使用している場合を除き、バッチを並行して送信しないでください。つまり、単一の HTTP 接続を使用して、[directly identifying information (DII)](../ref-info/glossary-uid.md#gl-dii) を連続してマッピングしてください。 -- メールアドレス、電話番号、またはそれぞれのハッシュのマッピングを必ず保存してください。
    マッピングを保存しないと、数百万のメールアドレスや電話番号をマッピングする必要がある場合に、処理時間が大幅に増加する可能性があります。しかし、実際に更新が必要なマッピングのみを再計算することで、毎日更新が必要な raw UID2 の数は約 1/365 となり、総処理時間を短縮できます。[Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) と [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers) も参照してください。 - -## Request Format - -`POST '{environment}/v2/identity/map'` - -認証の詳細は、 [Authentication and Authorization](../getting-started/gs-auth.md) を参照してください。 - -:::important -すべてのリクエストを秘密鍵で暗号化する必要があります。詳細といくつかのプログラミング言語でのコードの例は、[リクエストの暗号化とレスポンスの復号化](../getting-started/gs-encryption-decryption.md) を参照してください。 -::: - -### Path Parameters - -| Path Parameter | Data Type | Attribute | Description | -| :--- | :--- | :--- | :--- | -| `{environment}` | string | 必須 | テスト (インテグレーション) 環境: `https://operator-integ.uidapi.com`
    本番環境: `https://prod.uidapi.com`
    リージョンごとのオペレーターを含む全リストは [Environments](../getting-started/gs-environments.md) を参照してください。 | - -:::note -インテグレーション環境と本番環境では、異なる API Key が必要です。各環境の認証情報を取得する方法については、[Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials) を参照してください。 -::: - -### Unencrypted JSON Body Parameters - -:::important -リクエストを暗号化するときは、以下の 4 つの条件パラメータのうち、**1つ** だけをリクエストの JSON ボディにキーと値のペアとして含める必要がります。 -::: - -| Body Parameter | Data Type | Attribute | Description | -| :--- | :--- | :--- | :--- | -| `email` | string array | 条件付きで必要 | マッピングするメールアドレスのリストです。 | -| `email_hash` | string array | 条件付きで必要 | マッピングする [SHA-256 ハッシュし、Base64 エンコード](../getting-started/gs-normalization-encoding.md#email-address-normalization) した [正規化](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) 済みメールアドレスのリストです。 | -| `phone` | string array | 条件付きで必要 | マッピングする [正規化](../getting-started/gs-normalization-encoding.md#phone-number-normalization) 済み電話番号のリストです。 | -| `phone_hash` | string array | 条件付きで必要 | マッピングする [SHA-256 ハッシュし、Base64 エンコード](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) した [正規化](../getting-started/gs-normalization-encoding.md#phone-number-normalization) 済み電話番号のリストです。 | - -### Request Examples - -以下は、各パラメータの暗号化されていない JSON リクエストボディの例です。このうちの 1 つを、`POST /identity/map` エンドポイントへのリクエストに含める必要があります: - -```json -{ - "email": [ - "user@example.com", - "user2@example.com" - ] -} -``` -```json -{ - "email_hash": [ - "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", - "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU=" - ] -} -``` -```json -{ - "phone": [ - "+12345678901", - "+441234567890" - ] -} -``` -```json -{ - "phone_hash": [ - "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=" - ] -} -``` - -以下は、電話番号に対する `POST /identity/map` エンドポイントへの暗号化リクエストの例です: - -```sh -echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret] -``` - -詳細といくつかのプログラミング言語でのコードの例は、[リクエストの暗号化とレスポンスの復号化](../getting-started/gs-encryption-decryption.md) を参照してください。 - -## Decrypted JSON Response Format - -:::note -レスポンスは、HTTP ステータスコードが 200 の場合のみ暗号化されます。それ以外の場合、レスポンスは暗号化されません。 -::: - -復号化に成功すると、指定したメールアドレス、電話番号、またはそれぞれのハッシュに対する raw UID2 とソルトバケット ID が返されます。 - -```json -{ - "body": { - "mapped": [ - { - "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "a30od4mNRd" - }, - { - "identifier": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=", - "advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=", - "bucket_id": "ad1ANEmVZ" - } - ] - }, - "status": "success" -} -``` - -一部の識別子が無効と判断された場合、それらの識別子は "unmapped" リストとしてレスポンスに含まれる。この場合でも、レスポンスステータスは "success" となります。すべての識別子がマッピングされた場合、"unmapped"リストはレスポンスに含まれません。 - -```json -{ - "body": { - "mapped": [ - { - "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "a30od4mNRd" - } - ], - "unmapped": [ - { - "identifier": "some@malformed@email@hash", - "reason": "invalid identifier" - } - ] - }, - "status": "success" -} -``` - -一部の識別子が UID2 エコシステムからオプトアウトしている場合、オプトアウトした識別子は、見つかった無効な識別子とともに "unmapped" リストに移動されます。この場合でも、レスポンスステータスは "success" です。 - -```json -{ - "body": { - "mapped": [ - { - "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "a30od4mNRd" - } - ], - "unmapped": [ - { - "identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", - "reason": "optout" - } - ] - }, - "status": "success" -} -``` - -### Response Body Properties - -レスポンスボディには、次の表に示すプロパティが含まれます。 - -| Property | Data Type | Description | -| :--- | :--- | :--- | -| `identifier` | string | リクエストボディで指定されたメールアドレス、電話番号、またはそれぞれのハッシュです。 | -| `advertising_id` | string | 対応する Advertising ID (raw UID2) です。 | -| `bucket_id` | string | raw UID2 の生成に使用したソルトバケットの ID です。 | - -### Response Status Codes - -次の表は、`status` プロパティの値と、それに対応する HTTP ステータスコードの一覧です。 - -| Status | HTTP Status Code | Description | -| :--- | :--- | :--- | -| `success` | 200 | リクエストは成功しました。レスポンスは暗号化されています。 | -| `client_error` | 400 | リクエストに不足している、または無効なパラメータがありました。 | -| `unauthorized` | 401 | クエストにベアラートークンが含まれていない、無効なベアラートークンが含まれている、またはリクエストされた操作を実行するのに許可されていないベアラートークンが含まれていた。 | - -`status` の値が `success` 以外であれば、`message` フィールドにその問題に関する追加情報が表示されます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/summary-endpoints.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/summary-endpoints.md index 19fe3a91e..ed0a6ed96 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/summary-endpoints.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/summary-endpoints.md @@ -29,7 +29,7 @@ import Link from '@docusaurus/Link'; | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | | [POST /identity/buckets](post-identity-buckets.md) | 最後に更新されたタイムスタンプを使用して、ローテーションされたソルトバケットを監視します。 | 必須 | 必須 | -| [POST /identity/map](post-identity-map.md) | 1 つ以上のメールアドレス、電話番号、またはそれぞれのハッシュの UID2 とソルトバケット ID を取得します。 | 必須 | 必須 | +| [POST /identity/map (v2)](post-identity-map-v2.md) | 1 つ以上のメールアドレス、電話番号、またはそれぞれのハッシュの UID2 とソルトバケット ID を取得します。 | 必須 | 必須 | ## Opt-Out Status diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md index d7f2abcb0..3d31f16ec 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md @@ -22,7 +22,7 @@ UID2 の     環境 と本番環境の両方を使用している場合、それぞれの環境用に別々の認証情報が提供されます。詳細は [Getting Your Credentials](#getting-your-credentials) を参照してください。 さらに、いくつかのケースでは、異なるシナリオに対して異なるセットの認証情報を持つことを勧めますが、必須ではありません。たとえば: -- UID2 Token を生成する Publisher である場合([POST /token/generate](../endpoints/post-token-generate.md) または他の方法で)、または自分のために UID2 を生成/マッピングする場合([POST /identity/map](../endpoints/post-identity-map.md) を参照)、それぞれの活動に対して異なる認証情報を持つことがあります。 +- UID2 Token を生成する Publisher である場合([POST /token/generate](../endpoints/post-token-generate.md) または他の方法で)、または自分のために UID2 を生成/マッピングする場合([POST /identity/map (v2)](post-identity-map-v2.md) を参照)、それぞれの活動に対して異なる認証情報を持つことがあります。 - 広告主の場合、広告主キーを使用して複数のサービスプロバイダが運用するシナリオで、各サービスプロバイダに対して異なる認証情報割り当てることができます。 ## Getting Your Credentials diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md index 4b69a93f4..59be23c9b 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md @@ -41,7 +41,7 @@ UID2 に DII を送信すると、UID2 はその情報を保存しますか？ いいえ。UID2 service のコンポーネントは、DII を保存しません。 -さらに、ほとんどの場合、UID2 は、[POST /token/generate](../endpoints/post-token-generate.md)、[POST /token/refresh](../endpoints/post-token-refresh.md)、または [POST /identity/map](../endpoints/post-identity-map.md) の呼び出しが完了すると、値を全く保存しません。必要な例外は、ユーザーがオプトアウトした場合です。この場合、UID2 は、オプトアウトしたユーザーを示すハッシュ化された不透明な値を保存します。保存された値は、DII から生成された同じ UID2 に関する将来のリクエストを識別するために使用され、そのため拒否されます。 +さらに、ほとんどの場合、UID2 は、[POST /token/generate](../endpoints/post-token-generate.md)、[POST /token/refresh](../endpoints/post-token-refresh.md)、または [POST /identity/map (v2)](post-identity-map-v2.md).md) の呼び出しが完了すると、値を全く保存しません。必要な例外は、ユーザーがオプトアウトした場合です。この場合、UID2 は、オプトアウトしたユーザーを示すハッシュ化された不透明な値を保存します。保存された値は、DII から生成された同じ UID2 に関する将来のリクエストを識別するために使用され、そのため拒否されます。 #### Does UID2 allow the processing of HIPAA-regulated data? UID2 は HIPAA で規制されているデータの処理を許可しますか？ @@ -222,7 +222,7 @@ UID2 生成リクエストで提供されるメタデータには、UID2 の生 #### How should I handle user opt-outs? ユーザーのオプトアウトはどのように処理すればよいですか？ -ユーザーが [Transparency and Control Portal](https://www.transparentadvertising.com/) を通じて UID2 ベースのターゲティング広告をオプトアウトすると、オプトアウト信号が DSP とパブリッシャーに送信され、DSP とパブリッシャーが入札時にオプトアウトを処理します。広告主やデータプロバイダーは、[POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを通じて、ユーザーがオプトアウトしたかどうかを定期的に確認することを勧めます。 +ユーザーが [Transparency and Control Portal](https://www.transparentadvertising.com/) を通じて UID2 ベースのターゲティング広告をオプトアウトすると、オプトアウト信号が DSP とパブリッシャーに送信され、DSP とパブリッシャーが入札時にオプトアウトを処理します。広告主やデータプロバイダーは、[POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを通じて、ユーザーがオプトアウトしたかどうかを定期的に確認することを勧めます。 広告主やデータプロバイダーは、raw UID2 に対するオプトアウトステータスを確認するために、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用することもできます。 @@ -231,7 +231,7 @@ UID2 生成リクエストで提供されるメタデータには、UID2 の生 #### Does the same DII always result in the same raw UID2? 同じ DII は常に同じ raw UID2 になりますか？ -一般的にその通りです。DII から raw UID2 を生成するプロセスは同じであり、誰がリクエストを送信したかに関係なく、結果は同じ値になります。 2 人の UID2 参加者が同じメールアドレスを [POST /identity/map](../endpoints/post-identity-map.md) エンドポイントに同時に送信した場合、応答として両方とも同じ raw UID2 を取得します。 +一般的にその通りです。DII から raw UID2 を生成するプロセスは同じであり、誰がリクエストを送信したかに関係なく、結果は同じ値になります。 2 人の UID2 参加者が同じメールアドレスを [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントに同時に送信した場合、応答として両方とも同じ raw UID2 を取得します。 ただし、raw UID2 の生成に使用される秘密の [ソルト](../ref-info/glossary-uid.md#gl-salt) 値という可変要素があります。ソルト値は定期的にローテーションされます(詳細は [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)) を参照)。あるリクエストと別のリクエストの間でソルト値が変化する場合、DII が同じであっても、これら 2 つのリクエストは 2 つの異なる raw UID2 になります。 @@ -240,7 +240,7 @@ UID2 生成リクエストで提供されるメタデータには、UID2 の生 #### If two operators process the same DII, are the results the same? 2 つの Operator が同じ DII を処理した場合、結果は同じになりますか？ -はい、リクエストが raw UID2 に対するものである場合は、同じです。前の FAQ で説明したように、[同じ DII は常に同じ raw UID2 になりますか？](#does-the-same-dii-always-result-in-the-same-raw-uid2)、広告主やデータプロバイダーが同時に同じ DII を UID2 Operator に送信する場合、SDK または [POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを使用して、同じ raw UID2 が生成されます。 +はい、リクエストが raw UID2 に対するものである場合は、同じです。前の FAQ で説明したように、[同じ DII は常に同じ raw UID2 になりますか？](#does-the-same-dii-always-result-in-the-same-raw-uid2)、広告主やデータプロバイダーが同時に同じ DII を UID2 Operator に送信する場合、SDK または [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを使用して、同じ raw UID2 が生成されます。 Operator に関係なく、また、Private Operator と Public Operator のどちらであっても、結果は同じです。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-opt-out.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-opt-out.md index 2cdb4e4a3..a97fa92f5 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-opt-out.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-opt-out.md @@ -49,7 +49,7 @@ UID2 エコシステムには、2 種類のオプトアウトがあります: | :--- | :--- | | Publishers | [POST /token/generate](../endpoints/post-token-generate.md) を必須パラメータ `optout_check` を `1` に設定して呼び出したパブリッシャー、または [POST /token/refresh](../endpoints/post-token-refresh.md) を呼び出したパブリッシャーは、UID2 Token の代わりにオプトアウトレスポンスを受け取ります。| | DSPs | UID2 Operator Service は、DSP に対して、その目的のために提供された Webhook を介して、オプトアウトしたすべてのユーザーの情報を配布します。詳細は [Honor User Opt-Outs](../guides/dsp-guide#honor-user-opt-outs) を参照してください。
    DSP は、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認することもできます。 | - | 広告主とデータプロバイダー | UID2 Operator Service は、[POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを介して、広告主とデータプロバイダーにオプトアウト情報を配布します。別のオプションとして、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認することもできます。 | + | 広告主とデータプロバイダー | UID2 Operator Service は、[POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを介して、広告主とデータプロバイダーにオプトアウト情報を配布します。別のオプションとして、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認することもできます。 | | Sharers | UID2 Sharer は、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認することができます。 | このワークフローにより、ユーザーは Transparency and Control Portal を通じて、UID2 に基づくパーソナライズ広告をオプトアウトすることができます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-permissions.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-permissions.md index 441683055..530ffc84f 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-permissions.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-permissions.md @@ -26,4 +26,4 @@ UID2 エコシステムには、特定のアクティビティを完了するた | Generator | Publishers | Permission to call the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/validate](../endpoints/post-token-validate.md), and [POST /token/refresh](../endpoints/post-token-refresh.md) の各エンドポイントを呼び出して、DII から UID2 Token を生成/リフレッシュする権限:
    • Prebid インテグレーション
    • The SDK for JavaScript
    • UID2 Token の取得と管理のために、該当する API エンドポイントを直接呼び出すインテグレーション
    | | Bidder | DSPs | パブリッシャーからのビッドストリームから送られてくる UID2 Token を、入札目的で raw UID2 に復号化する権限。 | | Sharer | UID2 sharing に参加するすべての参加者タイプ。詳細は [UID2 Sharing: Overview](../sharing/sharing-overview.md) を参照してください。 | 以下両方の権限:
    • UID2 SDK または S nowflake を使用して、raw UID2 を UID2 Token に暗号化し、許可された別の共有参加者と共有します。
    • 他の許可された共有参加者から受け取った UID2 Token を raw UID2 に復号します。
    | -| Mapper | Advertisers
    Data Providers | [POST /identity/buckets](../endpoints/post-identity-buckets.md) エンドポイントを使用して、ローテーションされたソルトバケットをモニターし、[POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを使用して、複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 とソルトバケット ID にマッピングする権限。 | +| Mapper | Advertisers
    Data Providers | [POST /identity/buckets](../endpoints/post-identity-buckets.md) エンドポイントを使用して、ローテーションされたソルトバケットをモニターし、[POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを使用して、複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 とソルトバケット ID にマッピングする権限。 | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md index e6c96ebff..463f1f8cc 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md @@ -62,8 +62,8 @@ DII は、ユーザーの正規化されたメールアドレスまたは電話 | Step | Endpoint | Description | | --- | --- | --- | -| 1-a | [POST /identity/map](../endpoints/post-identity-map.md) request | DII を含むリクエストを ID マッピングエンドポイントに送信します。 | -| 1-b | [POST /identity/map](../endpoints/post-identity-map.md) response | レスポンスで返される `advertising_id` (raw UID2) は、関連する DSP でオーディエンスをターゲットするために使用できます。
    レスポンスは、ユーザーの raw UID2 と、それに対応するソルトバケットの `bucket_id` を返します。バケットに割り当てられたソルトは年に一度ローテーションし、生成された raw UID2 に影響を与えます。ソルトバケットのローテーションを確認する方法の詳細は、[5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s) を参照してください。 | +| 1-a | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) request | DII を含むリクエストを ID マッピングエンドポイントに送信します。 | +| 1-b | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) response | レスポンスで返される `advertising_id` (raw UID2) は、関連する DSP でオーディエンスをターゲットするために使用できます。
    レスポンスは、ユーザーの raw UID2 と、それに対応するソルトバケットの `bucket_id` を返します。バケットに割り当てられたソルトは年に一度ローテーションし、生成された raw UID2 に影響を与えます。ソルトバケットのローテーションを確認する方法の詳細は、[5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s) を参照してください。 | ### 2: Store Raw UID2s and Salt Bucket IDs @@ -105,8 +105,8 @@ raw UID2 は、特定の時点におけるユーザーの識別子です。raw U | --- | --- | --- | | 5-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | 特定のタイムスタンプ以降に変更されたすべてのソルトバケットに対して、`POST /identity/buckets` エンドポイントにリクエストを送信します。 | | 5-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 Service: `POST /identity/buckets` エンドポイントは、`bucket_id` と `last_updated` タイムスタンプのリストを返します。 | -| 5-c | [POST /identity/map](../endpoints/post-identity-map.md) | 返された `bucket_id` をキャッシュした raw UID2 のソルトバケットと比較します。
    1 つ以上の raw UID2 のソルトバケットが更新された場合は、新しい raw UID2 用に DII を `POST /identity/map` エンドポイントに再送信します。 | -| 5-d | [POST /identity/map](../endpoints/post-identity-map.md) | `advertising_id` と `bucket_id` の新しい値を保存します。 | +| 5-c | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) | 返された `bucket_id` をキャッシュした raw UID2 のソルトバケットと比較します。
    1 つ以上の raw UID2 のソルトバケットが更新された場合は、新しい raw UID2 用に DII を `POST /identity/map` エンドポイントに再送信します。 | +| 5-d | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) | `advertising_id` と `bucket_id` の新しい値を保存します。 | #### Determine whether the salt bucket has been rotated @@ -126,7 +126,7 @@ raw UID2 は、特定の時点におけるユーザーの識別子です。raw U UID2 Operator Service に最新のオプトアウト情報があるかを確認する方法は 2 つあります: -- [POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを呼び出してオプトアウトを確認します。DII がオプトアウトされている場合、raw UID2 は生成されません。 +- [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを呼び出してオプトアウトを確認します。DII がオプトアウトされている場合、raw UID2 は生成されません。 - [POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md index b4f992e2a..7f77c2694 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md @@ -49,7 +49,7 @@ import Link from '@docusaurus/Link'; | High-Level Step | Implementation Options | | --- | --- | -| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | DII を raw UID2 にマッピングするには、以下のオプションのいずれかをします:
    • 以下の UID2 SDK のいずれか:
      • Python SDK: [DII を Raw UID2 にマッピング](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s)
      • Java SDK: [広告主/データプロバイダー向けの使用法](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers)
    • Snowflake: [DII をマッピング](integration-snowflake.md#map-dii)
    • AWS Entity Resolution: [AWS Entity Resolution インテグレーションガイド](integration-aws-entity-resolution.md)
    • HTTP エンドポイント: [POST /identity/map](../endpoints/post-identity-map.md)
    | +| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | DII を raw UID2 にマッピングするには、以下のオプションのいずれかをします:
    • 以下の UID2 SDK のいずれか:
      • Python SDK: [DII を Raw UID2 にマッピング](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s)
      • Java SDK: [広告主/データプロバイダー向けの使用法](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers)
    • Snowflake: [DII をマッピング](integration-snowflake.md#map-dii)
    • AWS Entity Resolution: [AWS Entity Resolution インテグレーションガイド](integration-aws-entity-resolution.md)
    • HTTP エンドポイント: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md)
    | | [2: Store Raw UID2s and Salt Bucket IDs](#2-store-raw-uid2s-and-salt-bucket-ids) | カスタム（適切な方法で）。 | | [3: Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s) | カスタム（適切な方法で）。 | | [4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) | カスタム（適切な方法で）。 | @@ -85,7 +85,7 @@ raw UID2 を生成するには、以下のオプションのいずれかを使 - AWS Entity Resolution: [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) を参照してください。 -- HTTP endpoints: [POST /identity/map](../endpoints/post-identity-map.md). 詳細は、[Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii) を参照してください。 +- HTTP endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md). 詳細は、[Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii) を参照してください。 ### 2: Store Raw UID2s and Salt Bucket IDs @@ -150,7 +150,7 @@ AWS Entity Resolution では、ソルトバケットの監視方法はありま UID2 Operator Service で最新のオプトアウト情報があるかを確認する方法は 2 つあります: -- [POST /identity/map](../endpoints/post-identity-map.md) エンドポイイントを使用して、raw UID2 のオプトアウトステータスを確認します。オプトアウトされた DII には、raw UID2 は生成されません。 +- [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイイントを使用して、raw UID2 のオプトアウトステータスを確認します。オプトアウトされた DII には、raw UID2 は生成されません。 - [POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/updates-doc.md b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/updates-doc.md index 96dd9fb5a..3a28ddfe3 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/updates-doc.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/updates-doc.md @@ -422,7 +422,7 @@ March 4, 2024 February 28, 2024 -Java SDKは、[POST /identity/map](../endpoints/post-identity-map.md) エンドポイントの使用を希望する広告主およびデータプロバイダーをサポートするようになりました。 +Java SDKは、[POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントの使用を希望する広告主およびデータプロバイダーをサポートするようになりました。 詳細は、*SDK for Javaリファレンスガイド*: [Usage for Advertisers and Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers) の更新されたドキュメントを参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/summary-sdks.md b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/summary-sdks.md index 6dbc97fed..b5de39bd0 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/summary-sdks.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/summary-sdks.md @@ -28,7 +28,7 @@ SDK の機能を確認して使用する SDK を決定し、SDK の表をクリ |Android | Client (Mobile) | — | — | ✅ | ✅ | — | — | |iOS | Client (Mobile) | — | — | ✅| ✅ |— | — | -*DII から raw UID2 を生成する必要がある広告主およびデータプロバイダは Snowflake ([Snowflake Integration Guide](../guides/integration-snowflake.md) を参照) または [POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを使用することができます。 +*DII から raw UID2 を生成する必要がある広告主およびデータプロバイダは Snowflake ([Snowflake Integration Guide](../guides/integration-snowflake.md) を参照) または [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを使用することができます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sharing/sharing-tokenized-overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/sharing/sharing-tokenized-overview.md index 20d6d7794..df684427d 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/sharing/sharing-tokenized-overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sharing/sharing-tokenized-overview.md @@ -165,7 +165,7 @@ raw UID2 から始める場合は、次の手順に従ってください: 1 user@example.com -メールアドレス/電話番号を raw UID2 に変換する:
    POST /identity/map endpoint +メールアドレス/電話番号を raw UID2 に変換する:
    POST /identity/map (v2) endpoint K2jlbu2ldlpKL1z6n5bET7L3
    g0xfqmldZPDdPTktdRQ= From 18af9b132a1d6e96c5fe48b69e66ffe1726b6df5 Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Fri, 20 Jun 2025 13:20:19 +1000 Subject: [PATCH 21/28] Revert (v3) --- docs/endpoints/post-identity-map-v2.md | 2 +- .../{post-identity-map-v3.md => post-identity-map.md} | 4 ++-- docs/endpoints/summary-endpoints.md | 2 +- docs/getting-started/gs-credentials.md | 2 +- docs/getting-started/gs-faqs.md | 8 ++++---- docs/getting-started/gs-opt-out.md | 2 +- docs/getting-started/gs-permissions.md | 2 +- docs/sdks/summary-sdks.md | 2 +- .../{post-identity-map-v3.md => post-identity-map.md} | 2 +- sidebars.js | 6 +++--- 10 files changed, 16 insertions(+), 16 deletions(-) rename docs/endpoints/{post-identity-map-v3.md => post-identity-map.md} (99%) rename i18n/ja/docusaurus-plugin-content-docs/current/endpoints/{post-identity-map-v3.md => post-identity-map.md} (83%) diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md index 9b73c97ca..53674fe68 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -17,7 +17,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User ## Version -This documentation is for earlier version 2 of this endpoint. For documentation for the latest version 3 of this endpoint, see: [POST /identity/map (v3)](post-identity-map-v3.md). +This documentation is for earlier version 2 of this endpoint. For documentation for the latest version 3 of this endpoint, see: [POST /identity/map](post-identity-map.md). ## Batch Size and Request Parallelization Requirements diff --git a/docs/endpoints/post-identity-map-v3.md b/docs/endpoints/post-identity-map.md similarity index 99% rename from docs/endpoints/post-identity-map-v3.md rename to docs/endpoints/post-identity-map.md index ddab802ab..c1dfd1eb7 100644 --- a/docs/endpoints/post-identity-map-v3.md +++ b/docs/endpoints/post-identity-map.md @@ -1,5 +1,5 @@ --- -title: POST /identity/map (v3) +title: POST /identity/map description: Maps DII to UID2s. hide_table_of_contents: false sidebar_position: 08 @@ -8,7 +8,7 @@ displayed_sidebar: docs import Link from '@docusaurus/Link'; -# POST /identity/map (v3) +# POST /identity/map Maps multiple email addresses, phone numbers, or their respective hashes to their UID2s. You can also use this endpoint to check for updates to opt-out information, check when a UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old. diff --git a/docs/endpoints/summary-endpoints.md b/docs/endpoints/summary-endpoints.md index 4107031ed..d012b29de 100644 --- a/docs/endpoints/summary-endpoints.md +++ b/docs/endpoints/summary-endpoints.md @@ -34,7 +34,7 @@ Calling the /identity/buckets endpoint is no longer necessary when calling the l | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | -| [POST /identity/map (v3)](post-identity-map-v3.md) | Maps UID2s, previous UID2s and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | +| [POST /identity/map](post-identity-map.md) | Maps UID2s, previous UID2s and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | ### Earlier V2 Identity Map Endpoints diff --git a/docs/getting-started/gs-credentials.md b/docs/getting-started/gs-credentials.md index 327c3a436..d6e8949aa 100644 --- a/docs/getting-started/gs-credentials.md +++ b/docs/getting-started/gs-credentials.md @@ -22,7 +22,7 @@ Each UID2 environment as well as the production environment, you'll get a separate set of credentials for each environment. See [Getting Your Credentials](#getting-your-credentials). In addition, in some cases, we recommend, but do not require, that you have a different set of credentials for a different scenario. For example: -- If you're a publisher who generates UID2 tokens (via [POST /token/generate](../endpoints/post-token-generate.md) or in some other way), but you also create/map raw UID2s on your own behalf (see [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md)), you might have separate credentials for each of these activities. +- If you're a publisher who generates UID2 tokens (via [POST /token/generate](../endpoints/post-token-generate.md) or in some other way), but you also create/map raw UID2s on your own behalf (see [POST /identity/map)](../endpoints/post-identity-map.md)), you might have separate credentials for each of these activities. - If you're an advertiser, in a scenario where you allow multiple service providers to operate using your advertiser keys, you might choose to have separate credentials for each service provider. ## Getting Your Credentials diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md index 12a763197..bb5fc5d9c 100644 --- a/docs/getting-started/gs-faqs.md +++ b/docs/getting-started/gs-faqs.md @@ -38,7 +38,7 @@ Yes. Through the [Transparency and Control Portal](https://www.transparentadvert No. None of the components of the UID2 service store any DII. -In addition, in almost all cases, UID2 doesn't store any values at all once the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/refresh](../endpoints/post-token-refresh.md), or [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) call is complete. A necessary exception is the case where a user has opted out. In this scenario, UID2 stores a hashed, opaque value to indicate the opted-out user. The stored value cannot be reverse engineered back to the original value of the DII, but can be used to identify future requests for a UID2 generated from the same DII, which are therefore denied. +In addition, in almost all cases, UID2 doesn't store any values at all once the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/refresh](../endpoints/post-token-refresh.md), or [POST /identity/map](../endpoints/post-identity-map.md) call is complete. A necessary exception is the case where a user has opted out. In this scenario, UID2 stores a hashed, opaque value to indicate the opted-out user. The stored value cannot be reverse engineered back to the original value of the DII, but can be used to identify future requests for a UID2 generated from the same DII, which are therefore denied. #### Does UID2 allow the processing of HIPAA-regulated data? @@ -203,7 +203,7 @@ Unless you are using a salt value that's used in generating the raw UID2. The salt values are rotated roughly once per year (for details, see [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)). If the salt value changes between one request and another, those two requests result in two different raw UID2, even when the DII is the same. @@ -219,7 +219,7 @@ For more information, see [Monitor for Salt Bucket Rotations for Your Stored Raw #### If two operators process the same DII, are the results the same? -Yes, if the request is for a raw UID2. As covered in the previous FAQ, [Does the same DII always result in the same raw UID2?](#does-the-same-dii-always-result-in-the-same-raw-uid2), if an advertiser or data provider sends the same DII to the UID2 Operator, by using an SDK or the [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) endpoint, at the same time, the same raw UID2 is created. +Yes, if the request is for a raw UID2. As covered in the previous FAQ, [Does the same DII always result in the same raw UID2?](#does-the-same-dii-always-result-in-the-same-raw-uid2), if an advertiser or data provider sends the same DII to the UID2 Operator, by using an SDK or the [POST /identity/map](../endpoints/post-identity-map.md) endpoint, at the same time, the same raw UID2 is created. The result is the same, regardless of the Operator and whether it's a Private Operator or a Public Operator. diff --git a/docs/getting-started/gs-opt-out.md b/docs/getting-started/gs-opt-out.md index 1036c7724..8eae31ecf 100644 --- a/docs/getting-started/gs-opt-out.md +++ b/docs/getting-started/gs-opt-out.md @@ -49,7 +49,7 @@ The following steps provide a high-level outline of the opt-out workflow intende | :--- | :--- | | Publishers | A publisher calling [POST /token/generate](../endpoints/post-token-generate.md) with the required `optout_check` parameter set to `1`, or [POST /token/refresh](../endpoints/post-token-refresh.md), receives the opt-out response instead of the UID2 token. | | DSPs | The UID2 Operator Service distributes information on all opted-out users to DSPs via a webhook provided for the purpose. For details, see [Honor User Opt-Outs](../guides/dsp-guide#honor-user-opt-outs).
    DSPs can also check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | - | Advertisers and data providers | The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) endpoint. Another option is to check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | + | Advertisers and data providers | The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. Another option is to check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | | Sharers | UID2 sharers can check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | This workflow allows users to opt out of personalized advertising based on their UID2 through the Transparency and Control Portal. diff --git a/docs/getting-started/gs-permissions.md b/docs/getting-started/gs-permissions.md index fa3a7b843..c55faa312 100644 --- a/docs/getting-started/gs-permissions.md +++ b/docs/getting-started/gs-permissions.md @@ -26,4 +26,4 @@ The following table lists the key permissions, the types of participants that co | Generator | Publishers | Permission to call the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/validate](../endpoints/post-token-validate.md), and [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints, to generate UID2 tokens from DII and to refresh them, using one of these integration methods:
    • A Prebid integration
    • The SDK for JavaScript
    • An integration that directly calls the applicable API endpoints for retrieving and managing UID2 tokens.
    | | Bidder | DSPs | Permission to decrypt UID2 tokens coming in from the bidstream from publishers into raw UID2s for bidding purposes. | | Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:
    • Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake
    • Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s.
    | -| Mapper | Advertisers
    Data Providers | Permission to call the [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) endpoint to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s and refresh timestamps. Permission to use the earlier V2 Identity Map [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoints as well. | +| Mapper | Advertisers
    Data Providers | Permission to call the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s and refresh timestamps. Permission to use the earlier V2 Identity Map [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoints as well. | diff --git a/docs/sdks/summary-sdks.md b/docs/sdks/summary-sdks.md index 0bdeebc1b..7a4696fd9 100644 --- a/docs/sdks/summary-sdks.md +++ b/docs/sdks/summary-sdks.md @@ -28,7 +28,7 @@ The following table summarizes the functionality available with each SDK. |Android | Client (Mobile) | — | — | ✅ | ✅ | — | — | |iOS | Client (Mobile) | — | — | ✅| ✅ |— | — | -*Advertisers and Data Providers who need to generate raw UID2s from DII can also do this via Snowflake (see [Snowflake Integration Guide](../guides/integration-snowflake.md)) or by using the [POST /identity/map (v3)](../endpoints/post-identity-map-v3.md) endpoint. +*Advertisers and Data Providers who need to generate raw UID2s from DII can also do this via Snowflake (see [Snowflake Integration Guide](../guides/integration-snowflake.md)) or by using the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md similarity index 83% rename from i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md rename to i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md index 6bcf50f14..35cfdce83 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v3.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md @@ -1,5 +1,5 @@ --- -title: POST /identity/map (v3) +title: POST /identity/map description: Maps DII to UID2s. hide_table_of_contents: false sidebar_position: 08 diff --git a/sidebars.js b/sidebars.js index 0c04fb100..67b410b77 100644 --- a/sidebars.js +++ b/sidebars.js @@ -322,10 +322,10 @@ const fullSidebar = [ 'endpoints/post-identity-buckets', { type: 'category', - label: 'POST /identity/map (v3)', + label: 'POST /identity/map', link: { type: 'doc', - id: 'endpoints/post-identity-map-v3', + id: 'endpoints/post-identity-map', }, collapsed: true, items: [ @@ -409,7 +409,7 @@ const sidebars = { 'DSP Integrations', 'guides/dsp-guide', 'endpoints/post-identity-buckets', - 'endpoints/post-identity-map-v3', + 'endpoints/post-identity-map', 'endpoints/post-identity-map-v2', 'endpoints/post-optout-status' ), From 4f49e0415e4a9377427f83354da4b746bfbdf322 Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Tue, 24 Jun 2025 11:55:41 +1000 Subject: [PATCH 22/28] Add input example --- docs/endpoints/post-identity-map.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index c1dfd1eb7..e7fa2d1a2 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -109,12 +109,25 @@ For details, and code examples in different programming languages, see [Encrypti The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted. ::: -A successful decrypted response returns the current UID2s, previous UID2s (where applicable) and refresh timestamps for the specified email addresses, phone numbers, or their respective hashes. +A successful decrypted response returns the current UID2s, previous UID2s and refresh timestamps for the specified email addresses, phone numbers, or their respective hashes. The response arrays preserve the order of input arrays. Each element in the response array maps directly to the element at the same index in the corresponding request array. This ensures that results can be reliably associated with their corresponding inputs based on array position. DIIs that cannot be mapped to a UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the DII is considered invalid or if the DII has opted out from the UID2 ecosystem. In these cases, the response status is still "success". +For example, given the following input: +```json +{ + "email": [ + "user@example.com" // Corresponding UID2 rotated in the last 90 days + "user2@example.com" // Corresponding UID2 rotated more than 90 days ago + "invalid email string" // Invalid identifier + "optout@example.com" // DII is opted out + ] +} +``` + +The resulting response will be as follows: ```json { "body":{ From 3ce7252ef2c835259dd9a43f2fed3f040a1e789d Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Tue, 24 Jun 2025 13:30:43 +1000 Subject: [PATCH 23/28] Clean up --- docs/getting-started/gs-credentials.md | 2 +- .../current/getting-started/gs-credentials.md | 2 +- .../current/getting-started/gs-faqs.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/gs-credentials.md b/docs/getting-started/gs-credentials.md index d6e8949aa..c703d163a 100644 --- a/docs/getting-started/gs-credentials.md +++ b/docs/getting-started/gs-credentials.md @@ -22,7 +22,7 @@ Each UID2     environment as well as the production environment, you'll get a separate set of credentials for each environment. See [Getting Your Credentials](#getting-your-credentials). In addition, in some cases, we recommend, but do not require, that you have a different set of credentials for a different scenario. For example: -- If you're a publisher who generates UID2 tokens (via [POST /token/generate](../endpoints/post-token-generate.md) or in some other way), but you also create/map raw UID2s on your own behalf (see [POST /identity/map)](../endpoints/post-identity-map.md)), you might have separate credentials for each of these activities. +- If you're a publisher who generates UID2 tokens (via [POST /token/generate](../endpoints/post-token-generate.md) or in some other way), but you also create/map raw UID2s on your own behalf (see [POST /identity/map](../endpoints/post-identity-map.md)), you might have separate credentials for each of these activities. - If you're an advertiser, in a scenario where you allow multiple service providers to operate using your advertiser keys, you might choose to have separate credentials for each service provider. ## Getting Your Credentials diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md index 3d31f16ec..50353d243 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md @@ -22,7 +22,7 @@ UID2 の 環境 と本番環境の両方を使用している場合、それぞれの環境用に別々の認証情報が提供されます。詳細は [Getting Your Credentials](#getting-your-credentials) を参照してください。 さらに、いくつかのケースでは、異なるシナリオに対して異なるセットの認証情報を持つことを勧めますが、必須ではありません。たとえば: -- UID2 Token を生成する Publisher である場合([POST /token/generate](../endpoints/post-token-generate.md) または他の方法で)、または自分のために UID2 を生成/マッピングする場合([POST /identity/map (v2)](post-identity-map-v2.md) を参照)、それぞれの活動に対して異なる認証情報を持つことがあります。 +- UID2 Token を生成する Publisher である場合([POST /token/generate](../endpoints/post-token-generate.md) または他の方法で)、または自分のために UID2 を生成/マッピングする場合([POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) を参照)、それぞれの活動に対して異なる認証情報を持つことがあります。 - 広告主の場合、広告主キーを使用して複数のサービスプロバイダが運用するシナリオで、各サービスプロバイダに対して異なる認証情報割り当てることができます。 ## Getting Your Credentials diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md index 59be23c9b..669ead43f 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md @@ -41,7 +41,7 @@ UID2 に DII を送信すると、UID2 はその情報を保存しますか？ いいえ。UID2 service のコンポーネントは、DII を保存しません。 -さらに、ほとんどの場合、UID2 は、[POST /token/generate](../endpoints/post-token-generate.md)、[POST /token/refresh](../endpoints/post-token-refresh.md)、または [POST /identity/map (v2)](post-identity-map-v2.md).md) の呼び出しが完了すると、値を全く保存しません。必要な例外は、ユーザーがオプトアウトした場合です。この場合、UID2 は、オプトアウトしたユーザーを示すハッシュ化された不透明な値を保存します。保存された値は、DII から生成された同じ UID2 に関する将来のリクエストを識別するために使用され、そのため拒否されます。 +さらに、ほとんどの場合、UID2 は、[POST /token/generate](../endpoints/post-token-generate.md)、[POST /token/refresh](../endpoints/post-token-refresh.md)、または [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) の呼び出しが完了すると、値を全く保存しません。必要な例外は、ユーザーがオプトアウトした場合です。この場合、UID2 は、オプトアウトしたユーザーを示すハッシュ化された不透明な値を保存します。保存された値は、DII から生成された同じ UID2 に関する将来のリクエストを識別するために使用され、そのため拒否されます。 #### Does UID2 allow the processing of HIPAA-regulated data? UID2 は HIPAA で規制されているデータの処理を許可しますか？ From f981484aefeee2966c094468fe49aa7f634cf31f Mon Sep 17 00:00:00 2001 From: Vishal Egbert Date: Tue, 24 Jun 2025 13:35:10 +1000 Subject: [PATCH 24/28] Clean up --- docs/getting-started/gs-permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/gs-permissions.md b/docs/getting-started/gs-permissions.md index c55faa312..1e7eeb1c8 100644 --- a/docs/getting-started/gs-permissions.md +++ b/docs/getting-started/gs-permissions.md @@ -26,4 +26,4 @@ The following table lists the key permissions, the types of participants that co | Generator | Publishers | Permission to call the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/validate](../endpoints/post-token-validate.md), and [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints, to generate UID2 tokens from DII and to refresh them, using one of these integration methods:
    • A Prebid integration
    • The SDK for JavaScript
    • An integration that directly calls the applicable API endpoints for retrieving and managing UID2 tokens.
    | | Bidder | DSPs | Permission to decrypt UID2 tokens coming in from the bidstream from publishers into raw UID2s for bidding purposes. | | Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:
    • Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake
    • Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s.
    | -| Mapper | Advertisers
    Data Providers | Permission to call the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s and refresh timestamps. Permission to use the earlier V2 Identity Map [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoints as well. | +| Mapper | Advertisers
    Data Providers | Permission to call the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s and refresh timestamps. Permission to call the earlier V2 Identity Map [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoints as well. | From 32ae9a3cc50444f9327ccf032312f7ad07afd647 Mon Sep 17 00:00:00 2001 From: genwhittTTD Date: Tue, 24 Jun 2025 14:52:57 -0400 Subject: [PATCH 25/28] POST /identity/map update, partial GWH edits --- docs/endpoints/post-identity-buckets.md | 6 +++ docs/endpoints/post-identity-map-v2.md | 6 ++- docs/endpoints/post-identity-map.md | 40 ++++++++++--------- docs/endpoints/summary-endpoints.md | 18 +++++---- docs/getting-started/gs-permissions.md | 2 +- docs/ref-info/glossary-uid.md | 4 +- .../current/endpoints/post-identity-map.md | 2 +- 7 files changed, 49 insertions(+), 29 deletions(-) diff --git a/docs/endpoints/post-identity-buckets.md b/docs/endpoints/post-identity-buckets.md index 44ecfa783..9708fe0cf 100644 --- a/docs/endpoints/post-identity-buckets.md +++ b/docs/endpoints/post-identity-buckets.md @@ -13,6 +13,12 @@ Monitors rotated salt bucke Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). +:::important +If you're using the latest version of `POST /v3/identity/map`, v3, you don't need to use `POST /identity/buckets` at all. You only need to use it if you're using the earlier version, `POST /v2/identity/map`. + +If you're using the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements. +::: + ## Request Format `POST '{environment}/v2/identity/buckets'` diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md index 53674fe68..500f3fe24 100644 --- a/docs/endpoints/post-identity-map-v2.md +++ b/docs/endpoints/post-identity-map-v2.md @@ -17,7 +17,11 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User ## Version -This documentation is for earlier version 2 of this endpoint. For documentation for the latest version 3 of this endpoint, see: [POST /identity/map](post-identity-map.md). +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 the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements. +::: ## Batch Size and Request Parallelization Requirements diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index e7fa2d1a2..a3633bc36 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -1,6 +1,6 @@ --- title: POST /identity/map -description: Maps DII to UID2s. +description: Maps DII to raw UID2s. hide_table_of_contents: false sidebar_position: 08 displayed_sidebar: docs @@ -10,7 +10,7 @@ import Link from '@docusaurus/Link'; # POST /identity/map -Maps multiple email addresses, phone numbers, or their respective hashes to their UID2s. You can also use this endpoint to check for updates to opt-out information, check when a UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old. +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when a raw UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old. Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). @@ -18,9 +18,9 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User ## Version -This documentation is for the latest version of this endpoint. +This documentation is for the latest version of this endpoint, version 3. -If needed, documentation is also available for the earlier version 2 of this endpoint, see: [POST /identity/map (v2)](post-identity-map-v2.md). +If needed, documentation is also available for the previous version: see [POST /identity/map (v2)](post-identity-map-v2.md). ## Batch Size and Request Parallelization Requirements @@ -54,7 +54,7 @@ The integration environment and the production environment require different
  • If the current raw UID2 has been rotated in the last 90 days: the previous value.
  • If the current raw UID2 is older than 90 days: `Null`.
    • | +| `r` | number | The Unix timestamp (in milliseconds) that indicates when the raw UID2 can be refreshed. | -For unsuccessfully mapped DII, the mapped object includes the properties shown in the following table. +For unsuccessfully mapped input values, the mapped object includes the properties shown in the following table. | Property | Data Type | Description | |:---------|:----------|:-----------------------------------------------------------------------------------------------------------------| -| `e` | string | The reason for being unable to map the DII to a UID2. Either one of "optout" or "invalid identifier". | +| `e` | string | The reason for being unable to map the DII to a raw UID2. One of two possible values:
    • `optout`
    • `invalid identifier`
    | ### Response Status Codes diff --git a/docs/endpoints/summary-endpoints.md b/docs/endpoints/summary-endpoints.md index d012b29de..fb3a25178 100644 --- a/docs/endpoints/summary-endpoints.md +++ b/docs/endpoints/summary-endpoints.md @@ -26,24 +26,28 @@ The following endpoints are for retrieving and managing UID2 tokens (identity to The following endpoints are used by advertisers and third-party data providers. Publishers do not need to use these endpoints. -### Latest V3 Identity Map Endpoint +### Latest Identity Map Endpoint (V3) -The following endpoint is part of the latest V3 Identity Map integration. +In the latest identity map integration, you only need to call one endpoint, `POST /identity/map`. The `POST /identity/buckets` endpoint is not part of the workflow. -Calling the /identity/buckets endpoint is no longer necessary when calling the latest Identity Map endpoint. +:::important +If you're using the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements. +::: + +The latest identity map integration uses the following endpoint: | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | -| [POST /identity/map](post-identity-map.md) | Maps UID2s, previous UID2s and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | +| [POST /identity/map](post-identity-map.md) | Maps raw UID2s, previous raw UID2s, and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | -### Earlier V2 Identity Map Endpoints +### Earlier Identity Map Endpoints (V2) -The following endpoints are part of the earlier V2 Identity Map integration. +The following endpoints are part of the earlier identity map integration (version 2). | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | | [POST /identity/buckets](post-identity-buckets.md) | Monitors rotated salt buckets using their last updated timestamp. | Required | Required | -| [POST /identity/map (v2)](post-identity-map-v2.md) | Maps UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | +| [POST /identity/map (v2)](post-identity-map-v2.md) | Maps raw UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | ## Opt-Out Status diff --git a/docs/getting-started/gs-permissions.md b/docs/getting-started/gs-permissions.md index 1e7eeb1c8..a8d18950c 100644 --- a/docs/getting-started/gs-permissions.md +++ b/docs/getting-started/gs-permissions.md @@ -26,4 +26,4 @@ The following table lists the key permissions, the types of participants that co | Generator | Publishers | Permission to call the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/validate](../endpoints/post-token-validate.md), and [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints, to generate UID2 tokens from DII and to refresh them, using one of these integration methods:
    • A Prebid integration
    • The SDK for JavaScript
    • An integration that directly calls the applicable API endpoints for retrieving and managing UID2 tokens.
    | | Bidder | DSPs | Permission to decrypt UID2 tokens coming in from the bidstream from publishers into raw UID2s for bidding purposes. | | Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:
    • Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake
    • Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s.
    | -| Mapper | Advertisers
    Data Providers | Permission to call the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s and refresh timestamps. Permission to call the earlier V2 Identity Map [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoints as well. | +| Mapper | Advertisers
    Data Providers | Permission to call the following endpoints to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s, and refresh timestamps:
    • [POST /identity/map](../endpoints/post-identity-map.md) (latest version)
    • The earlier (version 2) identity mapping endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md).
    | diff --git a/docs/ref-info/glossary-uid.md b/docs/ref-info/glossary-uid.md index 4e254b2d8..e31e6480b 100644 --- a/docs/ref-info/glossary-uid.md +++ b/docs/ref-info/glossary-uid.md @@ -417,10 +417,12 @@ import Link from '@docusaurus/Link';
    Salt bucket
    A salt bucket is used to manage secret salt values, used to generate raw UID2s or UID2 tokens, over time. Each bucket contains a single current salt value, which remains active for approximately one year before being rotated to a new value. Buckets can be updated independently of one another.
    There are just over one million salt buckets, and each email address or phone number is assigned to a specific bucket in a deterministic manner. However, this assignment is not permanent; it might change when the bucket's current salt is rotated to a new value.
    +
    In versions of the [POST /identity/map](../endpoints/post-identity-map.md) endpoint earlier than version 3, such as [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md), the endpoint returns salt bucket IDs. In v3 and later, salt bucket information is not needed.
    Salt bucket ID
    A salt bucket ID is a unique string of characters that identifies a specific salt bucket. The salt bucket ID can be used to check which salt buckets have recently had their salt values updated, indicating which emails or phone numbers need their raw UID2 values regenerated.
    -
    For an example of a salt bucket ID, see the response to the `POST /identity/buckets` endpoint: Decrypted JSON Response Format.
    +
    In versions of the [POST /identity/map](../endpoints/post-identity-map.md) endpoint earlier than version 3, such as [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md), the endpoint returns salt bucket IDs. In v3 and later, salt bucket information is not needed.
    +
    For an example of a salt bucket ID, see the response to the `POST /v2/identity/buckets` endpoint: Decrypted JSON Response Format. If you're using `POST /v3/identity/map`, you don't need to use `POST /v2/identity/buckets` at all.
    Salted hash
    When a salt value is added to the input string before applying the hash function, the result is a salted hash. When the input value is salted before hashing, an attacker who has the hash cannot determine the input value by trying many possible inputs to arrive at the same output.
    diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md index 35cfdce83..25a88b9c6 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md @@ -1,6 +1,6 @@ --- title: POST /identity/map -description: Maps DII to UID2s. +description: Maps DII to raw UID2s. hide_table_of_contents: false sidebar_position: 08 displayed_sidebar: docs From b09c6f230c0493a0f5b2574044a73f8a5b94c1f5 Mon Sep 17 00:00:00 2001 From: Gian Miguel Del Mundo Date: Thu, 26 Jun 2025 14:28:13 +0800 Subject: [PATCH 26/28] Reverted Japanese file changes --- .../current/endpoints/post-identity-map-v2.md | 199 ------------------ .../current/endpoints/post-identity-map.md | 193 ++++++++++++++++- .../current/endpoints/summary-endpoints.md | 2 +- .../current/getting-started/gs-credentials.md | 2 +- .../current/getting-started/gs-faqs.md | 8 +- .../current/getting-started/gs-opt-out.md | 2 +- .../current/getting-started/gs-permissions.md | 2 +- ...ation-advertiser-dataprovider-endpoints.md | 10 +- ...ration-advertiser-dataprovider-overview.md | 6 +- .../current/ref-info/updates-doc.md | 2 +- .../current/sdks/summary-sdks.md | 2 +- .../sharing/sharing-tokenized-overview.md | 2 +- 12 files changed, 210 insertions(+), 220 deletions(-) delete mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md deleted file mode 100644 index f4112b91f..000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: POST /identity/map (v2) -description: DII を raw UID2 とソルトバケット ID にマッピング。 -hide_table_of_contents: false -sidebar_position: 08 ---- - -import Link from '@docusaurus/Link'; - -# POST /identity/map (v2) - -複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 と salt bucket IDs にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます - -Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) を参照してください。 - -UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳細は、[User Opt-Out](../getting-started/gs-opt-out.md) を参照してください。 - -## Batch Size and Request Parallelization Requirements - -知っておくべきことは以下のとおりです: - -- リクエストの最大サイズは 1MB です。 -- 大量のメールアドレス、電話番号、またはそれぞれのハッシュをマップするには、1 バッチあたり最大 5,000 アイテムのバッチサイズで、それらを *連続した* バッチで送信してください。 -- Private Operator を使用している場合を除き、バッチを並行して送信しないでください。つまり、単一の HTTP 接続を使用して、[directly identifying information (DII)](../ref-info/glossary-uid.md#gl-dii) を連続してマッピングしてください。 -- メールアドレス、電話番号、またはそれぞれのハッシュのマッピングを必ず保存してください。
    マッピングを保存しないと、数百万のメールアドレスや電話番号をマッピングする必要がある場合に、処理時間が大幅に増加する可能性があります。しかし、実際に更新が必要なマッピングのみを再計算することで、毎日更新が必要な raw UID2 の数は約 1/365 となり、総処理時間を短縮できます。[Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) と [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers) も参照してください。 - -## Request Format - -`POST '{environment}/v2/identity/map'` - -認証の詳細は、 [Authentication and Authorization](../getting-started/gs-auth.md) を参照してください。 - -:::important -すべてのリクエストを秘密鍵で暗号化する必要があります。詳細といくつかのプログラミング言語でのコードの例は、[リクエストの暗号化とレスポンスの復号化](../getting-started/gs-encryption-decryption.md) を参照してください。 -::: - -### Path Parameters - -| Path Parameter | Data Type | Attribute | Description | -| :--- | :--- | :--- | :--- | -| `{environment}` | string | 必須 | テスト (インテグレーション) 環境: `https://operator-integ.uidapi.com`
    本番環境: `https://prod.uidapi.com`
    リージョンごとのオペレーターを含む全リストは [Environments](../getting-started/gs-environments.md) を参照してください。 | - -:::note -インテグレーション環境と本番環境では、異なる API Key が必要です。各環境の認証情報を取得する方法については、[Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials) を参照してください。 -::: - -### Unencrypted JSON Body Parameters - -:::important -リクエストを暗号化するときは、以下の 4 つの条件パラメータのうち、**1つ** だけをリクエストの JSON ボディにキーと値のペアとして含める必要がります。 -::: - -| Body Parameter | Data Type | Attribute | Description | -| :--- | :--- | :--- | :--- | -| `email` | string array | 条件付きで必要 | マッピングするメールアドレスのリストです。 | -| `email_hash` | string array | 条件付きで必要 | マッピングする [SHA-256 ハッシュし、Base64 エンコード](../getting-started/gs-normalization-encoding.md#email-address-normalization) した [正規化](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) 済みメールアドレスのリストです。 | -| `phone` | string array | 条件付きで必要 | マッピングする [正規化](../getting-started/gs-normalization-encoding.md#phone-number-normalization) 済み電話番号のリストです。 | -| `phone_hash` | string array | 条件付きで必要 | マッピングする [SHA-256 ハッシュし、Base64 エンコード](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) した [正規化](../getting-started/gs-normalization-encoding.md#phone-number-normalization) 済み電話番号のリストです。 | - -### Request Examples - -以下は、各パラメータの暗号化されていない JSON リクエストボディの例です。このうちの 1 つを、`POST /identity/map` エンドポイントへのリクエストに含める必要があります: - -```json -{ - "email": [ - "user@example.com", - "user2@example.com" - ] -} -``` -```json -{ - "email_hash": [ - "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", - "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU=" - ] -} -``` -```json -{ - "phone": [ - "+12345678901", - "+441234567890" - ] -} -``` -```json -{ - "phone_hash": [ - "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=" - ] -} -``` - -以下は、電話番号に対する `POST /identity/map` エンドポイントへの暗号化リクエストの例です: - -```sh -echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret] -``` - -詳細といくつかのプログラミング言語でのコードの例は、[リクエストの暗号化とレスポンスの復号化](../getting-started/gs-encryption-decryption.md) を参照してください。 - -## Decrypted JSON Response Format - -:::note -レスポンスは、HTTP ステータスコードが 200 の場合のみ暗号化されます。それ以外の場合、レスポンスは暗号化されません。 -::: - -復号化に成功すると、指定したメールアドレス、電話番号、またはそれぞれのハッシュに対する raw UID2 とソルトバケット ID が返されます。 - -```json -{ - "body": { - "mapped": [ - { - "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "a30od4mNRd" - }, - { - "identifier": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=", - "advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=", - "bucket_id": "ad1ANEmVZ" - } - ] - }, - "status": "success" -} -``` - -一部の識別子が無効と判断された場合、それらの識別子は "unmapped" リストとしてレスポンスに含まれる。この場合でも、レスポンスステータスは "success" となります。すべての識別子がマッピングされた場合、"unmapped"リストはレスポンスに含まれません。 - -```json -{ - "body": { - "mapped": [ - { - "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "a30od4mNRd" - } - ], - "unmapped": [ - { - "identifier": "some@malformed@email@hash", - "reason": "invalid identifier" - } - ] - }, - "status": "success" -} -``` - -一部の識別子が UID2 エコシステムからオプトアウトしている場合、オプトアウトした識別子は、見つかった無効な識別子とともに "unmapped" リストに移動されます。この場合でも、レスポンスステータスは "success" です。 - -```json -{ - "body": { - "mapped": [ - { - "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "a30od4mNRd" - } - ], - "unmapped": [ - { - "identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", - "reason": "optout" - } - ] - }, - "status": "success" -} -``` - -### Response Body Properties - -レスポンスボディには、次の表に示すプロパティが含まれます。 - -| Property | Data Type | Description | -| :--- | :--- | :--- | -| `identifier` | string | リクエストボディで指定されたメールアドレス、電話番号、またはそれぞれのハッシュです。 | -| `advertising_id` | string | 対応する Advertising ID (raw UID2) です。 | -| `bucket_id` | string | raw UID2 の生成に使用したソルトバケットの ID です。 | - -### Response Status Codes - -次の表は、`status` プロパティの値と、それに対応する HTTP ステータスコードの一覧です。 - -| Status | HTTP Status Code | Description | -| :--- | :--- | :--- | -| `success` | 200 | リクエストは成功しました。レスポンスは暗号化されています。 | -| `client_error` | 400 | リクエストに不足している、または無効なパラメータがありました。 | -| `unauthorized` | 401 | クエストにベアラートークンが含まれていない、無効なベアラートークンが含まれている、またはリクエストされた操作を実行するのに許可されていないベアラートークンが含まれていた。 | - -`status` の値が `success` 以外であれば、`message` フィールドにその問題に関する追加情報が表示されます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md index 25a88b9c6..3fec46ef5 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map.md @@ -1,10 +1,199 @@ --- title: POST /identity/map -description: Maps DII to raw UID2s. +description: DII を raw UID2 とソルトバケット ID にマッピング。 hide_table_of_contents: false sidebar_position: 08 -displayed_sidebar: docs --- import Link from '@docusaurus/Link'; +# POST /identity/map + +複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 と salt bucket IDs にマッピングします。このエンドポイントを使用して、オプトアウト情報の更新をチェックすることもできます + +Used by: このエンドポイントは、主に広告主やデータプロバイダーが使用します。詳細は [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) を参照してください。 + +UID2 の Opt-Out ワークフローとユーザーが Opt-Out する方法の詳細は、[User Opt-Out](../getting-started/gs-opt-out.md) を参照してください。 + +## Batch Size and Request Parallelization Requirements + +知っておくべきことは以下のとおりです: + +- リクエストの最大サイズは 1MB です。 +- 大量のメールアドレス、電話番号、またはそれぞれのハッシュをマップするには、1 バッチあたり最大 5,000 アイテムのバッチサイズで、それらを *連続した* バッチで送信してください。 +- Private Operator を使用している場合を除き、バッチを並行して送信しないでください。つまり、単一の HTTP 接続を使用して、[directly identifying information (DII)](../ref-info/glossary-uid.md#gl-dii) を連続してマッピングしてください。 +- メールアドレス、電話番号、またはそれぞれのハッシュのマッピングを必ず保存してください。
    マッピングを保存しないと、数百万のメールアドレスや電話番号をマッピングする必要がある場合に、処理時間が大幅に増加する可能性があります。しかし、実際に更新が必要なマッピングのみを再計算することで、毎日更新が必要な raw UID2 の数は約 1/365 となり、総処理時間を短縮できます。[Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) と [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers) も参照してください。 + +## Request Format + +`POST '{environment}/v2/identity/map'` + +認証の詳細は、 [Authentication and Authorization](../getting-started/gs-auth.md) を参照してください。 + +:::important +すべてのリクエストを秘密鍵で暗号化する必要があります。詳細といくつかのプログラミング言語でのコードの例は、[リクエストの暗号化とレスポンスの復号化](../getting-started/gs-encryption-decryption.md) を参照してください。 +::: + +### Path Parameters + +| Path Parameter | Data Type | Attribute | Description | +| :--- | :--- | :--- | :--- | +| `{environment}` | string | 必須 | テスト (インテグレーション) 環境: `https://operator-integ.uidapi.com`
    本番環境: `https://prod.uidapi.com`
    リージョンごとのオペレーターを含む全リストは [Environments](../getting-started/gs-environments.md) を参照してください。 | + +:::note +インテグレーション環境と本番環境では、異なる API Key が必要です。各環境の認証情報を取得する方法については、[Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials) を参照してください。 +::: + +### Unencrypted JSON Body Parameters + +:::important +リクエストを暗号化するときは、以下の 4 つの条件パラメータのうち、**1つ** だけをリクエストの JSON ボディにキーと値のペアとして含める必要がります。 +::: + +| Body Parameter | Data Type | Attribute | Description | +| :--- | :--- | :--- | :--- | +| `email` | string array | 条件付きで必要 | マッピングするメールアドレスのリストです。 | +| `email_hash` | string array | 条件付きで必要 | マッピングする [SHA-256 ハッシュし、Base64 エンコード](../getting-started/gs-normalization-encoding.md#email-address-normalization) した [正規化](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) 済みメールアドレスのリストです。 | +| `phone` | string array | 条件付きで必要 | マッピングする [正規化](../getting-started/gs-normalization-encoding.md#phone-number-normalization) 済み電話番号のリストです。 | +| `phone_hash` | string array | 条件付きで必要 | マッピングする [SHA-256 ハッシュし、Base64 エンコード](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) した [正規化](../getting-started/gs-normalization-encoding.md#phone-number-normalization) 済み電話番号のリストです。 | + +### Request Examples + +以下は、各パラメータの暗号化されていない JSON リクエストボディの例です。このうちの 1 つを、`POST /identity/map` エンドポイントへのリクエストに含める必要があります: + +```json +{ + "email": [ + "user@example.com", + "user2@example.com" + ] +} +``` +```json +{ + "email_hash": [ + "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", + "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU=" + ] +} +``` +```json +{ + "phone": [ + "+12345678901", + "+441234567890" + ] +} +``` +```json +{ + "phone_hash": [ + "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=" + ] +} +``` + +以下は、電話番号に対する `POST /identity/map` エンドポイントへの暗号化リクエストの例です: + +```sh +echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret] +``` + +詳細といくつかのプログラミング言語でのコードの例は、[リクエストの暗号化とレスポンスの復号化](../getting-started/gs-encryption-decryption.md) を参照してください。 + +## Decrypted JSON Response Format + +:::note +レスポンスは、HTTP ステータスコードが 200 の場合のみ暗号化されます。それ以外の場合、レスポンスは暗号化されません。 +::: + +復号化に成功すると、指定したメールアドレス、電話番号、またはそれぞれのハッシュに対する raw UID2 とソルトバケット ID が返されます。 + +```json +{ + "body": { + "mapped": [ + { + "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "a30od4mNRd" + }, + { + "identifier": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=", + "advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=", + "bucket_id": "ad1ANEmVZ" + } + ] + }, + "status": "success" +} +``` + +一部の識別子が無効と判断された場合、それらの識別子は "unmapped" リストとしてレスポンスに含まれる。この場合でも、レスポンスステータスは "success" となります。すべての識別子がマッピングされた場合、"unmapped"リストはレスポンスに含まれません。 + +```json +{ + "body": { + "mapped": [ + { + "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "a30od4mNRd" + } + ], + "unmapped": [ + { + "identifier": "some@malformed@email@hash", + "reason": "invalid identifier" + } + ] + }, + "status": "success" +} +``` + +一部の識別子が UID2 エコシステムからオプトアウトしている場合、オプトアウトした識別子は、見つかった無効な識別子とともに "unmapped" リストに移動されます。この場合でも、レスポンスステータスは "success" です。 + +```json +{ + "body": { + "mapped": [ + { + "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "a30od4mNRd" + } + ], + "unmapped": [ + { + "identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", + "reason": "optout" + } + ] + }, + "status": "success" +} +``` + +### Response Body Properties + +レスポンスボディには、次の表に示すプロパティが含まれます。 + +| Property | Data Type | Description | +| :--- | :--- | :--- | +| `identifier` | string | リクエストボディで指定されたメールアドレス、電話番号、またはそれぞれのハッシュです。 | +| `advertising_id` | string | 対応する Advertising ID (raw UID2) です。 | +| `bucket_id` | string | raw UID2 の生成に使用したソルトバケットの ID です。 | + +### Response Status Codes + +次の表は、`status` プロパティの値と、それに対応する HTTP ステータスコードの一覧です。 + +| Status | HTTP Status Code | Description | +| :--- | :--- | :--- | +| `success` | 200 | リクエストは成功しました。レスポンスは暗号化されています。 | +| `client_error` | 400 | リクエストに不足している、または無効なパラメータがありました。 | +| `unauthorized` | 401 | クエストにベアラートークンが含まれていない、無効なベアラートークンが含まれている、またはリクエストされた操作を実行するのに許可されていないベアラートークンが含まれていた。 | + +`status` の値が `success` 以外であれば、`message` フィールドにその問題に関する追加情報が表示されます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/summary-endpoints.md b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/summary-endpoints.md index ed0a6ed96..19fe3a91e 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/summary-endpoints.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/summary-endpoints.md @@ -29,7 +29,7 @@ import Link from '@docusaurus/Link'; | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | | [POST /identity/buckets](post-identity-buckets.md) | 最後に更新されたタイムスタンプを使用して、ローテーションされたソルトバケットを監視します。 | 必須 | 必須 | -| [POST /identity/map (v2)](post-identity-map-v2.md) | 1 つ以上のメールアドレス、電話番号、またはそれぞれのハッシュの UID2 とソルトバケット ID を取得します。 | 必須 | 必須 | +| [POST /identity/map](post-identity-map.md) | 1 つ以上のメールアドレス、電話番号、またはそれぞれのハッシュの UID2 とソルトバケット ID を取得します。 | 必須 | 必須 | ## Opt-Out Status diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md index 50353d243..d7f2abcb0 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-credentials.md @@ -22,7 +22,7 @@ UID2 の 環境 と本番環境の両方を使用している場合、それぞれの環境用に別々の認証情報が提供されます。詳細は [Getting Your Credentials](#getting-your-credentials) を参照してください。 さらに、いくつかのケースでは、異なるシナリオに対して異なるセットの認証情報を持つことを勧めますが、必須ではありません。たとえば: -- UID2 Token を生成する Publisher である場合([POST /token/generate](../endpoints/post-token-generate.md) または他の方法で)、または自分のために UID2 を生成/マッピングする場合([POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) を参照)、それぞれの活動に対して異なる認証情報を持つことがあります。 +- UID2 Token を生成する Publisher である場合([POST /token/generate](../endpoints/post-token-generate.md) または他の方法で)、または自分のために UID2 を生成/マッピングする場合([POST /identity/map](../endpoints/post-identity-map.md) を参照)、それぞれの活動に対して異なる認証情報を持つことがあります。 - 広告主の場合、広告主キーを使用して複数のサービスプロバイダが運用するシナリオで、各サービスプロバイダに対して異なる認証情報割り当てることができます。 ## Getting Your Credentials diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md index 669ead43f..4b69a93f4 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-faqs.md @@ -41,7 +41,7 @@ UID2 に DII を送信すると、UID2 はその情報を保存しますか？ いいえ。UID2 service のコンポーネントは、DII を保存しません。 -さらに、ほとんどの場合、UID2 は、[POST /token/generate](../endpoints/post-token-generate.md)、[POST /token/refresh](../endpoints/post-token-refresh.md)、または [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) の呼び出しが完了すると、値を全く保存しません。必要な例外は、ユーザーがオプトアウトした場合です。この場合、UID2 は、オプトアウトしたユーザーを示すハッシュ化された不透明な値を保存します。保存された値は、DII から生成された同じ UID2 に関する将来のリクエストを識別するために使用され、そのため拒否されます。 +さらに、ほとんどの場合、UID2 は、[POST /token/generate](../endpoints/post-token-generate.md)、[POST /token/refresh](../endpoints/post-token-refresh.md)、または [POST /identity/map](../endpoints/post-identity-map.md) の呼び出しが完了すると、値を全く保存しません。必要な例外は、ユーザーがオプトアウトした場合です。この場合、UID2 は、オプトアウトしたユーザーを示すハッシュ化された不透明な値を保存します。保存された値は、DII から生成された同じ UID2 に関する将来のリクエストを識別するために使用され、そのため拒否されます。 #### Does UID2 allow the processing of HIPAA-regulated data? UID2 は HIPAA で規制されているデータの処理を許可しますか？ @@ -222,7 +222,7 @@ UID2 生成リクエストで提供されるメタデータには、UID2 の生 #### How should I handle user opt-outs? ユーザーのオプトアウトはどのように処理すればよいですか？ -ユーザーが [Transparency and Control Portal](https://www.transparentadvertising.com/) を通じて UID2 ベースのターゲティング広告をオプトアウトすると、オプトアウト信号が DSP とパブリッシャーに送信され、DSP とパブリッシャーが入札時にオプトアウトを処理します。広告主やデータプロバイダーは、[POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを通じて、ユーザーがオプトアウトしたかどうかを定期的に確認することを勧めます。 +ユーザーが [Transparency and Control Portal](https://www.transparentadvertising.com/) を通じて UID2 ベースのターゲティング広告をオプトアウトすると、オプトアウト信号が DSP とパブリッシャーに送信され、DSP とパブリッシャーが入札時にオプトアウトを処理します。広告主やデータプロバイダーは、[POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを通じて、ユーザーがオプトアウトしたかどうかを定期的に確認することを勧めます。 広告主やデータプロバイダーは、raw UID2 に対するオプトアウトステータスを確認するために、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用することもできます。 @@ -231,7 +231,7 @@ UID2 生成リクエストで提供されるメタデータには、UID2 の生 #### Does the same DII always result in the same raw UID2? 同じ DII は常に同じ raw UID2 になりますか？ -一般的にその通りです。DII から raw UID2 を生成するプロセスは同じであり、誰がリクエストを送信したかに関係なく、結果は同じ値になります。 2 人の UID2 参加者が同じメールアドレスを [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントに同時に送信した場合、応答として両方とも同じ raw UID2 を取得します。 +一般的にその通りです。DII から raw UID2 を生成するプロセスは同じであり、誰がリクエストを送信したかに関係なく、結果は同じ値になります。 2 人の UID2 参加者が同じメールアドレスを [POST /identity/map](../endpoints/post-identity-map.md) エンドポイントに同時に送信した場合、応答として両方とも同じ raw UID2 を取得します。 ただし、raw UID2 の生成に使用される秘密の [ソルト](../ref-info/glossary-uid.md#gl-salt) 値という可変要素があります。ソルト値は定期的にローテーションされます(詳細は [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates)) を参照)。あるリクエストと別のリクエストの間でソルト値が変化する場合、DII が同じであっても、これら 2 つのリクエストは 2 つの異なる raw UID2 になります。 @@ -240,7 +240,7 @@ UID2 生成リクエストで提供されるメタデータには、UID2 の生 #### If two operators process the same DII, are the results the same? 2 つの Operator が同じ DII を処理した場合、結果は同じになりますか？ -はい、リクエストが raw UID2 に対するものである場合は、同じです。前の FAQ で説明したように、[同じ DII は常に同じ raw UID2 になりますか？](#does-the-same-dii-always-result-in-the-same-raw-uid2)、広告主やデータプロバイダーが同時に同じ DII を UID2 Operator に送信する場合、SDK または [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを使用して、同じ raw UID2 が生成されます。 +はい、リクエストが raw UID2 に対するものである場合は、同じです。前の FAQ で説明したように、[同じ DII は常に同じ raw UID2 になりますか？](#does-the-same-dii-always-result-in-the-same-raw-uid2)、広告主やデータプロバイダーが同時に同じ DII を UID2 Operator に送信する場合、SDK または [POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを使用して、同じ raw UID2 が生成されます。 Operator に関係なく、また、Private Operator と Public Operator のどちらであっても、結果は同じです。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-opt-out.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-opt-out.md index a97fa92f5..2cdb4e4a3 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-opt-out.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-opt-out.md @@ -49,7 +49,7 @@ UID2 エコシステムには、2 種類のオプトアウトがあります: | :--- | :--- | | Publishers | [POST /token/generate](../endpoints/post-token-generate.md) を必須パラメータ `optout_check` を `1` に設定して呼び出したパブリッシャー、または [POST /token/refresh](../endpoints/post-token-refresh.md) を呼び出したパブリッシャーは、UID2 Token の代わりにオプトアウトレスポンスを受け取ります。| | DSPs | UID2 Operator Service は、DSP に対して、その目的のために提供された Webhook を介して、オプトアウトしたすべてのユーザーの情報を配布します。詳細は [Honor User Opt-Outs](../guides/dsp-guide#honor-user-opt-outs) を参照してください。
    DSP は、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認することもできます。 | - | 広告主とデータプロバイダー | UID2 Operator Service は、[POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを介して、広告主とデータプロバイダーにオプトアウト情報を配布します。別のオプションとして、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認することもできます。 | + | 広告主とデータプロバイダー | UID2 Operator Service は、[POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを介して、広告主とデータプロバイダーにオプトアウト情報を配布します。別のオプションとして、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認することもできます。 | | Sharers | UID2 Sharer は、[POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認することができます。 | このワークフローにより、ユーザーは Transparency and Control Portal を通じて、UID2 に基づくパーソナライズ広告をオプトアウトすることができます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-permissions.md b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-permissions.md index 530ffc84f..441683055 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-permissions.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/getting-started/gs-permissions.md @@ -26,4 +26,4 @@ UID2 エコシステムには、特定のアクティビティを完了するた | Generator | Publishers | Permission to call the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/validate](../endpoints/post-token-validate.md), and [POST /token/refresh](../endpoints/post-token-refresh.md) の各エンドポイントを呼び出して、DII から UID2 Token を生成/リフレッシュする権限:
    • Prebid インテグレーション
    • The SDK for JavaScript
    • UID2 Token の取得と管理のために、該当する API エンドポイントを直接呼び出すインテグレーション
    | | Bidder | DSPs | パブリッシャーからのビッドストリームから送られてくる UID2 Token を、入札目的で raw UID2 に復号化する権限。 | | Sharer | UID2 sharing に参加するすべての参加者タイプ。詳細は [UID2 Sharing: Overview](../sharing/sharing-overview.md) を参照してください。 | 以下両方の権限:
    • UID2 SDK または S nowflake を使用して、raw UID2 を UID2 Token に暗号化し、許可された別の共有参加者と共有します。
    • 他の許可された共有参加者から受け取った UID2 Token を raw UID2 に復号します。
    | -| Mapper | Advertisers
    Data Providers | [POST /identity/buckets](../endpoints/post-identity-buckets.md) エンドポイントを使用して、ローテーションされたソルトバケットをモニターし、[POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを使用して、複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 とソルトバケット ID にマッピングする権限。 | +| Mapper | Advertisers
    Data Providers | [POST /identity/buckets](../endpoints/post-identity-buckets.md) エンドポイントを使用して、ローテーションされたソルトバケットをモニターし、[POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを使用して、複数のメールアドレス、電話番号、またはそれぞれのハッシュを、raw UID2 とソルトバケット ID にマッピングする権限。 | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md index 463f1f8cc..e6c96ebff 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-endpoints.md @@ -62,8 +62,8 @@ DII は、ユーザーの正規化されたメールアドレスまたは電話 | Step | Endpoint | Description | | --- | --- | --- | -| 1-a | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) request | DII を含むリクエストを ID マッピングエンドポイントに送信します。 | -| 1-b | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) response | レスポンスで返される `advertising_id` (raw UID2) は、関連する DSP でオーディエンスをターゲットするために使用できます。
    レスポンスは、ユーザーの raw UID2 と、それに対応するソルトバケットの `bucket_id` を返します。バケットに割り当てられたソルトは年に一度ローテーションし、生成された raw UID2 に影響を与えます。ソルトバケットのローテーションを確認する方法の詳細は、[5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s) を参照してください。 | +| 1-a | [POST /identity/map](../endpoints/post-identity-map.md) request | DII を含むリクエストを ID マッピングエンドポイントに送信します。 | +| 1-b | [POST /identity/map](../endpoints/post-identity-map.md) response | レスポンスで返される `advertising_id` (raw UID2) は、関連する DSP でオーディエンスをターゲットするために使用できます。
    レスポンスは、ユーザーの raw UID2 と、それに対応するソルトバケットの `bucket_id` を返します。バケットに割り当てられたソルトは年に一度ローテーションし、生成された raw UID2 に影響を与えます。ソルトバケットのローテーションを確認する方法の詳細は、[5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s) を参照してください。 | ### 2: Store Raw UID2s and Salt Bucket IDs @@ -105,8 +105,8 @@ raw UID2 は、特定の時点におけるユーザーの識別子です。raw U | --- | --- | --- | | 5-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | 特定のタイムスタンプ以降に変更されたすべてのソルトバケットに対して、`POST /identity/buckets` エンドポイントにリクエストを送信します。 | | 5-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 Service: `POST /identity/buckets` エンドポイントは、`bucket_id` と `last_updated` タイムスタンプのリストを返します。 | -| 5-c | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) | 返された `bucket_id` をキャッシュした raw UID2 のソルトバケットと比較します。
    1 つ以上の raw UID2 のソルトバケットが更新された場合は、新しい raw UID2 用に DII を `POST /identity/map` エンドポイントに再送信します。 | -| 5-d | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) | `advertising_id` と `bucket_id` の新しい値を保存します。 | +| 5-c | [POST /identity/map](../endpoints/post-identity-map.md) | 返された `bucket_id` をキャッシュした raw UID2 のソルトバケットと比較します。
    1 つ以上の raw UID2 のソルトバケットが更新された場合は、新しい raw UID2 用に DII を `POST /identity/map` エンドポイントに再送信します。 | +| 5-d | [POST /identity/map](../endpoints/post-identity-map.md) | `advertising_id` と `bucket_id` の新しい値を保存します。 | #### Determine whether the salt bucket has been rotated @@ -126,7 +126,7 @@ raw UID2 は、特定の時点におけるユーザーの識別子です。raw U UID2 Operator Service に最新のオプトアウト情報があるかを確認する方法は 2 つあります: -- [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを呼び出してオプトアウトを確認します。DII がオプトアウトされている場合、raw UID2 は生成されません。 +- [POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを呼び出してオプトアウトを確認します。DII がオプトアウトされている場合、raw UID2 は生成されません。 - [POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md index 7f77c2694..b4f992e2a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/guides/integration-advertiser-dataprovider-overview.md @@ -49,7 +49,7 @@ import Link from '@docusaurus/Link'; | High-Level Step | Implementation Options | | --- | --- | -| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | DII を raw UID2 にマッピングするには、以下のオプションのいずれかをします:
    • 以下の UID2 SDK のいずれか:
      • Python SDK: [DII を Raw UID2 にマッピング](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s)
      • Java SDK: [広告主/データプロバイダー向けの使用法](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers)
    • Snowflake: [DII をマッピング](integration-snowflake.md#map-dii)
    • AWS Entity Resolution: [AWS Entity Resolution インテグレーションガイド](integration-aws-entity-resolution.md)
    • HTTP エンドポイント: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md)
    | +| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | DII を raw UID2 にマッピングするには、以下のオプションのいずれかをします:
    • 以下の UID2 SDK のいずれか:
      • Python SDK: [DII を Raw UID2 にマッピング](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s)
      • Java SDK: [広告主/データプロバイダー向けの使用法](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers)
    • Snowflake: [DII をマッピング](integration-snowflake.md#map-dii)
    • AWS Entity Resolution: [AWS Entity Resolution インテグレーションガイド](integration-aws-entity-resolution.md)
    • HTTP エンドポイント: [POST /identity/map](../endpoints/post-identity-map.md)
    | | [2: Store Raw UID2s and Salt Bucket IDs](#2-store-raw-uid2s-and-salt-bucket-ids) | カスタム（適切な方法で）。 | | [3: Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s) | カスタム（適切な方法で）。 | | [4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) | カスタム（適切な方法で）。 | @@ -85,7 +85,7 @@ raw UID2 を生成するには、以下のオプションのいずれかを使 - AWS Entity Resolution: [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md) を参照してください。 -- HTTP endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md). 詳細は、[Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii) を参照してください。 +- HTTP endpoints: [POST /identity/map](../endpoints/post-identity-map.md). 詳細は、[Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii) を参照してください。 ### 2: Store Raw UID2s and Salt Bucket IDs @@ -150,7 +150,7 @@ AWS Entity Resolution では、ソルトバケットの監視方法はありま UID2 Operator Service で最新のオプトアウト情報があるかを確認する方法は 2 つあります: -- [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイイントを使用して、raw UID2 のオプトアウトステータスを確認します。オプトアウトされた DII には、raw UID2 は生成されません。 +- [POST /identity/map](../endpoints/post-identity-map.md) エンドポイイントを使用して、raw UID2 のオプトアウトステータスを確認します。オプトアウトされた DII には、raw UID2 は生成されません。 - [POST /optout/status](../endpoints/post-optout-status.md) エンドポイントを使用して、raw UID2 のオプトアウトステータスを確認します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/updates-doc.md b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/updates-doc.md index 3a28ddfe3..96dd9fb5a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/updates-doc.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/ref-info/updates-doc.md @@ -422,7 +422,7 @@ March 4, 2024 February 28, 2024 -Java SDKは、[POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントの使用を希望する広告主およびデータプロバイダーをサポートするようになりました。 +Java SDKは、[POST /identity/map](../endpoints/post-identity-map.md) エンドポイントの使用を希望する広告主およびデータプロバイダーをサポートするようになりました。 詳細は、*SDK for Javaリファレンスガイド*: [Usage for Advertisers and Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers) の更新されたドキュメントを参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/summary-sdks.md b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/summary-sdks.md index b5de39bd0..6dbc97fed 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/sdks/summary-sdks.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sdks/summary-sdks.md @@ -28,7 +28,7 @@ SDK の機能を確認して使用する SDK を決定し、SDK の表をクリ |Android | Client (Mobile) | — | — | ✅ | ✅ | — | — | |iOS | Client (Mobile) | — | — | ✅| ✅ |— | — | -*DII から raw UID2 を生成する必要がある広告主およびデータプロバイダは Snowflake ([Snowflake Integration Guide](../guides/integration-snowflake.md) を参照) または [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) エンドポイントを使用することができます。 +*DII から raw UID2 を生成する必要がある広告主およびデータプロバイダは Snowflake ([Snowflake Integration Guide](../guides/integration-snowflake.md) を参照) または [POST /identity/map](../endpoints/post-identity-map.md) エンドポイントを使用することができます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sharing/sharing-tokenized-overview.md b/i18n/ja/docusaurus-plugin-content-docs/current/sharing/sharing-tokenized-overview.md index df684427d..20d6d7794 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/sharing/sharing-tokenized-overview.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sharing/sharing-tokenized-overview.md @@ -165,7 +165,7 @@ raw UID2 から始める場合は、次の手順に従ってください: 1 user@example.com -メールアドレス/電話番号を raw UID2 に変換する:
    POST /identity/map (v2) endpoint +メールアドレス/電話番号を raw UID2 に変換する:
    POST /identity/map endpoint K2jlbu2ldlpKL1z6n5bET7L3
    g0xfqmldZPDdPTktdRQ= From 84402a16d986e50a051d1bafb3231ca929879163 Mon Sep 17 00:00:00 2001 From: Gian Miguel Del Mundo Date: Fri, 27 Jun 2025 18:03:53 +0800 Subject: [PATCH 27/28] Updated post-identity-map filenames and corresponding URLs --- docs/endpoints/post-identity-map-v2.md | 207 ------------------ docs/endpoints/post-identity-map-v3.md | 196 +++++++++++++++++ docs/endpoints/post-identity-map.md | 163 +++++++------- docs/endpoints/summary-endpoints.md | 4 +- docs/getting-started/gs-permissions.md | 2 +- ...ation-advertiser-dataprovider-endpoints.md | 10 +- ...ration-advertiser-dataprovider-overview.md | 6 +- docs/ref-info/glossary-uid.md | 4 +- docs/ref-info/updates-doc.md | 2 +- 9 files changed, 297 insertions(+), 297 deletions(-) delete mode 100644 docs/endpoints/post-identity-map-v2.md create mode 100644 docs/endpoints/post-identity-map-v3.md diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md deleted file mode 100644 index 500f3fe24..000000000 --- a/docs/endpoints/post-identity-map-v2.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: POST /identity/map (v2) -description: Maps DII to raw UID2s and salt bucket IDs. -hide_table_of_contents: false -sidebar_position: 08 ---- - -import Link from '@docusaurus/Link'; - -# POST /identity/map (v2) - -Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information. - -Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). - -For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). - -## Version - -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 the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements. -::: - -## Batch Size and Request Parallelization Requirements - -Here's what you need to know: - -- The maximum request size is 1MB. -- To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch. -- Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. -- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
    Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). - -## Request Format - -`POST '{environment}/v2/identity/map'` - -For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md). - -:::important -You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). -::: - -### Path Parameters - -| Path Parameter | Data Type | Attribute | Description | -| :--- | :--- | :--- | :--- | -| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`
    Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). | - -:::note -The integration environment and the production environment require different API keys. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials). -::: - -### Unencrypted JSON Body Parameters - -:::important -You must include only **one** of the following four conditional parameters as a key-value pair in the JSON body of the request when encrypting it. -::: - -| Body Parameter | Data Type | Attribute | Description | -| :--- | :--- | :--- | :--- | -| `email` | string array | Conditionally Required | The list of email addresses to be mapped. | -| `email_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email addresses to be mapped. | -| `phone` | string array | Conditionally Required | The list of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | -| `phone_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | - -### Request Examples - -The following are unencrypted JSON request body examples for each parameter, one of which you should include in your requests to the `POST /identity/map` endpoint: - -```json -{ - "email":[ - "user@example.com", - "user2@example.com" - ] -} -``` -```json -{ - "email_hash":[ - "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", - "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU=" - ] -} -``` -```json -{ - "phone":[ - "+12345678901", - "+441234567890" - ] -} -``` -```json -{ - "phone_hash":[ - "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=" - ] -} -``` - -Here's an encrypted request example to the `POST /identity/map` endpoint for a phone number: - -```sh -echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/map [Your-Client-API-Key] [Your-Client-Secret] -``` - -For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). - -## Decrypted JSON Response Format - -:::note -The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted. -::: - -A successful decrypted response returns the raw UID2s and salt bucket IDs for the specified email addresses, phone numbers, or their respective hashes. - -```json -{ - "body":{ - "mapped": [ - { - "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "a30od4mNRd" - }, - { - "identifier": "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=", - "advertising_id": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=", - "bucket_id": "ad1ANEmVZ" - } - ] - }, - "status":"success" -} -``` - -If some identifiers are considered invalid, they are included in the response in an "unmapped" list. In this case, the response status is still "success". If all identifiers are mapped, the "unmapped" list is not included in the response. - -```json -{ - "body":{ - "mapped": [ - { - "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "a30od4mNRd" - } - ], - "unmapped": [ - { - "identifier": "some@malformed@email@hash", - "reason": "invalid identifier" - } - ] - }, - "status":"success" -} -``` - -If some identifiers have opted out from the UID2 ecosystem, the opted-out identifiers are moved to the "unmapped" list along with any invalid identifiers found. In this case, the response status is still "success". - -```json -{ - "body":{ - "mapped": [ - { - "identifier": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "a30od4mNRd" - } - ], - "unmapped": [ - { - "identifier": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", - "reason": "optout" - } - ] - }, - "status":"success" -} -``` - -### Response Body Properties - -The response body includes the properties shown in the following table. - -| Property | Data Type | Description | -| :--- | :--- | :--- | -| `identifier` | string | The email address, phone number, or respective hash specified in the request body. | -| `advertising_id` | string | The corresponding advertising ID (raw UID2). | -| `bucket_id` | string | The ID of the salt bucket used to generate the raw UID2. | - -### Response Status Codes - -The following table lists the `status` property values and their HTTP status code equivalents. - -| Status | HTTP Status Code | Description | -| :--- | :--- | :--- | -| `success` | 200 | The request was successful. The response will be encrypted. | -| `client_error` | 400 | The request had missing or invalid parameters.| -| `unauthorized` | 401 | The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested operation. | - -If the `status` value is anything other than `success`, the `message` field provides additional information about the issue. diff --git a/docs/endpoints/post-identity-map-v3.md b/docs/endpoints/post-identity-map-v3.md new file mode 100644 index 000000000..0d7a977b0 --- /dev/null +++ b/docs/endpoints/post-identity-map-v3.md @@ -0,0 +1,196 @@ +--- +title: POST /identity/map +description: Maps DII to raw UID2s. +hide_table_of_contents: false +sidebar_position: 08 +displayed_sidebar: docs +--- + +import Link from '@docusaurus/Link'; + +# POST /identity/map + +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when a raw UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old. + +Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). + +For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). + +## Version + +This documentation is for the latest version of this endpoint, version 3. + +If needed, documentation is also available for the previous version: see [POST /identity/map (v2)](post-identity-map.md). + +## Batch Size and Request Parallelization Requirements + +Here's what you need to know: + +- The maximum request size is 1MB. +- To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch. +- Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. +- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
    Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). + +## Request Format + +`POST '{environment}/v3/identity/map'` + +For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md). + +:::important +You must encrypt all requests using your secret. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). +::: + +### Path Parameters + +| Path Parameter | Data Type | Attribute | Description | +| :--- | :--- | :--- | :--- | +| `{environment}` | string | Required | Testing (integration) environment: `https://operator-integ.uidapi.com`
    Production environment: The best choice depends on where your users are based. For information about how to choose the best URL for your use case, and a full list of valid base URLs, see [Environments](../getting-started/gs-environments.md). | + +:::note +The integration environment and the production environment require different API keys. For information about getting credentials for each environment, see [Getting Your Credentials](../getting-started/gs-credentials.md#getting-your-credentials). +::: + +### Unencrypted JSON Body Parameters + +:::important +Include one or more of the following four parameters as key-value pairs in the JSON body of the request when encrypting it. +::: + +| Body Parameter | Data Type | Attribute | Description | +|:---------------|:----------------------------|:-----------------------| :--- | +| `email` | string array | Conditionally Required | The list of email addresses to be mapped. | +| `email_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email addresses to be mapped. | +| `phone` | string array | Conditionally Required | The list of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | +| `phone_hash` | string array | Conditionally Required | The list of [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hashes of [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone numbers to be mapped. | + + +### Request Examples + +The following are unencrypted JSON request body examples to the `POST /identity/map` endpoint: + +```json +{ + "email":[ + "user@example.com", + "user2@example.com" + ], + "phone":[ + "+12345678901", + "+441234567890" + ] +} +``` + +```json +{ + "email_hash":[ + "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=", + "KzsrnOhCq4tqbGFMsflgS7ig1QLRr0nFJrcrEIlOlbU=" + ], + "phone_hash":[ + "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "Rx8SW4ZyKqbPypXmswDNuq0SPxStFXBTG/yvPns/2NQ=" + ] +} +``` + +Here's an encrypted request example to the `POST /identity/map` endpoint for a phone number: + +```sh +echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v3/identity/map [YOUR_CLIENT_API_KEY] [YOUR_CLIENT_SECRET] +``` + +For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). + +## Decrypted JSON Response Format + +:::note +The response is encrypted only if the HTTP status code is 200. Otherwise, the response is not encrypted. +::: + +A successful decrypted response returns the current raw UID2s, previous raw UID2s, and refresh timestamps for the specified email addresses, phone numbers, or their respective hashes. + +The response arrays preserve the order of input arrays. Each element in the response array maps directly to the element at the same index in the corresponding request array. This ensures that you can reliably associate results with their corresponding inputs based on array position. + +Input values that cannot be mapped to a raw UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the DII is invalid or has been opted out from the UID2 ecosystem. In these cases, the response status is `success` but no raw UID2 is returned. + +The following example shows input and response. + +Input: + +```json +{ + "email": [ + "user@example.com" // Corresponding UID2 rotated in the last 90 days + "user2@example.com" // Corresponding UID2 rotated more than 90 days ago + "invalid email string" // Invalid identifier + "optout@example.com" // DII is opted out + ] +} +``` + +Response: + +```json +{ + "body":{ + "email": [ + { + "u": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "p": "EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=", + "r": 1735689600000 + }, + { + "u": "IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ=", + "p": null, + "r": 1735862400000 + }, + { "e": "invalid identifier" }, + { "e": "optout" } + ], + "email_hash": [], + "phone": [], + "phone_hash": [] + }, + "status":"success" +} +``` + +### Response Body Properties + +The response body includes one or more of the properties shown in the following table. + +| Body Parameter | Data Type | Description | +|:---------------|:----------------------------|:------------------------------------------------------------------------------------------------| +| `email` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of emails in the request. | +| `email_hash` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of email hashes in the request. | +| `phone` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of phone numbers in the request. | +| `phone_hash` | array of mapped DII objects | The list of mapped DII objects corresponding to the list of phone number hashes in the request. | + + +For successfully mapped DII, the mapped object includes the properties shown in the following table. + +| Property | Data Type | Description | +|:---------|:-----------|:--------------------------------------------------------------------------------------------------------------------------------------| +| `u` | string | The raw UID2 corresponding to the email or phone number provided in the request. | +| `p` | string | One of the following:
    • If the current raw UID2 has been rotated in the last 90 days: the previous value.
    • If the current raw UID2 is older than 90 days: `Null`.
    | +| `r` | number | The Unix timestamp (in milliseconds) that indicates when the raw UID2 can be refreshed. | + +For unsuccessfully mapped input values, the mapped object includes the properties shown in the following table. + +| Property | Data Type | Description | +|:---------|:----------|:-----------------------------------------------------------------------------------------------------------------| +| `e` | string | The reason for being unable to map the DII to a raw UID2. One of two possible values:
    • `optout`
    • `invalid identifier`
    | + +### Response Status Codes + +The following table lists the `status` property values and their HTTP status code equivalents. + +| Status | HTTP Status Code | Description | +| :--- | :--- | :--- | +| `success` | 200 | The request was successful. The response will be encrypted. | +| `client_error` | 400 | The request had missing or invalid parameters.| +| `unauthorized` | 401 | The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested operation. | + +If the `status` value is anything other than `success`, the `message` field provides additional information about the issue. diff --git a/docs/endpoints/post-identity-map.md b/docs/endpoints/post-identity-map.md index a3633bc36..ebb76227e 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -1,16 +1,15 @@ --- -title: POST /identity/map -description: Maps DII to raw UID2s. +title: POST /identity/map (v2) +description: Maps DII to raw UID2s and salt bucket IDs. hide_table_of_contents: false sidebar_position: 08 -displayed_sidebar: docs --- import Link from '@docusaurus/Link'; -# POST /identity/map +# POST /identity/map (v2) -Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s. You can also use this endpoint to check for updates to opt-out information, check when a raw UID2 can be refreshed, or view the previous UID2 if the current UID2 is less than 90 days old. +Maps multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. You can also use this endpoint to check for updates to opt-out information. Used by: This endpoint is used mainly by advertisers and data providers. For details, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md). @@ -18,9 +17,11 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User ## Version -This documentation is for the latest version of this endpoint, version 3. +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-v3.md). -If needed, documentation is also available for the previous version: see [POST /identity/map (v2)](post-identity-map-v2.md). +:::note +If you're using the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements. +::: ## Batch Size and Request Parallelization Requirements @@ -29,11 +30,11 @@ Here's what you need to know: - The maximum request size is 1MB. - To map a large number of email addresses, phone numbers, or their respective hashes, send them in *sequential* batches with a maximum batch size of 5,000 items per batch. - Unless you are using a Private Operator, do not send batches in parallel. In other words, use a single HTTP connection and send batches of hashed or unhashed directly identifying information (DII) values consecutively, without creating multiple parallel connections. -- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
    Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). +- Be sure to store mappings of email addresses, phone numbers, or their respective hashes.
    Not storing mappings could increase processing time drastically when you have to map millions of email addresses or phone numbers. Recalculating only those mappings that actually need to be updated, however, reduces the total processing time because only about 1/365th of raw UID2s need to be updated daily. See also [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md) and [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). ## Request Format -`POST '{environment}/v3/identity/map'` +`POST '{environment}/v2/identity/map'` For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md). @@ -54,40 +55,46 @@ The integration environment and the production environment require different
  • If the current raw UID2 has been rotated in the last 90 days: the previous value.
  • If the current raw UID2 is older than 90 days: `Null`.
    • | -| `r` | number | The Unix timestamp (in milliseconds) that indicates when the raw UID2 can be refreshed. | - -For unsuccessfully mapped input values, the mapped object includes the properties shown in the following table. - -| Property | Data Type | Description | -|:---------|:----------|:-----------------------------------------------------------------------------------------------------------------| -| `e` | string | The reason for being unable to map the DII to a raw UID2. One of two possible values:
    • `optout`
    • `invalid identifier`
    | +| Property | Data Type | Description | +| :--- | :--- | :--- | +| `identifier` | string | The email address, phone number, or respective hash specified in the request body. | +| `advertising_id` | string | The corresponding advertising ID (raw UID2). | +| `bucket_id` | string | The ID of the salt bucket used to generate the raw UID2. | ### Response Status Codes diff --git a/docs/endpoints/summary-endpoints.md b/docs/endpoints/summary-endpoints.md index fb3a25178..40cc94472 100644 --- a/docs/endpoints/summary-endpoints.md +++ b/docs/endpoints/summary-endpoints.md @@ -38,7 +38,7 @@ The latest identity map integration uses the following endpoint: | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | -| [POST /identity/map](post-identity-map.md) | Maps raw UID2s, previous raw UID2s, and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | +| [POST /identity/map](post-identity-map-v3.md) | Maps raw UID2s, previous raw UID2s, and refresh timestamps for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | ### Earlier Identity Map Endpoints (V2) @@ -47,7 +47,7 @@ The following endpoints are part of the earlier identity map integration (versio | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | | [POST /identity/buckets](post-identity-buckets.md) | Monitors rotated salt buckets using their last updated timestamp. | Required | Required | -| [POST /identity/map (v2)](post-identity-map-v2.md) | Maps raw UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | +| [POST /identity/map (v2)](post-identity-map.md) | Maps raw UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | ## Opt-Out Status diff --git a/docs/getting-started/gs-permissions.md b/docs/getting-started/gs-permissions.md index a8d18950c..2ff27e0f2 100644 --- a/docs/getting-started/gs-permissions.md +++ b/docs/getting-started/gs-permissions.md @@ -26,4 +26,4 @@ The following table lists the key permissions, the types of participants that co | Generator | Publishers | Permission to call the [POST /token/generate](../endpoints/post-token-generate.md), [POST /token/validate](../endpoints/post-token-validate.md), and [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints, to generate UID2 tokens from DII and to refresh them, using one of these integration methods:
    • A Prebid integration
    • The SDK for JavaScript
    • An integration that directly calls the applicable API endpoints for retrieving and managing UID2 tokens.
    | | Bidder | DSPs | Permission to decrypt UID2 tokens coming in from the bidstream from publishers into raw UID2s for bidding purposes. | | Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following:
    • Encrypt raw UID2s into UID2 tokens for sharing with another authorized sharing participant, using a UID2 SDK or Snowflake
    • Decrypt UID2 tokens received from another authorized sharing participant into raw UID2s.
    | -| Mapper | Advertisers
    Data Providers | Permission to call the following endpoints to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s, and refresh timestamps:
    • [POST /identity/map](../endpoints/post-identity-map.md) (latest version)
    • The earlier (version 2) identity mapping endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md).
    | +| Mapper | Advertisers
    Data Providers | Permission to call the following endpoints to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s, previous raw UID2s, and refresh timestamps:
    • [POST /identity/map](../endpoints/post-identity-map-v3.md) (latest version)
    • The earlier (version 2) identity mapping endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map.md) and [POST /identity/buckets](../endpoints/post-identity-buckets.md).
    | diff --git a/docs/guides/integration-advertiser-dataprovider-endpoints.md b/docs/guides/integration-advertiser-dataprovider-endpoints.md index 358c4c593..fc5d2eb30 100644 --- a/docs/guides/integration-advertiser-dataprovider-endpoints.md +++ b/docs/guides/integration-advertiser-dataprovider-endpoints.md @@ -62,8 +62,8 @@ DII refers to a user's normalized email address or phone number, or the normaliz | Step | Endpoint | Description | | --- | --- | --- | -| 1-a | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) request | Send a request containing DII to the identity mapping endpoint. | -| 1-b | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.
    The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). | +| 1-a | [POST /identity/map (v2)](../endpoints/post-identity-map.md) request | Send a request containing DII to the identity mapping endpoint. | +| 1-b | [POST /identity/map (v2)](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.
    The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [5: Monitor for salt bucket rotations related to your stored raw UID2s](#5-monitor-for-salt-bucket-rotations-for-your-stored-raw-uid2s). | ### 2: Store Raw UID2s and Salt Bucket IDs @@ -105,8 +105,8 @@ The following table shows the steps for checking for salt bucket rotation. | --- | --- | --- | | 5-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the `POST /identity/buckets` endpoint for all salt buckets that have changed since a specific timestamp. | | 5-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The `POST /identity/buckets` endpoint returns a list of `bucket_id` and `last_updated` timestamps. | -| 5-c | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.
    If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the `POST /identity/map (v2)` endpoint for a new raw UID2. | -| 5-d | [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) | Store the new values returned for `advertising_id` and `bucket_id`. | +| 5-c | [POST /identity/map (v2)](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.
    If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the `POST /identity/map (v2)` endpoint for a new raw UID2. | +| 5-d | [POST /identity/map (v2)](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. | #### Determine whether the salt bucket has been rotated @@ -126,7 +126,7 @@ It's important to honor user opt-out status. Periodically, monitor for opt-out s There are two ways that you can check with the UID2 Operator Service to make sure you have the latest opt-out information: -- Call the [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. +- Call the [POST /identity/map (v2)](../endpoints/post-identity-map.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. - Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. diff --git a/docs/guides/integration-advertiser-dataprovider-overview.md b/docs/guides/integration-advertiser-dataprovider-overview.md index bc0179b04..e2536c6c8 100644 --- a/docs/guides/integration-advertiser-dataprovider-overview.md +++ b/docs/guides/integration-advertiser-dataprovider-overview.md @@ -49,7 +49,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:
    • One of these UID2 SDKs:
      • Python SDK: [Map DII to Raw UID2s](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s)
      • Java SDK: [Usage for Advertisers/Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers)
    • Snowflake: [Map DII](integration-snowflake.md#map-dii)
    • AWS Entity Resolution: [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md)
    • HTTP endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md)
    | +| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | Use any of the following options to map DII to raw UID2s:
    • One of these UID2 SDKs:
      • Python SDK: [Map DII to Raw UID2s](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s)
      • Java SDK: [Usage for Advertisers/Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers)
    • Snowflake: [Map DII](integration-snowflake.md#map-dii)
    • AWS Entity Resolution: [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md)
    • HTTP endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map.md)
    | | [2: Store Raw UID2s and Salt Bucket IDs](#2-store-raw-uid2s-and-salt-bucket-ids) | 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). | @@ -85,7 +85,7 @@ To generate raw UID2s, use one of the following options: - AWS Entity Resolution: See [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md). -- HTTP endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md). For details, see [Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii). +- HTTP endpoints: [POST /identity/map (v2)](../endpoints/post-identity-map.md). For details, see [Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii). ### 2: Store Raw UID2s and Salt Bucket IDs @@ -150,7 +150,7 @@ It's important to honor user opt-out status. Periodically, monitor for opt-out s There are two ways that you can check with the UID2 Operator Service to make sure you have the latest opt-out information: -- Call the [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. +- Call the [POST /identity/map (v2)](../endpoints/post-identity-map.md) endpoint to check for opt-outs. If the DII has been opted out, no raw UID2 is generated. - Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. diff --git a/docs/ref-info/glossary-uid.md b/docs/ref-info/glossary-uid.md index e31e6480b..2869c7e65 100644 --- a/docs/ref-info/glossary-uid.md +++ b/docs/ref-info/glossary-uid.md @@ -417,11 +417,11 @@ import Link from '@docusaurus/Link';
    Salt bucket
    A salt bucket is used to manage secret salt values, used to generate raw UID2s or UID2 tokens, over time. Each bucket contains a single current salt value, which remains active for approximately one year before being rotated to a new value. Buckets can be updated independently of one another.
    There are just over one million salt buckets, and each email address or phone number is assigned to a specific bucket in a deterministic manner. However, this assignment is not permanent; it might change when the bucket's current salt is rotated to a new value.
    -
    In versions of the [POST /identity/map](../endpoints/post-identity-map.md) endpoint earlier than version 3, such as [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md), the endpoint returns salt bucket IDs. In v3 and later, salt bucket information is not needed.
    +
    In versions of the [POST /identity/map](../endpoints/post-identity-map-v3.md) endpoint earlier than version 3, such as [POST /identity/map (v2)](../endpoints/post-identity-map.md), the endpoint returns salt bucket IDs. In v3 and later, salt bucket information is not needed.
    Salt bucket ID
    A salt bucket ID is a unique string of characters that identifies a specific salt bucket. The salt bucket ID can be used to check which salt buckets have recently had their salt values updated, indicating which emails or phone numbers need their raw UID2 values regenerated.
    -
    In versions of the [POST /identity/map](../endpoints/post-identity-map.md) endpoint earlier than version 3, such as [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md), the endpoint returns salt bucket IDs. In v3 and later, salt bucket information is not needed.
    +
    In versions of the [POST /identity/map](../endpoints/post-identity-map-v3.md) endpoint earlier than version 3, such as [POST /identity/map (v2)](../endpoints/post-identity-map.md), the endpoint returns salt bucket IDs. In v3 and later, salt bucket information is not needed.
    For an example of a salt bucket ID, see the response to the `POST /v2/identity/buckets` endpoint: Decrypted JSON Response Format. If you're using `POST /v3/identity/map`, you don't need to use `POST /v2/identity/buckets` at all.
    Salted hash
    diff --git a/docs/ref-info/updates-doc.md b/docs/ref-info/updates-doc.md index b25bce028..dffffec29 100644 --- a/docs/ref-info/updates-doc.md +++ b/docs/ref-info/updates-doc.md @@ -422,7 +422,7 @@ For details, see [UID2 Hashing Tool](../getting-started/gs-normalization-encodin February 28, 2024 -The Java SDK now supports Advertisers and Data Providers wanting to use the [POST /identity/map (v2)](../endpoints/post-identity-map-v2.md) endpoint. +The Java SDK now supports Advertisers and Data Providers wanting to use the [POST /identity/map (v2)](../endpoints/post-identity-map.md) endpoint. For details, see the updated documentation in the *SDK for Java Reference Guide*: [Usage for Advertisers and Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers). From 8278704b3ea505da3762caa6450a02952d00d442 Mon Sep 17 00:00:00 2001 From: Gian Miguel Del Mundo Date: Fri, 27 Jun 2025 18:11:34 +0800 Subject: [PATCH 28/28] Fixed broken link in sidebar --- sidebars.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sidebars.js b/sidebars.js index 67b410b77..8b4321c61 100644 --- a/sidebars.js +++ b/sidebars.js @@ -325,11 +325,11 @@ const fullSidebar = [ label: 'POST /identity/map', link: { type: 'doc', - id: 'endpoints/post-identity-map', + id: 'endpoints/post-identity-map-v3', }, collapsed: true, items: [ - 'endpoints/post-identity-map-v2', + 'endpoints/post-identity-map', ], }, 'endpoints/post-optout-status',