diff --git a/docs/endpoints/post-identity-map-v2.md b/docs/endpoints/post-identity-map-v2.md new file mode 100644 index 000000000..53674fe68 --- /dev/null +++ b/docs/endpoints/post-identity-map-v2.md @@ -0,0 +1,203 @@ +--- +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 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 + +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..c1dfd1eb7 100644 --- a/docs/endpoints/post-identity-map.md +++ b/docs/endpoints/post-identity-map.md @@ -1,20 +1,27 @@ --- title: POST /identity/map -description: Maps DII to raw UID2s and salt bucket IDs. +description: Maps DII to 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 and salt bucket IDs. 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 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). 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 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 Here's what you need to know: @@ -22,11 +29,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 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 -`POST '{environment}/v2/identity/map'` +`POST '{environment}/v3/identity/map'` For authentication details, see [Authentication and Authorization](../getting-started/gs-auth.md). @@ -47,46 +54,40 @@ The integration environment and the production environment require different
  • 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/docs/getting-started/gs-permissions.md b/docs/getting-started/gs-permissions.md index 4a76db34e..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: | | 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: | -| 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](../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/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: | +| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | Use any of the following options to map DII to raw UID2s: | | [2: Store Raw UID2s and 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/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..f4112b91f --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/endpoints/post-identity-map-v2.md @@ -0,0 +1,199 @@ +--- +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 3fec46ef5..35cfdce83 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,199 +1,10 @@ --- title: POST /identity/map -description: DII を raw UID2 とソルトバケット ID にマッピング。 +description: Maps DII to UID2s. 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 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 を生成/リフレッシュする権限: | | Bidder | DSPs | パブリッシャーからのビッドストリームから送られてくる UID2 Token を、入札目的で raw UID2 に復号化する権限。 | | Sharer | UID2 sharing に参加するすべての参加者タイプ。詳細は [UID2 Sharing: Overview](../sharing/sharing-overview.md) を参照してください。 | 以下両方の権限: | -| 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 にマッピングするには、以下のオプションのいずれかをします: | +| [1: Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) | DII を raw UID2 にマッピングするには、以下のオプションのいずれかをします: | | [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= diff --git a/sidebars.js b/sidebars.js index 637ae41a6..67b410b77 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', ], }, @@ -399,6 +410,7 @@ const sidebars = { 'guides/dsp-guide', 'endpoints/post-identity-buckets', 'endpoints/post-identity-map', + 'endpoints/post-identity-map-v2', 'endpoints/post-optout-status' ),