diff --git a/.gitignore b/.gitignore index 72dfb7711..f252b79f1 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ npm-debug.log* yarn-debug.log* yarn-error.log* .aider* +.idea/ diff --git a/docs/endpoints/post-identity-buckets-new.md b/docs/endpoints/post-identity-buckets-new.md new file mode 100644 index 000000000..9708fe0cf --- /dev/null +++ b/docs/endpoints/post-identity-buckets-new.md @@ -0,0 +1,115 @@ +--- +title: POST /identity/buckets +description: Monitors rotated salt buckets. +hide_table_of_contents: false +sidebar_position: 07 +--- + +import Link from '@docusaurus/Link'; + +# POST /identity/buckets + +Monitors rotated salt buckets. + +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'` + +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 the following parameter as a key-value pair in the JSON body of a request when encrypting it. +::: + +| Body Parameter | Data Type | Attribute | Description | Format | +| :--- | :--- | :--- | :--- | :--- | +| `since_timestamp` | date-time or integer | Required | Specify the date and time to which to compare the last updated UTC timestamps of the buckets to be returned. | ISO 8601 format:
`YYYY-MM-DDThh:mm:ss` | + +### Request Examples + +The following is an unencrypted JSON request body example, which you should include in your identity bucket rotation requests: + +```json +{ + "since_timestamp": "2022-06-01T13:00:00" +} +``` +Here's an encrypted identity bucket rotation request example: + +```sh +echo '{"since_timestamp": "2023-04-19T13:00:00"}' | python3 uid2_request.py https://prod.uidapi.com/v2/identity/buckets [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 a list of salt bucket IDs and the timestamps of their last updates. + +```json +{ + "body":[ + { + "bucket_id": "a30od4mNRd", + "last_updated": "2022-06-05T22:52:03.109" + }, + { + "bucket_id": "aJ0jMvw9Z8", + "last_updated": "2022-06-06T22:52:01.828" + }, + { + "bucket_id": "aeRQ9L7wRN", + "last_updated": "2022-06-01T22:52:02.574" + } + ], + "status":"success" +} +``` +### Response Body Properties + +The response body includes the properties shown in the following table. + +| Property | Format | Description | +| :--- | :--- | :--- | +| `bucket_id` | string | The salt bucket ID. | +| `last_updated` | date-time | The UTC timestamp of the last time the bucket salt was rotated. | + +### 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-new.md b/docs/endpoints/post-identity-map-new.md new file mode 100644 index 000000000..bb7e96b4a --- /dev/null +++ b/docs/endpoints/post-identity-map-new.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-v2-new.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: | +| `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: | + +### 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-v2-new.md b/docs/endpoints/post-identity-map-v2-new.md new file mode 100644 index 000000000..677dfd991 --- /dev/null +++ b/docs/endpoints/post-identity-map-v2-new.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) + +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-new.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-v2.md b/docs/endpoints/post-identity-map-v2.md new file mode 100644 index 000000000..500f3fe24 --- /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) + +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/summary-endpoints-new.md b/docs/endpoints/summary-endpoints-new.md new file mode 100644 index 000000000..df01648ef --- /dev/null +++ b/docs/endpoints/summary-endpoints-new.md @@ -0,0 +1,60 @@ +--- +title: UID2 Endpoints - Summary +description: Summary of the endpoints available in the UID2 service. +hide_table_of_contents: false +sidebar_position: 01 +displayed_sidebar: docs +--- + +import Link from '@docusaurus/Link'; + +# UID2 Endpoints: Summary + +All UID2 endpoints require a client secret for encrypting API requests (except [POST /token/refresh](post-token-refresh.md) requests) and decrypting responses. For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). + +## UID2 Tokens + +The following endpoints are for retrieving and managing UID2 tokens (identity tokens, advertising tokens), and are used mainly by publishers. + +| Endpoint | Description | Request Encryption | Response Decryption | +| :--- | :--- | :--- | :--- | +| [POST /token/generate](post-token-generate.md) | Requests a UID2 token generated from a user's DII (email address or phone number). If the DII is valid, and the user has not opted out of UID2, this operation returns a UID2 token and associated values. | Required | Required | +| [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 Map + +The following endpoints are used by advertisers and third-party data providers. Publishers do not need to use these endpoints. + +### Latest Identity Map Endpoint (V3) + +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. + +:::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-new.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) + +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-new.md) | Monitors rotated salt buckets using their last updated timestamp. | Required | Required | +| [POST /identity/map (v2)](post-identity-map-v2-new.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 + +The following endpoint can be used by advertisers, third-party data providers, DSPs, and sharers. Publishers do not need to use this endpoint. + +For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). + +| Endpoint | Description | Request Encryption | Response Decryption | +| :--- | :--- | :--- | :--- | +| [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-faqs-new.md b/docs/getting-started/gs-faqs-new.md new file mode 100644 index 000000000..9d3245691 --- /dev/null +++ b/docs/getting-started/gs-faqs-new.md @@ -0,0 +1,315 @@ +--- +title: FAQs +description: Common questions about implementing UID2. +hide_table_of_contents: false +sidebar_position: 20 +--- + +import Link from '@docusaurus/Link'; +import ExampleTokenInBidstream from '../snippets/_example-token-in-bidstream.mdx'; + +# Frequently Asked Questions + +Frequently asked questions for UID2 in this document are grouped by audience, into the following general categories: + +- [FAQs—General](#faqsgeneral) +- [FAQs for Publishers](#faqs-for-publishers) +- [FAQs for Advertisers and Data Providers](#faqs-for-advertisers-and-data-providers) +- [FAQs for DSPs](#faqs-for-dsps) + +The following additional FAQ information for publishers is also available: +- [FAQs for Mobile Integrations](../guides/integration-mobile-overview.md#faqs-for-mobile-integrations) + +## FAQs—General + +Here are some frequently asked questions regarding the UID2 framework. + +- [Will all integration partners in the EUID infrastructure (SSPs, third-party data providers, measurement providers) be automatically integrated with UID2?](#will-all-integration-partners-in-the-euid-infrastructure-ssps-third-party-data-providers-measurement-providers-be-automatically-integrated-with-uid2) +- [Can users opt out of targeted advertising tied to their UID2?](#can-users-opt-out-of-targeted-advertising-tied-to-their-uid2) +- [When I send DII to UID2, does UID2 store the information?](#when-i-send-dii-to-uid2-does-uid2-store-the-information) +- [Does UID2 allow the processing of HIPAA-regulated data?](#does-uid2-allow-the-processing-of-hipaa-regulated-data) +- [Should I use a Public Operator or a Private Operator?](#should-i-use-a-public-operator-or-a-private-operator) + +:::note +For FAQs relating to mobile publisher integrations, see [FAQs for Mobile Integrations](../guides/integration-mobile-overview.md#faqs-for-mobile-integrations). +::: + +#### Will all integration partners in the EUID infrastructure (SSPs, third-party data providers, measurement providers) be automatically integrated with UID2? + +No. UID2 has its own framework, which is separate from EUID. As such, paperwork relating to accessing and using the EUID framework does not automatically grant usage and access to the UID2 framework. New contracts are required to be signed for UID2. + +#### Can users opt out of targeted advertising tied to their UID2? + +Yes. Through the [Transparency and Control Portal](https://www.transparentadvertising.com/), users can opt out from being served targeted ads tied to their UID2. Each request is distributed through the UID2 Opt-Out Service, and UID2 Operators make the opt-out information available to all relevant participants. + +#### When I send DII to UID2, does UID2 store the information? + +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. + +#### Does UID2 allow the processing of HIPAA-regulated data? + +No. UID2 participants must not generate UID2s from Protected Health Information, as defined by the Health Insurance Portability and Accountability Act (HIPAA), even if they have obtained consent to engage in marketing with respect to such data. + +#### Should I use a Public Operator or a Private Operator? + +For most participants, Public Operator is the simplest solution. A Public Operator integration is a much easier option than hosting your own Private Operator. Having a Private Operator instance has some advantages, but adds extra complexities and costs. + +The best choice depends on your unique scenario and needs. For more information to help you arrive at a decision, refer to the following: + +- [The UID2 Operator](../ref-info/ref-operators-public-private.md) + +- [UID2 Private Operator Integration Overview](../guides/integration-options-private-operator.md) + +## FAQs for Publishers + +Here are some frequently asked questions for publishers using the UID2 framework. + +- [How can I test that the DII sent and the returned token match up?](#how-can-i-test-that-the-dii-sent-and-the-returned-token-match-up) +- [Do I need to decrypt tokens?](#do-i-need-to-decrypt-tokens) +- [How will I be notified of user opt-out?](#how-will-i-be-notified-of-user-opt-out) +- [Where should I make token generation calls—from the server side or the client side?](#where-should-i-make-token-generation-callsfrom-the-server-side-or-the-client-side) +- [Can I make token refresh calls from the client side?](#can-i-make-token-refresh-calls-from-the-client-side) +- [If I choose to manually refresh the token, how will I know when to refresh the token?](#if-i-choose-to-manually-refresh-the-token-how-will-i-know-when-to-refresh-the-token) +- [How can I test the refresh token workflow?](#how-can-i-test-the-refresh-token-workflow) +- [What is the uniqueness and rotation policy for UID2 tokens?](#what-is-the-uniqueness-and-rotation-policy-for-uid2-tokens) +- [What does a UID2 token look like in the bidstream?](#what-does-a-uid2-token-look-like-in-the-bidstream) +- [Can I integrate UID2 with Single Sign-On (SSO)?](#can-i-integrate-uid2-with-single-sign-on-sso) + +#### How can I test that the DII sent and the returned token match up? + +You can use the [POST /token/validate](../endpoints/post-token-validate.md) endpoint to check whether the DII that you are sending through [POST /token/generate](../endpoints/post-token-generate.md) is valid. `POST /token/validate` is used primarily for testing purposes. + +For details, see [Using POST /token/validate to Test](../endpoints/post-token-validate.md#using-post-tokenvalidate-to-test). + +#### Do I need to decrypt tokens? + +No, publishers do not need to decrypt UID2 tokens. However, if you want to get access to [raw UID2s](../ref-info/glossary-uid.md#gl-raw-uid2) for internal use only, please work with UID2 support to gain access. + +#### How will I be notified of user opt-out? + +If the user has opted out, the API response notifies you in either of these cases: +- When you generate the UID2 token by a call to the [POST /token/generate](../endpoints/post-token-generate.md) endpoint, either directly or via one of the UID2 SDKs, using the required `optout_check` parameter with a value of `1`. +- When you refresh the UID2 token by a call to the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint, either directly or via one of the UID2 SDKs. + +#### Where should I make token generation calls—from the server side or the client side? + +You can generate UID2 tokens from either the client side or the server side. For more information, see: +- Generating tokens from the client side using Prebid.js: [UID2 Client-Side Integration Guide for Prebid.js](../guides/integration-prebid-client-side.md). +- Generating tokens from the server side using Prebid.js: [UID2 Client-Server Integration Guide for Prebid.js](../guides/integration-prebid-client-server.md). +- Other server-side options: [Publisher Integrations](../guides/summary-guides.md#publisher-integrations). + +#### Can I make token refresh calls from the client side? + +Yes. The [POST /token/refresh](../endpoints/post-token-refresh.md) can be called from the client side (for example, a browser or a mobile app) because it does not require using an API key. + +#### If I choose to manually refresh the token, how will I know when to refresh the token? + +The recommended refresh interval is hourly. + +To determine when to refresh, you can use the timestamp of the `refresh_from` field in the response to the [POST /token/generate](../endpoints/post-token-generate.md) endpoint (see [Successful Response](../endpoints/post-token-generate.md#successful-response)) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint (see [Successful Response With Tokens](../endpoints/post-token-refresh.md#successful-response-with-tokens)). + +You could also use one of the SDKs that has a function to check if token refresh is needed. + +For details, see [Recommended Token Refresh Frequency](../ref-info/ref-tokens.md#recommended-token-refresh-frequency) and [Managing Token Refresh with an SDK](../ref-info/ref-tokens.md#managing-token-refresh-with-an-sdk). + +#### How can I test the refresh token workflow? + +You can use the `refresh-optout@example.com` email address or the `+00000000002` phone number to test your token refresh workflow. Using either parameter value in a request always generates an identity response with a `refresh_token` that results in a logout response. + +:::tip +To get the normalized, hashed, and Base64-encoded hashed values for any email address, or the hashed and Base64-encoded hashed values for a phone number, you can use the hashing tool: see [UID2 Hashing Tool](gs-normalization-encoding.md#uid2-hashing-tool). +::: + +The procedure is a little different depending on whether or not you are using an SDK. + +##### With SDK: + +1. Depending on whether the DII is an email address or a phone number, send a [POST /token/generate](../endpoints/post-token-generate.md) request using one of the following values: + - `email` value: `refresh-optout@example.com`. + - `email_hash` value: The hashed and Base64-encoded value for `refresh-optout@example.com`, which is `NaNI8RU0bL1Jpp1jJLC5aJO/lchc6gGhgXQIAwJ7cV4=`. + - `phone` value: `+00000000002`. + - `phone_hash` value: The hashed and Base64-encoded value for `+00000000002`, which is `0VoxsIuk88qt7TnZaTC//C9Vur3pR1zBMIr1cJe7xjE=`. + +2. Wait until the SDK's [background auto-refresh](../sdks/sdk-ref-javascript.md#background-token-auto-refresh) attempts to refresh the advertising token (this can take several hours) and observe the refresh attempt fail with the `OPTOUT` status. At this point the SDK also clears the first-party cookie. + +##### Without SDK: + +1. Depending on whether the DII is an email address or a phone number, send a [POST /token/generate](../endpoints/post-token-generate.md) request using one of the following values: + - `email` value: `refresh-optout@example.com`. + - `email_hash` value: The hashed and Base64-encoded value for `refresh-optout@example.com`, which is `NaNI8RU0bL1Jpp1jJLC5aJO/lchc6gGhgXQIAwJ7cV4=`. + - `phone` value: `+00000000002`. + - `phone_hash` value: The hashed and Base64-encoded value for `+00000000002`, which is `0VoxsIuk88qt7TnZaTC//C9Vur3pR1zBMIr1cJe7xjE=`. + +2. Store the returned `refresh_token` for use in the following step. + +3. Send a [POST /token/refresh](../endpoints/post-token-refresh.md) request with the `refresh_token` (saved in step 2) as the `token` value.
The body response should be empty, and the `status` value should be set to `optout` because the `refresh-optout@example.com` email and the `+00000000002` phone number always result in a logged-out user. + +#### What is the uniqueness and rotation policy for UID2 tokens? + +The UID2 service encrypts UID2 tokens using random initialization vectors. The UID2 token is unique for a given user as the user browses the internet. This means that every time a UID2 token is generated, the token is always different, even for the same underlying raw UID2. Every time the token is refreshed, a new token is generated and encrypted. + +#### What does a UID2 token look like in the bidstream? + +There are many ways to approach UID2 implementation. Here is one example of a code snippet showing how a UID2 token is passed in the bidstream: + + + +#### Can I integrate UID2 with Single Sign-On (SSO)? + +Yes. With popular SSO integration options such as Sign in with Google, Facebook Login, Sign in with Apple, or OpenPass, you can retrieve the email address and use it to generate a UID2. + +For details, see [Publisher Integration with SSO Providers](/docs/ref-info/ref-integration-sso-providers.md). + +## FAQs for Advertisers and Data Providers + +Here are some frequently asked questions for advertisers and data providers using the UID2 framework. + +- [How do I know when to refresh a raw UID2?](#how-do-i-know-when-to-refresh-a-raw-uid2) +- [How often should UID2s be refreshed for incremental updates?](#how-often-should-uid2s-be-refreshed-for-incremental-updates) +- [How should I generate the SHA-256 of DII for mapping?](#how-should-i-generate-the-sha-256-of-dii-for-mapping) +- [Should I store mapping of email addresses, phone numbers, or corresponding hashes to raw UID2s in my own datasets?](#should-i-store-mapping-of-email-addresses-phone-numbers-or-corresponding-hashes-to-raw-uid2s-in-my-own-datasets) +- [How should I handle user opt-outs?](#how-should-i-handle-user-opt-outs) +- [Does the same DII always result in the same raw UID2?](#does-the-same-dii-always-result-in-the-same-raw-uid2) +- [If two operators process the same DII, are the results the same?](#if-two-operators-process-the-same-dii-are-the-results-the-same) + +#### How do I know when to refresh a raw UID2? + +The V3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 may refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data. + +To determine whether to refresh a raw UID2: + +1. Compare the current time with the refresh timestamp (`r` field) you stored from the [POST /identity/map](../endpoints/post-identity-map.md) response. +2. If the current time is greater than or equal to the refresh timestamp, regenerate the raw UID2 by calling the identity map endpoint again with the same DII. + +:::note +We recommend checking for refresh opportunities daily. It is guaranteed that the raw UID2 won't refresh before the indicated timestamp. Afterward the UID2 has a chance to rotate. +::: + + +#### How often should UID2s be refreshed for incremental updates? + +The recommended cadence for updating audiences is daily. + +A raw UID2 for a specific user changes at least once per year as part of the UID2 rotation process. The V3 Identity Map API provides refresh timestamps that indicate when each raw UID2 may refresh. We recommend checking these timestamps daily to ensure your UID2s remain current and valid for audience targeting. + +#### How should I generate the SHA-256 of DII for mapping? + +The system should follow the [email normalization rules](gs-normalization-encoding.md#email-address-normalization) and hash without salting. + +#### Should I store mapping of email addresses, phone numbers, or corresponding hashes to raw UID2s in my own datasets? + +Yes. Not storing mappings may 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. + +:::important +Unless you are using a Private Operator, you must map email addresses, phone numbers, or hashes consecutively, using a single HTTP connection, with a maximum batch size of 5,000 items per batch. In other words, do your mapping without creating multiple parallel connections. +::: + +#### How should I handle user opt-outs? + +When a user opts out of UID2-based targeted advertising through the [Transparency and Control Portal](https://www.transparentadvertising.com/), the opt-out signal is sent to DSPs and publishers, who handle opt-outs at bid time. We recommend that advertisers and data providers regularly check whether a user has opted out, via the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. + +Advertisers and data providers can also check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. + +If a user opts out through your website, you should follow your internal procedures for handling the opt-out. For example, you might choose not to generate a UID2 for that user. + +#### Does the same DII always result in the same raw UID2? + +In general yes, the process of generating a raw UID2 from DII is the same, and results in the same value, no matter who sent the request. If two UID2 participants were to send the same email address to the [POST /identity/map](../endpoints/post-identity-map.md) endpoint at the same time, they would both get the same raw UID2 in response. + +However, there is a variable factor, which is the secret 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. + +For more information, see [Monitor for Raw UID2 Refresh](../guides/integration-advertiser-dataprovider-overview.md#5-monitor-for-raw-uid2-refresh) in the *Advertiser/Data Provider Integration Guide*. + +#### 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. + +The result is the same, regardless of the Operator and whether it's a Private Operator or a Public Operator. + +The timing is important only because of salt rotation. If the salt value changes between one request and another, the result is a different raw UID2. + +However, if a publisher sends DII in a request for a UID2 token, via the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint or via an SDK, the resulting UID2 token contains the same encrypted raw UID2, but the token itself is always unique. + +## FAQs for DSPs + +Here are some frequently asked questions for demand-side platforms (DSPs). + +- [How do I know which decryption key to apply to a UID2?](#how-do-i-know-which-decryption-key-to-apply-to-a-uid2) +- [Where do I get the decryption keys?](#where-do-i-get-the-decryption-keys) +- [How many decryption keys may be present in memory at any point?](#how-many-decryption-keys-may-be-present-in-memory-at-any-point) +- [How do I know if/when the salt bucket has rotated?](#how-do-i-know-ifwhen-the-salt-bucket-has-rotated) +- [Should the DSP be concerned with latency?](#should-the-dsp-be-concerned-with-latency) +- [How should the DSP maintain proper frequency capping with UID2?](#how-should-the-dsp-maintain-proper-frequency-capping-with-uid2) +- [Will all user opt-out traffic be sent to the DSP?](#will-all-user-opt-out-traffic-be-sent-to-the-dsp) +- [Is the DSP expected to handle opt-out signals only for the UID2s that they already store?](#is-the-dsp-expected-to-handle-opt-out-signals-only-for-the-uid2s-that-they-already-store) +- [How long should the DSP keep the opt-out list?](#how-long-should-the-dsp-keep-the-opt-out-list) +- [Is the UID2 of an opted-out user sent to the opt-out endpoint in an encrypted form?](#is-the-uid2-of-an-opted-out-user-sent-to-the-opt-out-endpoint-in-an-encrypted-form) +- [In what format is the UID2 of an opted-out user sent to the webhook?](#in-what-format-is-the-uid2-of-an-opted-out-user-sent-to-the-webhook) +- [What request type do opt-outs use?](#what-request-type-do-opt-outs-use) +- [How strict are the requirements for honoring opt-outs?](#how-strict-are-the-requirements-for-honoring-opt-outs) +- [How can I check if a user has opted out?](#how-can-i-check-if-a-user-has-opted-out) +- [How do SDK errors impact the DSP's ability to respond to a bid?](#how-do-sdk-errors-impact-the-dsps-ability-to-respond-to-a-bid) + +#### How do I know which decryption key to apply to a UID2? + +Each of the server-side SDKs (see [SDKs: Summary](../sdks/summary-sdks.md)) updates decryption keys automatically. Metadata supplied with the UID2 token discloses the IDs of the decryption keys to use. + +#### Where do I get the decryption keys? + +You can use one of the server-side SDKs (see [SDKs: Summary](../sdks/summary-sdks.md)) to communicate with the UID2 service and fetch the latest keys. To make sure that the keys remain up-to-date, it is recommended to fetch them periodically; for example, once every hour. + +#### How many decryption keys may be present in memory at any point? + +There may be thousands of decryption keys present in the system at any given point. + +#### How do I know if/when the salt has rotated? + +The DSP is not privy to when the UID2 salt rotates. This is similar to a DSP being unaware if users cleared their cookies. Salt rotation has no significant impact on the DSP. + +#### Should the DSP be concerned with latency? + +The UID2 service does not introduce latency into the bidding process. Any latency experienced can be attributed to the network, not the UID2 service. + +#### How should the DSP maintain proper frequency capping with UID2? + +The UID2 has the same chance as a cookie of becoming stale. Hence, the DSP can adapt the same infrastructure currently used for cookie or deviceID-based frequency capping for UID2. For details, see [How do I know when to refresh a raw UID2?](#how-do-i-know-when-to-refresh-a-raw-uid2). + +#### Will all user opt-out traffic be sent to the DSP? + +Yes, all opt-outs from the UID2 [Transparency and Control Portal](https://www.transparentadvertising.com/) hit the opt-out endpoint, which the DSP must configure to [honor user opt-outs](../guides/dsp-guide.md#honor-user-opt-outs). + +#### Is the DSP expected to handle opt-out signals only for the UID2s that they already store? + +In some cases a DSP may receive a UID2 token for a newly-stored UID2 where the token is generated before the opt-out timestamp. The DSP is not allowed to bid on such tokens. It is therefore recommended to store all opt-out signals regardless of whether the corresponding UID2 is currently stored by the DSP or not. For details, see the diagram in [Bidding Opt-Out Logic](../guides/dsp-guide.md#bidding-opt-out-logic). + +#### How long should the DSP keep the opt-out list? + +We recommend that you keep the opt-out information indefinitely. + +#### Is the UID2 of an opted-out user sent to the opt-out endpoint in an encrypted form? + +No. It is sent as an unencrypted (raw) UID2. + +#### In what format is the UID2 of an opted-out user sent to the webhook? + +If a user has opted out, the UID2 Operator returns the raw UID2s as URL-encoded query parameters. + +For details about the opt-out process for DSPs, see [Honor User Opt-Outs](../guides/dsp-guide.md#honor-user-opt-outs). + +#### What request type do opt-outs use? + +Typically GET requests, but different DSPs may use different types. + +#### How strict are the requirements for honoring opt-outs? + +Opt-outs must always be respected. It may take some time for an opt-out request to propagate through the system during which time it is expected that some bids may not honor the opt-out. + +#### How can I check if a user has opted out? + +DSPs can check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. + +#### How do SDK errors impact the DSP's ability to respond to a bid? + +If there is an error, the SDK will not decrypt the UID2 token into a UID2. diff --git a/docs/getting-started/gs-permissions-new.md b/docs/getting-started/gs-permissions-new.md new file mode 100644 index 000000000..2a5212bee --- /dev/null +++ b/docs/getting-started/gs-permissions-new.md @@ -0,0 +1,29 @@ +--- +title: API Permissions +description: Information about UID2 API permissions. +hide_table_of_contents: false +sidebar_position: 07 +--- + +import Link from '@docusaurus/Link'; + +# API Permissions + +The UID2 ecosystem includes several different API permissions that allow access to complete specific activities. This approach is part of the overall secure design of UID2. + +For each UID2 participant that has API Key and Client Secret, the permissions are linked to the participant's API credentials (see [Account Setup](gs-account-setup.md) and [UID2 Credentials](gs-credentials.md)). + +:::note +If you're a publisher and are implementing UID2 on the client side, API permissions do not apply to you. Instead, you'll receive a different set of credentials that are specifically for generating a client-side token request. For details, see [Subscription ID and Public Key](gs-credentials.md#subscription-id-and-public-key). +::: + +A participant can have one or several sets of API credentials with associated permissions. In cases where you have more than one API permission, you have the option to have a separate set of credentials for each permission or have a single set of credentials for all permissions. We recommend having a separate set of credentials for each permission. + +The following table lists the key permissions, the types of participants that commonly use them, and a summary of the key associated activities. + +| Name | Participant Type | Permissions | +| :--- | :--- | :--- | +| 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 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: | diff --git a/docs/guides/images/advertiser-flow-endpoints-mermaid.png b/docs/guides/images/advertiser-flow-endpoints-mermaid.png index 6b9d3ee9d..55f704a3e 100644 Binary files a/docs/guides/images/advertiser-flow-endpoints-mermaid.png and b/docs/guides/images/advertiser-flow-endpoints-mermaid.png differ diff --git a/docs/guides/images/advertiser-flow-endpoints-mermaid.png.bak b/docs/guides/images/advertiser-flow-endpoints-mermaid.png.bak new file mode 100644 index 000000000..6b9d3ee9d Binary files /dev/null and b/docs/guides/images/advertiser-flow-endpoints-mermaid.png.bak differ diff --git a/docs/guides/images/advertiser-flow-overview-mermaid.png b/docs/guides/images/advertiser-flow-overview-mermaid.png index f1b258069..f793720f3 100644 Binary files a/docs/guides/images/advertiser-flow-overview-mermaid.png and b/docs/guides/images/advertiser-flow-overview-mermaid.png differ diff --git a/docs/guides/images/advertiser-flow-overview-mermaid.png.bak b/docs/guides/images/advertiser-flow-overview-mermaid.png.bak new file mode 100644 index 000000000..f1b258069 Binary files /dev/null and b/docs/guides/images/advertiser-flow-overview-mermaid.png.bak differ diff --git a/docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak b/docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak index 6223664e3..4f738b843 100644 --- a/docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak +++ b/docs/guides/images/resource/advertiser-flow-endpoints-mermaid.md.bak @@ -1,3 +1,30 @@ +26/6/25: V3 API Update - Updated endpoints diagram to use V3 identity map API with refresh timestamps instead of salt bucket monitoring. + + sequenceDiagram + participant ADP as Advertiser/Data Provider + participant UID as UID2 Operator + participant DSP + Note over ADP,DSP: 1. Generate raw UID2s from DII using the identity map endpoint. + loop + ADP->>UID: 1-a. Send a request containing DII to the POST /identity/map endpoint. + UID->>ADP: 1-b. Store the raw UID2 (u), refresh timestamp (r), and optionally previous UID2 (p) returned from the POST /identity/map endpoint. + end + Note over ADP,DSP: 2. Store raw UID2s and refresh timestamps. + Note over ADP,DSP: 3. Manipulate or combine raw UID2s. + Note over ADP,DSP: 4. Send raw UID2s to DSPs. + ADP-->>DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for raw UID2 refresh. + loop + ADP->>ADP: 5-a. Check current time against stored refresh timestamps. + ADP->>UID: 5-b. If refresh time reached, resend DII to the POST /identity/map endpoint for updated raw UID2. + UID->>ADP: 5-c. Store the new raw UID2 (u), refresh timestamp (r) and optionally previous UID2 (p) returned from the POST /identity/map endpoint. + end + Note over ADP,DSP: 6. Monitor for opt-out status. Remove all opt-outs from local storage and do not use. + loop + ADP->>UID: 6-a. Monitor for optout status using the POST /optout/status endpoint. + UID->>ADP: 6-b. Return optout status. + end + >DSP: Send stored raw UID2s to DSPs to create audiences and conversions, or use them for measurement. + Note over ADP,DSP: 5. Monitor for raw UID2 refresh. + loop + ADP->>ADP: 5-a. Check current time against stored refresh timestamps. + ADP->>UID: 5-b. If refresh time reached, resend DII to get updated raw UID2. + UID->>ADP: 5-c. Store the new raw UID2 and refresh timestamp. + end + Note over ADP,DSP: 6. Monitor for opt-out status. Remove all opt-outs from local storage and do not use. + loop + ADP->>UID: 6-a. Monitor for optout status using the POST optout/status endpoint. + UID->>ADP: 6-b. Return optout status. + end + 1/2/25: Reworking the ADP diagram for six steps as discussed with AnDe. Sent to her for review but checking in these mods. + +### 1: Generate Raw UID2s from DII + +| 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 raw UID2 (`u` field) returned in the response can be used to target audiences on relevant DSPs.
The response returns a user's raw UID2 (`u`), refresh timestamp (`r`), and optionally the previous raw UID2 (`p`) if the current UID2 was rotated within the last 90 days. Use the refresh timestamp to determine when to refresh the UID2. For details, see [5: Monitor for Raw UID2 Refresh](#5-monitor-for-raw-uid2-refresh). | + + +### 2: Store Raw UID2s and Refresh Timestamps + +The response from Step 1, [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii), contains mapping information. We recommend that you store the following information returned in Step 1: + +- Cache the mapping between DII and raw UID2 (`u` field). +- Store the refresh timestamp (`r` field) to know when the raw UID2 could refresh. +- Optionally store the previous raw UID2 (`p` field) if provided for users whose UID2 was rotated within the last 90 days. + +### 3: Manipulate or Combine Raw UID2s + +Use the UID2s you received in Step 1. For example, you might do one or more of the following: + +- Do some manipulation: for example, combine UID2s you generated from DII and UID2s received from another participant such as an advertiser or data provider. +- Add new UID2s into an existing audience. + +### 4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions + +Use the raw UID2s for some purpose such as: + + - Sending stored raw UID2s to DSPs to create audiences and conversions. + - Using the raw UID2s for measurement. + +For example, you could send the (raw UID2) (`u` field) returned in Step 1-b to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw UID2s to build an audience. + +You could also send conversion information via API or pixels for measurement (attribution) or for retargeting. + +### 5: Monitor for Raw UID2 Refresh + +A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year as part of the UID2 rotation process. + +The V3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 may refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data, it is guaranteed that it won't refresh before that time. + +We recommend checking for refresh opportunities daily. The following table shows the steps for monitoring raw UID2 refresh. + +| Step | Action | Description | +| --- |--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 5-a | Local timestamp check | Compare the current time with the refresh timestamp (`r` field) you stored from the [POST /identity/map](../endpoints/post-identity-map.md) response previously. | +| 5-b | [POST /identity/map](../endpoints/post-identity-map.md) | If the current time is greater than or equal to the refresh timestamp, regenerate the raw UID2 by calling the identity map endpoint again with the same DII. | +| 5-c | Local storage update | Store the new raw UID2 (`u` field), refresh timestamp (`r` field) and optionally previous UID2 (`p` field) returned from the response. | + +#### Determine whether to refresh a raw UID2 + +To determine whether to refresh a raw UID2, follow these steps: + +1. Compare the current time with the refresh timestamp (`r` field) you stored from the [POST /identity/map](../endpoints/post-identity-map.md) response. + +2. If the current time is greater than or equal to the refresh timestamp, regenerate the raw UID2 by calling [POST /identity/map](../endpoints/post-identity-map.md) again with the same DII. + +This approach ensures your UID2s remain current and valid for audience targeting and measurement. + +### 6: Monitor for Opt-Out Status + +It's important to honor user opt-out status. Periodically, monitor for opt-out status, to be sure that you don't continue using UID2s for users that have recently opted out. + +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. + +- Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. + +For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). diff --git a/docs/guides/integration-advertiser-dataprovider-overview-new.md b/docs/guides/integration-advertiser-dataprovider-overview-new.md new file mode 100644 index 000000000..a17f7313c --- /dev/null +++ b/docs/guides/integration-advertiser-dataprovider-overview-new.md @@ -0,0 +1,146 @@ +--- +title: Advertiser/Data Provider Integration Overview +sidebar_label: Advertiser/Data Provider Integration Overview +description: Overview of integration options for organizations that collect user data and push it to other participants. +hide_table_of_contents: false +sidebar_position: 07 +displayed_sidebar: sidebarAdvertisers +--- + +import Link from '@docusaurus/Link'; + +# Advertiser/Data Provider Integration Overview + +This guide provides an overview of integration options for organizations that collect user data and push it to other UID2 participants. Data collectors include advertisers, data on-boarders, measurement providers, identity graph providers, third-party data providers, and any other organizations that send data to other participants. + +## Advertiser/Data Provider Routes to Use UID2 + +Within the ad tech industry, advertisers use identity to build audiences, track conversions, and generate their graphs. As an advertiser, or as a data provider acting on behalf of an advertiser, the following table shows some examples of how you can accomplish some of these goals with UID2. + +:::note +There are other ways that you can use UID2, outside these use cases. These are just some examples. +::: + +| Send/Receive? | Action | Advantage/Result | +| --- | --- | --- | +| Send in audiences | Send UID2s via API or pixels | Create audiences. | +| Send in conversions | Send UID2s as conversion information | Use conversion information for measurement (attribution) or for retargeting via API or pixels. | +| Receive graph data | Receive UID2s from graph/data providers via API or pixels | Build graph data. | + +## High-Level Steps + +At a high level, the steps for advertisers and data providers integrating with UID2 are as follows: + +1. [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii) + +2. [Store Raw UID2s and Refresh Timestamps](#2-store-raw-uid2s-and-refresh-timestamps) + +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) + +5. [Monitor for Raw UID2 Refresh](#5-monitor-for-raw-uid2-refresh) + +6. [Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) + +## Summary of Implementation Options + +The following table shows the implementation options that are available for advertisers and data providers, for each of the high-level steps. Some steps are managed solely as part of your own custom implementation; some steps can be managed by one or more of the UID2 implementation options available. For details, click the link on each step. + +| 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: | +| [2: Store Raw UID2s and Refresh Timestamps](#2-store-raw-uid2s-and-refresh-timestamps) | Custom (your choice). | +| [3: Manipulate or Combine Raw UID2s](#3-manipulate-or-combine-raw-uid2s) | Custom (your choice). | +| [4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions](#4-send-stored-raw-uid2s-to-dsps-to-create-audiences-or-conversions) | Custom (your choice). | +| [5: Monitor for Raw UID2 Refresh](#5-monitor-for-raw-uid2-refresh) | Use the refresh timestamp (`r` field) returned from the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to determine when to refresh UID2s. | +[//]: # (Any of the following options:) +| [6: Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) | API call to the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. | + +## Integration Diagram + +The following diagram outlines the steps that data collectors must complete to map DII to raw UID2s for audience building and targeting. + +DII refers to a user's normalized email address or phone number, or the normalized and SHA-256-hashed email address or phone number. + +To keep your UID2-based audience information accurate and up to date, follow these integration steps every day. + +![Advertiser Flow](images/advertiser-flow-overview-mermaid.png) + + + +For details about the different parts of the diagram, refer to the following sections. + +### 1: Generate Raw UID2s from DII + +You can generate raw UID2s from directly identifying information (DII), or receive UID2s from another UID2 participant such as a data provider acting on your behalf. + +To generate raw UID2s, use one of the following options: + +- One of the UID2 SDKs: + + - Python SDK: See [Map DII to Raw UID2s](../sdks/sdk-ref-python.md#map-dii-to-raw-uid2s). + - Java SDK: See [Usage for Advertisers/Data Providers](../sdks/sdk-ref-java.md#usage-for-advertisersdata-providers). + +- Snowflake: See [Map DII](integration-snowflake.md#map-dii). + +- AWS Entity Resolution: See [AWS Entity Resolution Integration Guide](integration-aws-entity-resolution.md). + +- HTTP endpoints: [POST /identity/map](../endpoints/post-identity-map.md). For details, see [Generate Raw UID2s from DII](integration-advertiser-dataprovider-endpoints.md#1-generate-raw-uid2s-from-dii). + +### 2: Store Raw UID2s and Refresh Timestamps + +The response from Step 1, [Generate Raw UID2s from DII](#1-generate-raw-uid2s-from-dii), contains mapping information. We recommend that you store the following information returned in Step 1: + +- Cache the mapping between DII and raw UID2 (`u` field). +- Store the refresh timestamp (`r` field) to know when the raw UID2 could refresh. +- Optionally store the previous raw UID2 (`p` field) if provided for users whose UID2 was rotated within the last 90 days. + +### 3: Manipulate or Combine Raw UID2s + +Use the UID2s you received in Step 1. For example, you might do one or more of the following: + +- Do some manipulation: for example, combine UID2s you generated from DII and UID2s received from another participant such as an advertiser or data provider. +- Add new UID2s into an existing audience. + +### 4: Send Stored Raw UID2s to DSPs to Create Audiences or Conversions + +Use the raw UID2s for some purpose such as: + + - Sending stored raw UID2s to DSPs to create audiences and conversions. + - Using the raw UID2s for measurement. + +For example, you could send the (raw UID2 (`u` field) returned in Step 1 to a DSP while building your audiences. Each DSP has a unique integration process for building audiences; follow the integration guidance provided by the DSP for sending raw UID2s to build an audience. + +You could also send conversion information via API or pixels for measurement (attribution) or for retargeting. + +### 5: Monitor for possible Raw UID2 Refresh + +A raw UID2 is an identifier for a user at a specific moment in time. The raw UID2 for a specific user changes at least once per year as part of the UID2 rotation process. + +The V3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 may refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data, it is guaranteed that it won't refresh before that time. + +We recommend checking for refresh opportunities daily. To determine whether to refresh a raw UID2: + +1. Compare the current time with the refresh timestamp (`r` field) you stored from the [POST /identity/map](../endpoints/post-identity-map.md) response. + +2. If the current time is greater than or equal to the refresh timestamp, regenerate the raw UID2 by calling [POST /identity/map](../endpoints/post-identity-map.md) again with the same DII. + +This approach ensures your UID2s remain current and valid for audience targeting and measurement. + + +### 6: Monitor for Opt-Out Status + +It's important to honor user opt-out status. Periodically, monitor for opt-out status, to be sure that you don't continue using UID2s for users that have recently opted out. + +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. + +- Check the opt-out status of raw UID2s using the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. + +For details about the UID2 opt-out workflow and how users can opt out, see [User Opt-Out](../getting-started/gs-opt-out.md). + +## FAQs + +For a list of frequently asked questions for advertisers and data providers using the UID2 framework, see [FAQs for Advertisers and Data Providers](../getting-started/gs-faqs.md#faqs-for-advertisers-and-data-providers). diff --git a/docs/ref-info/glossary-uid-new.md b/docs/ref-info/glossary-uid-new.md new file mode 100644 index 000000000..7fe1cd1aa --- /dev/null +++ b/docs/ref-info/glossary-uid-new.md @@ -0,0 +1,532 @@ +--- +title: UID2 Glossary +description: Definitions for some UID2 terms. +hide_table_of_contents: false +sidebar_position: 10 +--- + +import MdxJumpAnchor from '@site/src/components/MdxJumpAnchor'; +import Link from '@docusaurus/Link'; + +# Unified ID 2.0 Glossary +

