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' ),