This page defines some key terms used in the UID2 documentation.

+ + + +### A +
+ +
Advertising ID
+
Advertising ID is another term for a raw UID2.
+ +
Advertising token
+
Advertising token is another term for a UID2 token.
+ +
AKS
+
AKS is an acronym for Azure Kubernetes Service. For details, see [What is Azure Kubernetes Service (AKS)?](https://learn.microsoft.com/en-us/azure/aks/what-is-aks) (Microsoft documentation).
+
To run an AKS cluster on a confidential container, Microsoft offers a solution to run it on virtual nodes on Microsoft Azure container instances. For details, see [Virtual nodes on Azure Container Instances](https://learn.microsoft.com/en-us/azure/container-instances/container-instances-virtual-nodes) (Microsoft documentation).
+
In the context of UID2, AKS is one of the supported secure computing environments for hosting a Private Operator.
+
For details, see UID2 Private Operator for AKS Integration Guide.
+ + +
API key
+
Each UID2 participant using a server-side implementation has an API key (client key) and also a secret value associated with the key, called the client secret (API secret). The client secret is known only to the participant and the UID2 service.
+
For details, see UID2 Credentials.
+ +
API secret
+
See client secret.
+ +
App name
+
In the context of mobile integrations, the app name is the Android application ID, the iOS app store ID, or the iOS bundle identifier.
+ +
Authorization header
+
The Authorization header is a way to authenticate the client to the UID2 service.
+
For details, see 11.6.2. Authorization in RFC 9110, the HTTP specification.
+ +
+ +### B + +
+ +
Bearer token
+
A bearer token is a special string that identifies the client. For authentication, some UID2 endpoints require the client key to be specified as a bearer token in the Authorization header of the request: for example, POST /token/generate.
+ +
Bidstream
+
To place a request for an ad to be placed in an advertising spot (bid request), the publisher sends different pieces of information, so that advertisers can bid on it, generally through an advertising exchange or DSP. The flow of bidding data is the bidstream.
+
Bidstream data goes from publishers to other entities (depending on the publisher's configuration) and back to the publisher.
+ +
+ +### C + +
+ +
Client key
+
See API key.
+ +
Client keypair
+
For client-side publisher integrations, the Subscription ID and public key are the two values issued to publishers to uniquely identify the account. Client keypair is a term we use for these two values together.
+
For details, see Subscription ID and Public Key.
+ +
Client secret
+
Each UID2 participant using a server-side implementation has an API key (client key) and also a secret value associated with the key, called the client secret (API secret). The client secret is known only to the participant and the UID2 service.
+
For details, see UID2 Credentials.
+ +
Client-server integration
+
One of the UID2 integration approaches is to integrate partially on the client side and partially on the server side (client-server).
+
For example, in a client-server integration for a publisher, the UID2 token is generated on the server side and refreshed on the client side.
+
Examples of documentation for publisher client-server integrations:
- UID2 Client-Server Integration Guide for Prebid.js
- Client-Server Integration Guide for JavaScript
- UID2 Client-Server Integration Guide for Mobile
+ +
Client-side integration
+
One of the UID2 integration approaches is to integrate entirely on the client side.
+
In a client-side integration, UID2 tokens are generated and refreshed on the client side.
+
For example, in a client-side integration, advertisers generate UID2 tokens on the client side for tracking pixels, and publishers generate UID2 tokens on the client side for bidstream use, as well as refreshing the tokens.
+
Examples of documentation for publisher client-side integrations:
- UID2 Client-Side Integration Guide for Prebid.js
- Client-Side Integration Guide for JavaScript
- UID2 Client-Side Integration Guide for Mobile
+ +
Closed Operator
+
Closed Operator is another term for a Private Operator.
+ +
Confidential Computing (GCP)
+
A Confidential Computing solution from Google Cloud Platform (GCP), Confidential Space, that is supported for hosting a UID2 Private Operator.
+
For details, see Confidential Space.
+ +
Confidential containers (Azure)
+
Confidential Containers is the name of a secure confidential computing option from Microsoft Azure. Each Confidential Containers implementation runs in a hardware-backed Trusted Execution Environment (TEE) that provides intrinsic capabilities such as data integrity, data confidentiality, and code integrity.
+
In the context of UID2, Confidential Containers from Azure is one of the supported secure computing environments for hosting a Private Operator.
+
For details, see UID2 Private Operator for Azure Integration Guide.
+ +
Confidential Space (GCP)
+
Confidential Space is one of the Confidential Computing options from Google Cloud Platform (GCP). Confidential Space offers a secure enclave environment, known as a Trusted Execution Environment (TEE).
+
In the context of UID2, GCP Confidential Space is one of the supported secure computing environments for hosting a Private Operator.
+
For details, see UID2 Private Operator for GCP Integration Guide.
+ +
Core Service
+
The UID2 Core Service is a centralized service that manages access to secret salts, encryption keys, and other relevant data in the UID2 ecosystem.
+
For an overview of all the UID2 services, see UID2 Component Services.
+ +
+ +### D + +
+ +
Data provider
+
In the context of UID2, a data provider is any entity that provides data and measurement services relating to advertising, such as a data partner, measurement partner, or offline measurement provider.
+
For details, see participant (Data Providers).
+ +
Demand-side platform
+
A demand-side platform (DSP) provides services to companies that want to buy digital advertising, such as advertisers, brands, and media agencies.
+ +
Directly identifying information (DII)
+
Directly identifying information, or DII, is information that directly identifies an individual, including name, email address, or phone number.
+
UID2 supports email address and phone number, and translates the DII to a value that can be used for the purpose of targeted advertising but cannot by itself be traced back to the original value.
+ +
Docker
+
Docker is a Platform as a Service (PaaS) suite of products that is used for automating the deployment of software via packages called containers. The set of Docker products allows packaging of an application, with all its dependencies, into a virtual container that can run on most operating systems so that applications can work efficiently in different environments.
+
For details, see https://www.docker.com.
+ +
+ +### E + +
+ +
Enclave
+
An enclave is a secure subsection of a computing environment. The enclave has additional business logic and security measures applied to it, to prevent anyone from tampering with it.
+
In the context of UID2, a Private Operator must run inside an enclave. For a summary of the enclave versions supported, see Hosting Options for Private Operators in *UID2 Private Operator Integration Overview*.
+
In an enclave, the operator image must be a very specific, predefined version, and additional constraints are applied to ensure security.
+ +
Encryption key
+
Each UID2 token is encrypted using an encryption key that's unique to the publisher that requested the token. The key identifies the publisher and is required for decrypting the token. This helps ensure that UID2 tokens cannot be decrypted by unauthorized individuals.
+ +
Environment
+
UID2 offers two environments: an integration environment for testing, and a production environment.
+
If you're using both, you'll need to get a separate set of credentials for each environment.
+
For details, see [Environments](../getting-started/gs-environments.md).
+ +
EUID framework
+
The European Unified ID (EUID) framework enables deterministic identity for advertising opportunities on the open internet for many participants across the advertising ecosystem. It enables publisher websites, mobile apps, and Connected TV (CTV) apps to monetize through programmatic workflows. Built as an open-source, standalone solution with its own unique namespace, the framework offers privacy controls designed to help participants meet local market requirements.
+
EUID operates in the European region, including many European countries, such as France, Italy, and Spain, some non-European countries, such as Iceland, and some other regions, such as the Azores, Martinique, and the United Kingdom. It was designed with EU privacy law compliance in mind.
+
There are many similarities between UID2 and EUID, but they are completely separate, and their tokens are not interchangeable.
+
For details, see European Unified ID Overview.
+ +
+ +### F + +
+ +
First-level hash
+
In the context of UID2, the first-level hash is the anonymized, opaque, secure value from which the raw UID2, UID2 token, and refresh token are generated. Several cryptographic functions, including salting and hashing, are applied to the initial value, whether an email or a phone number, to create the first-level hash.
+ +
+ +### G + +
+ +
GDPR
+
The GDPR, or General Data Protection Regulation, is a European privacy and security law that regulates how organizations target or collect data related to residents of the European Union.
+ +
+ +### H + +
+
Hash
+
A hash function converts a set of data of varying/arbitrary size to a set of data of fixed size. The result of the hash function is called a hash, digest, or hash value.
+
Hashing is a one-way function. The same input value, hashed, always yields the same output value, but there is no corresponding function to take the output value and arrive at the input value. Hashing is a security measure.
+
UID2 uses the SHA-256 hashing algorithm.
+ +
+ +### I + +
+ +
Identity
+
In the context of UID2, the term "identity" refers to a package of values that includes the UID2 token, the refresh token, and associated values such as timestamps. This set of values is returned in the response from the POST /token/generate endpoint and also from the POST /token/refresh endpoint.
+ +
Integration approaches
+
UID2 integrations can be entirely on the client side, entirely on the server side, or partially on the client side and partially on the server side (client-server).
+ +
+ +### J + +
+ +
JSON Web Token (JWT)
+
A JSON Web Token (JWT) is a compact, URL-safe means of representing claims (pieces of information) to be sent from one party to another over the web. The claims in a JWT are encoded as a JSON object that is used either as the payload of a JSON Web Signature (JWS) structure or as the plain text of a JSON Web Encryption (JWE) structure. This enables the claims to be digitally signed and/or encrypted.
+ +
+ +### K + +
+ +
Key
+
See Encryption key.
+ +
+ +### N + +
+ +
Normalize
+
To normalize a data set means to bring it to a standard condition or state.
+
UID2 includes specific normalization rules. For details, see Email Address Normalization and Phone Number Normalization.
+ +
+ +### O + +
+ +
OpenID Connect (OIDC)
+
OpenID Connect (OIDC) is an identity layer on top of the OAuth 2.0 protocol that allows the client to verify the identity of an end-user based on authentication by an authorization server.
+
For details, see [OpenID Connect Basic Client Implementer's Guide 1.0 - draft 40](https://openid.net/specs/openid-connect-basic-1_0.html) (specification).
+ +
Opaque
+
When we say a UID2 token is an opaque string, we mean that the way that the token is computed, and its format, are not communicated to UID2 participants and cannot be relied upon to remain unchanged. No assumptions should be made about the format or length of the string, or any other aspect of it.
+ +
Open Operator
+
Open Operator is another term for a Public Operator.
+ +
Operator
+
An Operator is an organization or entity that runs the UID2 Operator Service. The UID2 Operator is the API server in the UID2 ecosystem.
+
Operators perform multiple functions, such as receiving encryption keys and secret salts from the UID2 Core Service, salting and hashing personal data (DII) to return raw UID2s, and encrypting raw UID2s to generate UID2 tokens.
+
A participant can also choose to become a Private Operator to access UID2 APIs and to generate raw UID2s and UID2 tokens from within a private infrastructure.
+
For details, see participants and The UID2 Operator.
+ +
Operator key
+
Each UID2 Private Operator has an operator key that allows the Private Operator Service to connect to the Core Service and Opt-Out Service and call some endpoints on it.
+
The operator key identifies the participant Operator to the UID2 service.
+ +
Operator Service
+
A service that enables all functions of the Operator.
+
For an overview of all the UID2 services, see UID2 Component Services.
+ +
Opt-out
+
An end user who participates in the UID2 ecosystem can opt out at any time by going to the Transparency and Control Portal.
+
For details about the UID2 opt-out workflow and how users can opt out, see User Opt-Out.
+ +
Opt-Out Service
+
The Opt-Out Service is a global UID2 service that manages and stores user opt-out requests.
+
For an overview of all the UID2 services, see UID2 Component Services.
+ +
+ +### P + +
+ +
Participant
+
An entity that fulfils a key role in UID2. Participants include the following: Core Administrator, Operator, DSP, data provider, advertiser, publisher, consumer.
+
For details, see participants.
+ +
Private Operator
+
A Private Operator is an entity that runs a private instance of the Operator Service. The Private Operator generates and manages UID2s for itself, using its own resources (such as hardware) in a secure environment.
+
For details, see The UID2 Operator.
+ +
Private Operator Service
+
A private instance of the Operator Service, run by a Private Operator.
+ +
Public key
+
For client-side publisher integrations, the public key is one of the two values issued to publishers to uniquely identify the account. For details, see Subscription ID and Public Key.
+
In UID2 integrations, this value is often represented as serverPublicKey: for example, in the UID2 Client-Side Integration Guide for Prebid.js, the Client-Side Integration Guide for JavaScript, and the UID2 Client-Side Integration Guide for Mobile.
+ +
Public Operator
+
A Public Operator is an entity that runs a public instance of the UID2 Operator Service. For example, The Trade Desk currently serves as a Public Operator for the UID2 framework, available to all participants.
+
For details, see The UID2 Operator.
+ +
+ +### R + +
+ +
Raw UID2
+
An unencrypted alphanumeric identifier created through the UID2 APIs or SDKs with the user's directly identifying information (email address or phone number) as input. The raw UID2 is encrypted to create a UID2 token. The raw UID2 is a unique value; no two raw UID2s are the same. Raw UID2s, and their associated UID2 tokens, are case sensitive.
+
For details, see UID2 Identifier Types.
+ +
Refresh token
+
A refresh token is an opaque string that is issued along with the UID2 token. It is used to refresh the UID2 token, which has a limited life.
+
When the UID2 server receives the refresh token with a request for a new UID2 token, it checks for user opt-out. If the user has opted out of UID2, no new UID2 token is generated.
+
When a new UID2 token is generated and returned in response to the refresh token, a new refresh token is returned along with it. However, if the user is inactive for a long period of time, the refresh token itself expires.
+
For details, see UID2 Tokens and Refresh Tokens.
+
+ +### S + +
+ +
Salt
+
A string of characters that is used in the process of transforming an email address or phone number into a secure, opaque value that cannot by itself be traced back to the original value (raw UID2 or UID2 token). Salt values are kept secret.
+
The UID2 service uses salt as part of the process, along with hashing and encryption, to secure the original value. Salt is added to the input value before hashing.
+ +
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-new.md) endpoint earlier than version 3, such as [POST /identity/map (v2)](../endpoints/post-identity-map-v2-new.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-new.md) endpoint earlier than version 3, such as [POST /identity/map (v2)](../endpoints/post-identity-map-v2-new.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.
+ +
Secret
+
See client secret.
+ +
Secure Signals
+
A feature of Google Ad Manager. The secure signals feature (previously known as Encrypted Signals for Publishers, abbreviated to ESP) allows publishers to securely share signals with trusted third-party buying partners. It allows publishers to pass "encrypted" user IDs to bidders that are approved by Google, via Google Ad Manager and the Google Ad Manager Ad Exchange (AdX).
+
For details, see Share secure signals with your trusted partners (second section) and Share secure signals with bidders, both from Google.
+
For details about UID2 support of the Google secure signals feature, see Google Ad Manager Secure Signals Integration Guide.
+ +
Server-side integration
+
One of the UID2 integration approaches is to integrate entirely on the server side.
+
In a server-side integration, raw UID2s or UID2 tokens are generated and refreshed on the server.
+
For example, in a server-side integration, advertisers generate raw UID2s on the server side to be delivered for audience targeting, and publishers generate UID2 tokens on the server side for bidstream use.
+
An example of documentation for publisher server-side integration is Publisher Integration Guide, Server-Side.
+ +
SHA-256
+
SHA-256 is the secure hashing algorithm that UID2 uses.
+
SHA-256 (sometimes called SHA256) is part of the SHA-2 family of algorithms developed by the National Institute of Standards and Technology (NIST) and the National Security Agency (NSA) to succeed SHA-1. Each algorithm is named according to the number of bits in the output, so SHA-256 has 256 bits.
+
For details, see https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf (specification).
+ +
Sharing (in UID2)
+
In the context of UID2, sharing is a process for distributing raw UID2s, either directly or encrypted into UID2 tokens, from one UID2 sharing participant to another.
+
For details, see UID2 Sharing.
+ +
Sharing participant
+
For UID2, a sharing participant is a company that either has agreed to comply with the UID2 Participation Policy or fits within one of the exceptions, and that takes part in sharing, either as a sender or a receiver.
+
For details, see UID2 Sharing.
+ +
Single sign-on (SSO)
+
SSO is an acronym for Single sign-on. SSO allows a user to log in with the same credentials (usually, but not always, ID and password) to one of several software systems, such as apps or websites. SSO allows the user to log in once to multiple applications or sites using one set of credentials. With SSO, websites/apps do not have to maintain their own authentication systems.
+ +
SSO
+
See Single sign-on (SSO).
+ +
Subscription ID
+
For client-side publisher integrations, the Subscription ID is one of the two values issued to publishers to uniquely identify the account. For details, see Subscription ID and Public Key.
+ +
+ +### T + +
+ +
Token refresh
+
When a UID2 participant requests a UID2 token, the token is returned with a set of associated values, including a refresh token and timestamps for the UID2 token and the refresh token. As long as the refresh token has not expired, the publisher can use it to request a fresh UID2 token without having to send DII.
+
Any UID2 participant that requests a UID2 token must have a process in place for keeping the token valid: either monitoring the refresh period and requesting a new UID2 token before the refresh token expires, or requesting a new UID2 token each time, which requires sending DII.
+
In most cases, token refresh is managed by an SDK or other implementation strategy such as a Prebid.js implementation.
+
If the refresh token expires, the publisher must re-request a UID2 token by sending DII.
+
For details, see UID2 Tokens and Refresh Tokens.
+ +
Tokenized sharing
+
Tokenized sharing means encrypting DII or Raw UID2s into UID2 tokens and sharing the tokens with authorized recipients. Using UID2 tokens helps protect raw UID2s end-to-end between the sender and receiver of the data, including when the data passes through unauthorized parties. Tokenized sharing is required for sharing in the bidstream or via pixels, but you can use it in any sharing use case.
+
For details, see Tokenized Sharing Overview.
+ +
Transparency and Control Portal
+
The UID2 Transparency and Control Portal is a user-facing website, https://www.transparentadvertising.com/, that allows consumers to opt out of UID2 at any time.
+ +
+ +### U + +
+ +
UID
+
UID is a general term used to encompass both UID2 and EUID.
+
Since there are code components that support both UID2 and EUID, such as the server-side SDKs, the term UID is used as an umbrella term.
+
There are many similarities between UID2 and EUID, but they are completely separate, and their tokens are not interchangeable.
+ +
UID2 framework
+
The Unified ID 2.0 (UID2) framework enables deterministic identity for advertising opportunities on the open internet for many participants across the advertising ecosystem. It enables publisher websites, mobile apps, and Connected TV (CTV) apps to monetize through programmatic workflows. Built as an open-source, standalone solution with its own unique namespace, the framework offers privacy controls designed to help participants meet local market requirements.
+
UID2 operates in North America, parts of Asia, and some other regions.
+
There are many similarities between UID2 and EUID, but they are completely separate, and their tokens are not interchangeable.
+ +
UID2 identifier
+
There are two Unified ID 2.0 (UID2) identifier types: raw UID2s and UID2 tokens (also known as advertising tokens).
+
For details, see UID2 Identifier Types.
+ +
UID2 Portal
+
The UID2 Portal is a separate user interface that allows UID2 participants to manage their accounts.
+
For details, see UID2 Portal: Overview.
+ +
UID2 Service
+
The Unified ID 2.0 (UID2) service is a set of components, API endpoints, and other types of solutions that collectively implement the UID2 framework and provide clients with access to the relevant UID2 functionality.
+
The term "UID2 service" is also used to mean the UID2 Operator Service.
+ +
UID2 Token (Advertising Token)
+
A Unified ID 2.0 (UID2) token, also called an advertising token, is an encrypted form of a raw UID2.
+
UID2 tokens are generated from hashed or unhashed email addresses or phone numbers that are converted to raw UID2s and then encrypted. The UID2 token is a unique value; no two UID2 tokens are the same. UID2 tokens are case sensitive.
+
The token value is opaque: No assumptions should be made about the format or about the length of the string.
+
The token has a limited life, but can be refreshed in the background using the refresh token.
+
Publishers send UID2 tokens in the bidstream.
+
For details, see UID2 Identifier Types, UID2 Tokens: Key Information, and How the UID2 Token Is Created.
+ +
Unified ID 2.0
+
The term UID2 can be used to mean the UID2 framework, the UID2 service, a raw UID2, or a UID2 token (advertising token).
+ +
Unix time
+
Unix time, also called Epoch time, is defined as the number of seconds since 00:00:00 UTC on Thursday, 1 January 1970. Unix time is used in some UID2 response messages, expressed in milliseconds: for example, in the response to the `POST /token/refresh` endpoint (see Successful Response With Tokens).
+
Example: 1 January 2024, 9:00:00 AM GMT, expressed in Unix time, is `1704067200`. In milliseconds it is: `1704067200000`.
+ +
UTC
+
UTC is an abbreviation for Coordinated Universal Time, also called Zulu time, which is the primary time standard in general use. UTC essentially equates to Greenwich Mean Time (GMT), but is more scientifically precise.
+ +
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..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,199 +1,10 @@ --- title: POST /identity/map -description: DII を raw UID2 とソルトバケット ID にマッピング。 +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 - -複数のメールアドレス、電話番号、またはそれぞれのハッシュを、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..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](../endpoints/post-identity-map.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 4b69a93f4..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](../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)](../endpoints/post-identity-map-v2.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=