diff --git a/docs/endpoints/post-token-generate.md b/docs/endpoints/post-token-generate.md index ed5abe0d3..da7afa6a2 100644 --- a/docs/endpoints/post-token-generate.md +++ b/docs/endpoints/post-token-generate.md @@ -40,7 +40,7 @@ Here's what you need to know about this endpoint requests: ### Request Examples ->IMPORTANT: To ensure that the API key used to access the service remains secret, the `POST /token/generate` endpoint must be called from the server side, unlike the [POST /token/refresh](post-token-refresh.md), which does not require using an API key. +>IMPORTANT: To ensure that the API key used to access the service remains secret, the `POST /token/generate` endpoint must be called from the server side, unlike the [POST /token/refresh](post-token-refresh.md), which does not require using an API key. The following are unencrypted JSON request body examples for each parameter, one of which you should include in your token generation requests: @@ -122,7 +122,7 @@ Here is an example response when the the user has opted out. | `identity_expires` | double | The UNIX timestamp (in milliseconds) that indicates when the advertising token expires. | | `refresh_from` | double | The UNIX timestamp (in milliseconds) that indicates when the UID2 SDK for JavaScript (see [UID2 SDK for JavaScript Reference Guide](../sdks/client-side-identity.md)) will start refreshing the UID2 token.
TIP: If you are not using the SDK, consider refreshing the UID2 token from this timestamp, too. | | `refresh_expires` | double | The UNIX timestamp (in milliseconds) that indicates when the refresh token expires. | -| `refresh_response_key` | string | A key to be used in a [POST /token/refresh](post-token-refresh.md) request for response decryption. | +| `refresh_response_key` | string | A key to be used in a [POST /token/refresh](post-token-refresh.md) request for response decryption. | ### Response Status Codes @@ -141,9 +141,9 @@ If the `status` value is anything other than `success`, the `message` field prov | Type | Identity | Purpose | Next Endpoint | |:------|:-----------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------| -| Email | `validate@example.com` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified email address. | [POST /token/validate](post-token-validate.md) | -| Email | `optout@example.com` | Using this email for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) | -| Email | `refresh-optout@example.com` | Using this email for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) | -| Phone | `+12345678901` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified phone number. | [POST /token/validate](post-token-validate.md) | -| Phone | `+00000000002` | Using this phone number for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) | -| Phone | `+00000000000` | Using this phone number for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) | +| Email | `validate@example.com` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified email address. | [POST /token/validate](post-token-validate.md) | +| Email | `optout@example.com` | Using this email for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) | +| Email | `refresh-optout@example.com` | Using this email for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) | +| Phone | `+12345678901` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified phone number. | [POST /token/validate](post-token-validate.md) | +| Phone | `+00000000002` | Using this phone number for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) | +| Phone | `+00000000000` | Using this phone number for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) | diff --git a/docs/endpoints/post-token-refresh.md b/docs/endpoints/post-token-refresh.md index 15dccb6cf..efe4b28a0 100644 --- a/docs/endpoints/post-token-refresh.md +++ b/docs/endpoints/post-token-refresh.md @@ -6,7 +6,7 @@ sidebar_position: 04 --- # POST /token/refresh -Generate a new [UID2 token](../ref-info/glossary-uid.md#gl-uid2-token) by sending the corresponding unexpired refresh token, returned by the [POST /token/generate](post-token-generate.md) endpoint. +Generate a new [UID2 token](../ref-info/glossary-uid.md#gl-uid2-token) by sending the corresponding unexpired refresh token, returned by the [POST /token/generate](post-token-generate.md) endpoint. Used by: This endpoint is used mainly by publishers. @@ -16,14 +16,14 @@ Used by: This endpoint is used mainly by publishers. `POST '{environment}/v2/token/refresh'` -Add the content of the `refresh_token` value, returned in the response from the previous [POST /token/generate](post-token-generate.md) or `POST /token/refresh` operation, as the POST body. +Add the content of the `refresh_token` value, returned in the response from the previous [POST /token/generate](post-token-generate.md) or `POST /token/refresh` operation, as the POST body. Here's what you need to know about this endpoint: - No encryption is required for token refresh requests. - If the request is successful, with an HTTP status code of 200, a new UID2 token or opt-out information is returned. - Successful responses, whether the response includes a new token or opt-out information, are encrypted. Error responses are not encrypted. -- To decrypt responses, use the most recent `refresh_response_key` value for this token. The `refresh_response_key` value is returned in the response to the [POST /token/generate](post-token-generate.md) and `POST /token/refresh` operations. Each time a token is refreshed, a new `refresh_response_key` is returned. Be sure to use the most recent one to decrypt the current response. +- To decrypt responses, use the most recent `refresh_response_key` value for this token. The `refresh_response_key` value is returned in the response to the [POST /token/generate](post-token-generate.md) and `POST /token/refresh` operations. Each time a token is refreshed, a new `refresh_response_key` is returned. Be sure to use the most recent one to decrypt the current response. ### Path Parameters @@ -33,7 +33,7 @@ Here's what you need to know about this endpoint: #### Testing Notes -Using either of the following parameters in a [POST /token/generate](post-token-generate.md) request always generates an identity response with a `refresh_token` that results in a logout response when used with the `POST /token/refresh` endpoint: +Using either of the following parameters in a [POST /token/generate](post-token-generate.md) request always generates an identity response with a `refresh_token` that results in a logout response when used with the `POST /token/refresh` endpoint: - The `refresh-optout@example.com` email address - The `+00000000002` phone number @@ -102,7 +102,7 @@ An error response might look like the following: | `identity_expires` | double | The UNIX timestamp (in milliseconds) that indicates when the UID2 token expires. | | `refresh_from` | double | The UNIX timestamp (in milliseconds) that indicates when the UID2 SDK for JavaScript (see [UID2 SDK for JavaScript Reference Guide](../sdks/client-side-identity.md)) will start refreshing the UID2 token, if the SDK is in use.
TIP: If you are not using the SDK, consider refreshing the UID2 token from this timestamp, too. | | `refresh_expires` | double | The UNIX timestamp (in milliseconds) that indicates when the refresh token expires. | -| `refresh_response_key` | string | A key to be used in a new [POST /token/refresh](post-token-refresh.md) request for response decryption. | +| `refresh_response_key` | string | A key to be used in a new [POST /token/refresh](post-token-refresh.md) request for response decryption. | ### Response Status Codes diff --git a/docs/endpoints/post-token-validate.md b/docs/endpoints/post-token-validate.md index 7260a6217..c86beebdc 100644 --- a/docs/endpoints/post-token-validate.md +++ b/docs/endpoints/post-token-validate.md @@ -35,7 +35,7 @@ Used by: This endpoint is used mainly by publishers. | Body Parameter | Data Type | Attribute | Description | | :--- | :--- | :--- | :--- | -| `token` | string | Required | The advertising token returned by the [POST /token/generate](post-token-generate.md) response. | +| `token` | string | Required | The advertising token returned by the [POST /token/generate](post-token-generate.md) response. | | `email` | string | Conditionally Required | The email address for token validation.
The only valid value is: `validate@example.com`. | | `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of the [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address for token validation (`validate@example.com`).
The only valid value is: `ntI244ZRTXwAwpki6/M5cyBYW7h/Wq576lnN3l9+W/c=`. | | `phone` | string | Conditionally Required | The [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number for which to generate tokens.
The only valid value is: `+12345678901`. | @@ -113,9 +113,9 @@ If the `status` value is anything other than `success`, the `message` field prov ## Using POST /token/validate to Test -You can use this endpoint to test whether the [DII](../ref-info/glossary-uid.md#gl-dii) you are sending through [POST /token/generate](../endpoints/post-token-generate.md) is valid. Follow these steps. +You can use this endpoint to test whether the [DII](../ref-info/glossary-uid.md#gl-dii) you are sending through [POST /token/generate](../endpoints/post-token-generate.md) is valid. Follow these steps. -1. Depending on whether the DII is a hashed or unhashed email address or phone number, send a [POST /token/generate](../endpoints/post-token-generate.md) request using one of the four valid options listed in the [Unencrypted JSON Body Parameters](#unencrypted-json-body-parameters) table—`email`, `email_hash`, `phone`, or `phone_hash`—with the corresponding value as listed in the table. +1. Depending on whether the DII is a hashed or unhashed email address or phone number, send a [POST /token/generate](../endpoints/post-token-generate.md) request using one of the four valid options listed in the [Unencrypted JSON Body Parameters](#unencrypted-json-body-parameters) table—`email`, `email_hash`, `phone`, or `phone_hash`—with the corresponding value as listed in the table. 2. Store the returned `advertising_token` value for use in the next step. 3. Send a `POST /token/validate` request using the `email`, `email_hash`, `phone`, or `phone_hash` value that you sent in Step 1, with the `advertising_token` that you saved in Step 2 as the `token` property value. diff --git a/docs/endpoints/summary-endpoints.md b/docs/endpoints/summary-endpoints.md index d2a69405f..02176053d 100644 --- a/docs/endpoints/summary-endpoints.md +++ b/docs/endpoints/summary-endpoints.md @@ -7,7 +7,7 @@ sidebar_position: 01 # UID2 Endpoints -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 Python script examples, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). +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 Python script examples, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md). ## UID2 Tokens @@ -15,9 +15,9 @@ The following endpoints are for retrieving and managing UID2 tokens (identity to | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | -| [POST /token/generate](post-token-generate.md) | Requests a UID2 token from an email address or phone number provided by a user with their authorization for UID2-based targeted advertising. 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) | Generate a new token for a user for their refresh token from the [POST /token/generate](post-token-generate.md) response. | N/A | Required | +| [POST /token/generate](post-token-generate.md) | Requests a UID2 token from an email address or phone number provided by a user with their authorization for UID2-based targeted advertising. 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) | Generate a new token for a user for their refresh token from the [POST /token/generate](post-token-generate.md) response. | N/A | Required | ## Identity Maps @@ -25,6 +25,6 @@ The following endpoints are used by advertisers and third-party data providers. | Endpoint | Description | Request Encryption | Response Decryption | | :--- | :--- | :--- | :--- | -| [POST /identity/buckets](post-identity-buckets.md) | Monitor rotated salt buckets using their last updated timestamp. | Required | Required | -| [POST /identity/map](post-identity-map.md) | Retrieve UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | +| [POST /identity/buckets](post-identity-buckets.md) | Monitor rotated salt buckets using their last updated timestamp. | Required | Required | +| [POST /identity/map](post-identity-map.md) | Retrieve UID2s and salt bucket IDs for one or more email addresses, phone numbers, or their respective hashes. | Required | Required | diff --git a/docs/getting-started/gs-auth.md b/docs/getting-started/gs-auth.md index 1cbef6c07..49fdeba4f 100644 --- a/docs/getting-started/gs-auth.md +++ b/docs/getting-started/gs-auth.md @@ -11,4 +11,4 @@ To authenticate to the UID2 endpoints in a server-side implementation, you need - A client [API key](gs-credentials.md#api-key-and-client-secret). The API key is included as a bearer token in the request's Authorization header. For example:
`Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=` -- A client secret for encrypting API requests and decrypting API responses. This is needed for all endpoints except [POST /token/refresh](../endpoints/post-token-refresh.md).
For details and Python examples, see [Encrypting Requests and Decrypting Responses](gs-encryption-decryption.md). \ No newline at end of file +- A client secret for encrypting API requests and decrypting API responses. This is needed for all endpoints except [POST /token/refresh](../endpoints/post-token-refresh.md).
For details and Python examples, see [Encrypting Requests and Decrypting Responses](gs-encryption-decryption.md). \ No newline at end of file diff --git a/docs/getting-started/gs-credentials.md b/docs/getting-started/gs-credentials.md index f461a070e..8a1a077ef 100644 --- a/docs/getting-started/gs-credentials.md +++ b/docs/getting-started/gs-credentials.md @@ -11,7 +11,7 @@ Each UID2 participant gets a set of uniqu | Audience | Credentials | Integration | | :--- | :--- | :--- | -| Participants using a server-side endpoint | Both of the following: | Any integration using one of these endpoints: | +| Participants using a server-side endpoint | Both of the following: | Any integration using one of these endpoints: | | Participants using a client-side implementation | Both of the following: | Integrations using one of these: | If you're using the integration environment as well as the production environment, you'll get a separate set of credentials for each environment. diff --git a/docs/getting-started/gs-encryption-decryption.md b/docs/getting-started/gs-encryption-decryption.md index d2050cc47..458911796 100644 --- a/docs/getting-started/gs-encryption-decryption.md +++ b/docs/getting-started/gs-encryption-decryption.md @@ -12,7 +12,7 @@ import TabItem from '@theme/TabItem'; For almost all UID2 [endpoints](../endpoints/summary-endpoints.md), requests sent to the endpoint must be [encrypted](#encrypting-requests) and responses from the endpoint must be [decrypted](#decrypting-responses). -The only exception is that requests to the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint do not need to be encrypted. +The only exception is that requests to the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint do not need to be encrypted. Here's what you need to know about encrypting UID2 API requests and decrypting respective responses: @@ -96,7 +96,7 @@ The following table describes the field layout for response decryption code. ### Response Example -For example, a decrypted response to the [POST /token/generate](../endpoints/post-token-generate.md) request for an email address in the [preceding example](#request-example), may look like this: +For example, a decrypted response to the [POST /token/generate](../endpoints/post-token-generate.md) request for an email address in the [preceding example](#request-example), may look like this: ```json { @@ -117,7 +117,7 @@ For example, a decrypted response to the [POST /token/generate](../endpoints/pos This section includes an encryption and decryption code example in different programming languages. -For the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint, the code takes the values for `refresh_token` and `refresh_response_key` that were obtained from a prior call to [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md). +For the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint, the code takes the values for `refresh_token` and `refresh_response_key` that were obtained from a prior call to [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md). :::note For Windows, if you're using Windows Command Prompt instead of PowerShell, you must also remove the single quotes surrounding the JSON. For example, use `echo {"email": "test@example.com"}`. diff --git a/docs/getting-started/gs-environments.md b/docs/getting-started/gs-environments.md index 8883d3590..1be5149cb 100644 --- a/docs/getting-started/gs-environments.md +++ b/docs/getting-started/gs-environments.md @@ -25,4 +25,4 @@ Notes: - All UID2 endpoints use the same base URL. - The integration environment and the production environment require different [API keys](../ref-info/glossary-uid.md#gl-api-key). -- The expiration time of the [UID2 token](../ref-info/glossary-uid.md#gl-uid2-token) returned by the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints is subject to change, but is always significantly shorter in the integration environment than it is in the production environment. +- The expiration time of the [UID2 token](../ref-info/glossary-uid.md#gl-uid2-token) returned by the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints is subject to change, but is always significantly shorter in the integration environment than it is in the production environment. diff --git a/docs/getting-started/gs-faqs.md b/docs/getting-started/gs-faqs.md index 0cb117365..9e6cdd34e 100644 --- a/docs/getting-started/gs-faqs.md +++ b/docs/getting-started/gs-faqs.md @@ -56,9 +56,9 @@ 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? -You can use the [POST /token/validate](../endpoints/post-token-validate.md) endpoint to check whether the [DII](../ref-info/glossary-uid.md#gl-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. +You can use the [POST /token/validate](../endpoints/post-token-validate.md) endpoint to check whether the [DII](../ref-info/glossary-uid.md#gl-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). +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? @@ -67,8 +67,8 @@ No, publishers do not need to decrypt [UID2 tokens](../ref-info/glossary-uid.md# #### 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. +- 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? @@ -79,7 +79,7 @@ You can generate UID2 tokens from either the client side or the server side. For #### 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. +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. #### How can I test the refresh token workflow? @@ -89,7 +89,7 @@ The procedure is a little different depending on whether or not you are using an ##### 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: +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: - The `refresh-optout@example.com` as the `email` value. - The hash of `refresh-optout@example.com` as the `email_hash` value. - The `+00000000002` as the `phone` value. @@ -98,13 +98,13 @@ The procedure is a little different depending on whether or not you are using an ##### Without SDK: -1. Depending on whether the [DII](../ref-info/glossary-uid.md#gl-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: +1. Depending on whether the [DII](../ref-info/glossary-uid.md#gl-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: - The `refresh-optout@example.com` as the `email` value. - The hash of `refresh-optout@example.com` as the `email_hash` value. - The `+00000000002` as the `phone` value. - The hash of `+00000000002` as the `phone_hash` value. 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. +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? @@ -147,7 +147,7 @@ Here are some frequently asked questions for advertisers and data providers usin #### How do I know when to refresh the UID2 due to salt bucket rotation? -Metadata supplied with the UID2 generation request indicates the salt bucket used for generating the UID2. Salt buckets persist and correspond to the underlying [DII](../ref-info/glossary-uid.md#gl-dii) used to generate a UID2. Use the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint to return which salt buckets rotated since a given timestamp. The returned rotated salt buckets inform you which UID2s to refresh. +Metadata supplied with the UID2 generation request indicates the salt bucket used for generating the UID2. Salt buckets persist and correspond to the underlying [DII](../ref-info/glossary-uid.md#gl-dii) used to generate a UID2. Use the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint to return which salt buckets rotated since a given timestamp. The returned rotated salt buckets inform you which UID2s to refresh. :::note We do not make any promises about when the rotation takes place. To stay as up-to-date as possible, we recommend doing the checks once per hour. @@ -165,7 +165,7 @@ When mapping and remapping emails, be sure not to make any assumptions about the The recommended cadence for updating audiences is daily. -Even though each salt bucket is updated roughly once a year, individual bucket updates are spread over the year. This means that about 1/365th of all buckets are rotated daily. If fidelity is critical, consider calling the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint more frequently; for example, hourly. +Even though each salt bucket is updated roughly once a year, individual bucket updates are spread over the year. This means that about 1/365th of all buckets are rotated daily. If fidelity is critical, consider calling the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint more frequently; for example, hourly. #### How should I generate the SHA-256 of DII for mapping? diff --git a/docs/getting-started/gs-opt-out.md b/docs/getting-started/gs-opt-out.md index 4e7adf58f..77a5819b2 100644 --- a/docs/getting-started/gs-opt-out.md +++ b/docs/getting-started/gs-opt-out.md @@ -54,9 +54,9 @@ The following steps provide a high-level outline of the workflow intended for us | Participant | Distribution Method | | :--- | :--- | - | Publishers | A publisher calling [POST /token/generate](../endpoints/post-token-generate.md) with the required `optout_check` parameter set to `1`, or [POST /token/refresh](../endpoints/post-token-refresh.md), receives the opt-out response instead of the UID2 token. | + | Publishers | A publisher calling [POST /token/generate](../endpoints/post-token-generate.md) with the required `optout_check` parameter set to `1`, or [POST /token/refresh](../endpoints/post-token-refresh.md), receives the opt-out response instead of the UID2 token. | | DSPs | The UID2 Operator Service distributes information on all opted-out users to DSPs via a webhook provided for the purpose. For details, see [Honor User Opt-Outs](../guides/dsp-guide#honor-user-opt-outs). | - | Advertisers | The UID2 Operator Service distributes opt-out information to advertisers via the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. | + | Advertisers | The UID2 Operator Service distributes opt-out information to advertisers via the [POST /identity/map](../endpoints/post-identity-map.md) endpoint. | This workflow allows users to consent to the creation of UID2 identifiers and manage their UID2 consent and privacy settings through the Transparency and Control Portal. @@ -64,7 +64,7 @@ This workflow allows users to consent to the creation of UID2 identifiers and ma diff --git a/docs/getting-started/gs-permissions.md b/docs/getting-started/gs-permissions.md index 4ca5268a8..27d3f9069 100644 --- a/docs/getting-started/gs-permissions.md +++ b/docs/getting-started/gs-permissions.md @@ -17,7 +17,7 @@ The following table lists the key permissions, the types of participants that co | 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: | +| 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 bid stream from publishers into raw UID2s for bidding purposes. | | Sharer | Any participant type that takes part in UID2 sharing. For details, see [UID2 Sharing: Overview](../sharing/sharing-overview.md). | Permission to do both of the following: | -| Mapper | Advertisers
Data Providers | Permission to use the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint to monitor rotated salt buckets and to use the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. | +| Mapper | Advertisers
Data Providers | Permission to use the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint to monitor rotated salt buckets and to use the [POST /identity/map](../endpoints/post-identity-map.md) endpoint to map multiple email addresses, phone numbers, or their respective hashes to their raw UID2s and salt bucket IDs. | diff --git a/docs/guides/advertiser-dataprovider-guide.md b/docs/guides/advertiser-dataprovider-guide.md index 407230421..21c292f5a 100644 --- a/docs/guides/advertiser-dataprovider-guide.md +++ b/docs/guides/advertiser-dataprovider-guide.md @@ -40,8 +40,8 @@ Refer to the following sections for details about the different parts of the dia | Step | Endpoint | Description | | --- | --- | --- | -| 1-a | [POST /identity/map](../endpoints/post-identity-map.md) request | Send a request containing DII to the identity mapping endpoint. | -| 1-b | [POST /identity/map](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.
The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [3: Monitor for salt bucket rotations](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).
For ease of maintenance, a recommended approach is to store a user's raw UID2 and `bucket_id` in a mapping table. For guidance on incremental updates, see [Use an incremental process to continuously update raw UID2s](#use-an-incremental-process-to-continuously-update-raw-uid2s). | +| 1-a | [POST /identity/map](../endpoints/post-identity-map.md) request | Send a request containing DII to the identity mapping endpoint. | +| 1-b | [POST /identity/map](../endpoints/post-identity-map.md) response | The `advertising_id` (raw UID2) returned in the response can be used to target audiences on relevant DSPs.
The response returns a user's raw UID2 and the corresponding `bucket_id` for the salt bucket. The salt assigned to the bucket rotates annually, which impacts the generated raw UID2. For details on how to check for salt bucket rotation, see [3: Monitor for salt bucket rotations](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-raw-uid2s).
For ease of maintenance, a recommended approach is to store a user's raw UID2 and `bucket_id` in a mapping table. For guidance on incremental updates, see [Use an incremental process to continuously update raw UID2s](#use-an-incremental-process-to-continuously-update-raw-uid2s). | ### 2: Send stored raw UID2s to DSPs to create audiences @@ -56,10 +56,10 @@ Even though each salt bucket is updated approximately once per year, individual | Step | Endpoint | Description | | --- | --- | --- | -| 3-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the bucket status endpoint for all salt buckets that have changed since a specific timestamp. | -| 3-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The bucket status endpoint returns a list of `bucket_id` and `last_updated` timestamps. | -| 3-c | [POST /identity/map](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.
If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the identity mapping service for a new raw UID2. | -| 3-d | [POST /identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. | +| 3-a | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | Send a request to the bucket status endpoint for all salt buckets that have changed since a specific timestamp. | +| 3-b | [POST /identity/buckets](../endpoints/post-identity-buckets.md) | UID2 service: The bucket status endpoint returns a list of `bucket_id` and `last_updated` timestamps. | +| 3-c | [POST /identity/map](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of raw UID2s that you've cached.
If you find that the salt bucket was updated for one or more raw UID2s, re-send the DII to the identity mapping service for a new raw UID2. | +| 3-d | [POST /identity/map](../endpoints/post-identity-map.md) | Store the new values returned for `advertising_id` and `bucket_id`. | ## Use an Incremental Process to Continuously Update Raw UID2s diff --git a/docs/guides/custom-publisher-integration.md b/docs/guides/custom-publisher-integration.md index e8b1b6f00..8439ef5ca 100644 --- a/docs/guides/custom-publisher-integration.md +++ b/docs/guides/custom-publisher-integration.md @@ -70,8 +70,8 @@ After authentication in step 1-c, which includes getting the user's consent and | Step | Endpoint | Description | | :--- | :--- | :--- | -| 1-d | [POST /token/generate](../endpoints/post-token-generate.md) | There are two ways for publishers to establish identity with UID2:
- Integrate with a UID2-enabled single-sign-on provider.
- Use the [POST /token/generate](../endpoints/post-token-generate.md) endpoint to generate a UID2 token using the normalized email address or phone number of the user. | -| 1-e | [POST /token/generate](../endpoints/post-token-generate.md) | Return a UID2 token generated from the user's hashed or unhashed email address or phone number, plus associated values such as the refresh token. | +| 1-d | [POST /token/generate](../endpoints/post-token-generate.md) | There are two ways for publishers to establish identity with UID2:
- Integrate with a UID2-enabled single-sign-on provider.
- Use the [POST /token/generate](../endpoints/post-token-generate.md) endpoint to generate a UID2 token using the normalized email address or phone number of the user. | +| 1-e | [POST /token/generate](../endpoints/post-token-generate.md) | Return a UID2 token generated from the user's hashed or unhashed email address or phone number, plus associated values such as the refresh token. | | 1-f | N/A | Place the returned `advertising_token` and `refresh_token` in a store tied to a user. You might consider client-side storage, such as a first-party cookie, or server-side storage. | ### Bid Using a UID2 Token @@ -91,11 +91,11 @@ Use the `POST /token/refresh` endpoint to make sure you always have a valid and | Step | Endpoint | Description | | :--- | :--- | :--- | | 3-a |N/A | When a user returns to an asset and becomes active again, refresh the UID2 token before sending it to the SSP. | -| 3-b | [POST /token/refresh](../endpoints/post-token-refresh.md) | Send the `refresh_token` obtained in step [1-e](#establish-identity) as a query parameter. | -| 3-c | [POST /token/refresh](../endpoints/post-token-refresh.md) | The UID2 service issues a new identity token for users that haven't opted out. | +| 3-b | [POST /token/refresh](../endpoints/post-token-refresh.md) | Send the `refresh_token` obtained in step [1-e](#establish-identity) as a query parameter. | +| 3-c | [POST /token/refresh](../endpoints/post-token-refresh.md) | The UID2 service issues a new identity token for users that haven't opted out. | | 3-d | N/A| Place the values returned by the `POST /token/refresh` endpoint, `advertising_token` and `refresh_token`, so that they are linked to the user. You might consider client-side storage, such as a first-party cookie, or server-side storage. | ->TIP: Refresh tokens starting from the `refresh_from` timestamp, which is part of the identity returned by the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints. +>TIP: Refresh tokens starting from the `refresh_from` timestamp, which is part of the identity returned by the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoints. ### Clear Identity: User Logout diff --git a/docs/guides/google-ss-integration.md b/docs/guides/google-ss-integration.md index cba7d02a1..bfbc8a850 100644 --- a/docs/guides/google-ss-integration.md +++ b/docs/guides/google-ss-integration.md @@ -59,7 +59,7 @@ window.googletag.cmd.push(function () { So that it can share encrypted signals, the hosted auto-loaded secure signals script must be able to make an asynchronous call to the `window.getUid2AdvertisingToken` function and, in response, receive `advertising_token` as a string. -It's important to make sure that the identity token is fresh. For a server-side integration, we recommend making a call to the [POST /token/refresh](../endpoints/post-token-refresh.md#post-tokenrefresh) endpoint to get a fresh [advertising token](../endpoints/post-token-refresh.md#decrypted-json-response-format) from the JSON response. +It's important to make sure that the identity token is fresh. For a server-side integration, we recommend making a call to the [POST /token/refresh](../endpoints/post-token-refresh.md#post-tokenrefresh) endpoint to get a fresh [advertising token](../endpoints/post-token-refresh.md#decrypted-json-response-format) from the JSON response. The following code is an example of how you could do this. diff --git a/docs/guides/integration-javascript-standard.md b/docs/guides/integration-javascript-standard.md index 5b8475c21..d93f19484 100644 --- a/docs/guides/integration-javascript-standard.md +++ b/docs/guides/integration-javascript-standard.md @@ -71,8 +71,8 @@ After authentication in step 1-c, which forces the user to accept the rules of e | Step | Endpoint/SDK | Description | | :--- | :--- | :--- | -| 1-d | [POST /token/generate](../endpoints/post-token-generate.md) | After the user authenticates and authorizes the creation of a UID2, use the [POST /token/generate](../endpoints/post-token-generate.md) endpoint to generate a UID2 token using the email address or phone number provided by the user. Make sure it is normalized. | -| 1-e | [POST /token/generate](../endpoints/post-token-generate.md) | The endpoint returns a UID2 token generated from the user's email address, phone number, or the respective hash. | +| 1-d | [POST /token/generate](../endpoints/post-token-generate.md) | After the user authenticates and authorizes the creation of a UID2, use the [POST /token/generate](../endpoints/post-token-generate.md) endpoint to generate a UID2 token using the email address or phone number provided by the user. Make sure it is normalized. | +| 1-e | [POST /token/generate](../endpoints/post-token-generate.md) | The endpoint returns a UID2 token generated from the user's email address, phone number, or the respective hash. | | 1-f | UID2 SDK for JavaScript | The SDK sends the returned UID2 token from step 1-e to the SDK in the `identity` property of its [init() function](../sdks/client-side-identity.md#initopts-object-void). | | 1-g | UID2 SDK for JavaScript | Provide the SDK a callback function that will receive identity updates from the SDK and use them to initiate targeted advertising. | @@ -198,7 +198,7 @@ As part of its initialization, the SDK sets up a [token auto-refresh](../sdks/cl | Step | Endpoint/SDK | Description | | :--- | :--- | :--- | | 3-a | [UID2 SDK for JavaScript](../sdks/client-side-identity.md) | The SDK automatically refreshes UID2 tokens in the background. No manual action is required. | -| 3-b | [UID2 SDK for JavaScript](../sdks/client-side-identity.md) | If the user hasn't opted out, the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint automatically returns new identity tokens. | +| 3-b | [UID2 SDK for JavaScript](../sdks/client-side-identity.md) | If the user hasn't opted out, the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint automatically returns new identity tokens. | ### Clear Identity: User Logout diff --git a/docs/guides/integration-prebid-server-side.md b/docs/guides/integration-prebid-server-side.md index fe64131bb..99373c1b3 100644 --- a/docs/guides/integration-prebid-server-side.md +++ b/docs/guides/integration-prebid-server-side.md @@ -96,7 +96,7 @@ You'll need to configure the UID2 Prebid module to complete the following two ac ### Generating a UID2 Token on the Server -To generate a token, call the [POST /token/generate](../endpoints/post-token-generate.md) endpoint. +To generate a token, call the [POST /token/generate](../endpoints/post-token-generate.md) endpoint. For an example, see [Sample Token](#sample-token). @@ -113,8 +113,8 @@ There are two ways to refresh a UID2 token, as shown in the following table. You must provide the Prebid module with the full JSON response body from the applicable endpoint: -- [POST /token/generate](../endpoints/post-token-generate.md) for a new UID2 token. -- [POST /token/refresh](../endpoints/post-token-refresh.md) for a refreshed UID2 token. +- [POST /token/generate](../endpoints/post-token-generate.md) for a new UID2 token. +- [POST /token/refresh](../endpoints/post-token-refresh.md) for a refreshed UID2 token. For an example, see [Sample Token](#sample-token). diff --git a/docs/sdks/client-side-identity-v2.md b/docs/sdks/client-side-identity-v2.md index 20210b619..da59f931b 100644 --- a/docs/sdks/client-side-identity-v2.md +++ b/docs/sdks/client-side-identity-v2.md @@ -64,7 +64,7 @@ This SDK is in the following open-source GitHub repository: ## Terminology In this document, the following terms apply: -- **Identity** refers to a package of values, returned by the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint, that includes the UID2 token, the refresh token, and associated values such as timestamps. +- **Identity** refers to a package of values, returned by the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint, that includes the UID2 token, the refresh token, and associated values such as timestamps. - **Advertising token** refers to the UID2 token. ## Include the SDK Script @@ -117,7 +117,7 @@ Here's what you need to know about the token auto-refresh: - Only one token refresh call can be active at a time. -- If the [POST /token/refresh](../endpoints/post-token-refresh.md) response is unsuccessful because the user has opted out, or because the refresh token has expired, this suspends the background auto-refresh process and requires a new login ([isLoginRequired()](#isloginrequired-boolean) returns `true`). In all other cases, auto-refresh attempts continue in the background. +- If the [POST /token/refresh](../endpoints/post-token-refresh.md) response is unsuccessful because the user has opted out, or because the refresh token has expired, this suspends the background auto-refresh process and requires a new login ([isLoginRequired()](#isloginrequired-boolean) returns `true`). In all other cases, auto-refresh attempts continue in the background. - The [callback function](#callback-function) specified during the SDK initialization is invoked in the following cases: - After each successful refresh attempt. - After an initial failure to refresh an expired advertising token. @@ -151,7 +151,7 @@ Here's what you need to know about this function: - You can call `init()` any time after the SDK has been loaded by the corresponding script tag, typically during page loading. - Initialization calls require a [callback function](#callback-function) that is invoked after the SDK is initialized. -- When creating an instance for the UID2 lifecycle on the client, the `identity` property in the `init()` call refers to the `body` property of the response JSON object returned from a successful [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) call with the server-side generated identity. +- When creating an instance for the UID2 lifecycle on the client, the `identity` property in the `init()` call refers to the `body` property of the response JSON object returned from a successful [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) call with the server-side generated identity. - Since the SDK relies on [first-party cookies](#uid2-cookie-format) to store the passed UID2 information for the session, a call to `init()` made by a page on a different domain might not be able to access the cookie. You can adjust the settings used for the cookie with the `cookieDomain` and `cookiePath` options. - To tune specific behaviors, initialization calls might include optional configuration [parameters](#parameters). @@ -200,8 +200,8 @@ The `opts` object supports the following properties. | Property | Data Type | Attribute | Description | Default Value | | :--- | :--- | :--- | :--- | :--- | | `callback` | `function(object): void` | Required | The function that the SDK should invoke after validating the passed identity. For details, see [Callback Function](#callback-function).| N/A | -| `identity` | object | Optional | The `body` property value from a successful [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) call that has been run on the server to generate an identity.
To use the identity from a [first-party cookie](#uid2-cookie-format), leave this property empty. | N/A | -| `baseUrl` | string | Optional | The custom base URL of the UID2 operator to use when invoking the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint.
For example: `https://my.operator.com`. | `https://prod.uidapi.com`. | +| `identity` | object | Optional | The `body` property value from a successful [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) call that has been run on the server to generate an identity.
To use the identity from a [first-party cookie](#uid2-cookie-format), leave this property empty. | N/A | +| `baseUrl` | string | Optional | The custom base URL of the UID2 operator to use when invoking the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint.
For example: `https://my.operator.com`. | `https://prod.uidapi.com`. | | `refreshRetryPeriod` | number | Optional | The number of seconds after which to retry refreshing tokens if intermittent errors occur. | 5 | | `cookieDomain` | string | Optional | The domain name string to apply to the [UID2 cookie](#uid2-cookie-format).
For example, if the `baseUrl` is `https://my.operator.com`, the `cookieDomain` value might be `operator.com`. | `undefined` | | `cookiePath` | string | Optional | The path string to apply to the [UID2 cookie](#uid2-cookie-format). | `/` | @@ -292,7 +292,7 @@ This function can be called before or after the [init()](#initopts-object-void) ### isLoginRequired(): boolean -Specifies whether a UID2 login ([POST /token/generate](../endpoints/post-token-generate.md) call) is required. +Specifies whether a UID2 login ([POST /token/generate](../endpoints/post-token-generate.md) call) is required. This function can also provide additional context for handling missing identities, as shown in [Workflow States and Transitions](#workflow-states-and-transitions). @@ -329,7 +329,7 @@ After this function is executed, the [getAdvertisingToken()](#getadvertisingtoke Terminates any background timers or requests. The UID2 object remains in an unspecified state and cannot be used anymore. -This function is intended for use in advanced scenarios where you might want to replace the existing UID2 object with a new instance. For example, a single-page application could use this to clear the current UID2 object and construct or initialize a new one after receiving a new identity from the server in the [POST /token/generate](../endpoints/post-token-generate.md) response. +This function is intended for use in advanced scenarios where you might want to replace the existing UID2 object with a new instance. For example, a single-page application could use this to clear the current UID2 object and construct or initialize a new one after receiving a new identity from the server in the [POST /token/generate](../endpoints/post-token-generate.md) response. ## UID2 Cookie Format @@ -342,13 +342,13 @@ The following table lists the cookie properties. | Properties | Default Value | Comments | | :--- | :--- | :--- | | `Name` | `__uid_2` | N/A | -| `Expiry` | N/A | The value is the refresh token expiration timestamp as specified in the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) response. | +| `Expiry` | N/A | The value is the refresh token expiration timestamp as specified in the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) response. | | `Path` | `/` | If you want to use a different value, you can set it during SDK initialization using the `cookiePath` [init() parameter](#parameters). | | `Domain` | `undefined` | If you want to use a different value, you can set it during SDK initialization using the `cookieDomain` [init() parameter](#parameters). | ### Contents Structure -The UID2 cookie contents are a URI-encoded string representation of a JSON object with the structure identical to that of the `body` property in a [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) response, with the exception of the `private` object. +The UID2 cookie contents are a URI-encoded string representation of a JSON object with the structure identical to that of the `body` property in a [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) response, with the exception of the `private` object. The following is an example of the UID2 cookie structure: diff --git a/docs/sdks/client-side-identity.md b/docs/sdks/client-side-identity.md index 99706cade..5052c835b 100644 --- a/docs/sdks/client-side-identity.md +++ b/docs/sdks/client-side-identity.md @@ -71,7 +71,7 @@ The SDK is published in these locations: ## Terminology In this document, the following terms apply: -- **Identity** refers to a package of values, returned by the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint, that includes the UID2 token, the refresh token, and associated values such as timestamps. +- **Identity** refers to a package of values, returned by the [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint, that includes the UID2 token, the refresh token, and associated values such as timestamps. - **Advertising token** refers to the UID2 token. - **Callback function** refers to a callback function built for the current version of this SDK and registered using the [Array Push Pattern](#array-push-pattern). - **Legacy callback function** refers to a callback function built for version 1.x or 2.x of this SDK and registered in the call to `init`. @@ -126,7 +126,7 @@ As part of the SDK [initialization](#initopts-object-void), a token auto-refresh Here's what you need to know about the token auto-refresh: - Only one token refresh call can be active at a time. -- If the [POST /token/refresh](../endpoints/post-token-refresh.md) response is unsuccessful because the user has opted out, or because the refresh token has expired, this suspends the background auto-refresh process and requires a new login. In all other cases, auto-refresh attempts continue in the background. +- If the [POST /token/refresh](../endpoints/post-token-refresh.md) response is unsuccessful because the user has opted out, or because the refresh token has expired, this suspends the background auto-refresh process and requires a new login. In all other cases, auto-refresh attempts continue in the background. - All [callback functions](#callback-function) provided using the [Array Push Pattern](#array-push-pattern) are invoked in the following cases: - After each successful refresh attempt. - When identity has become invalid—for example, because the user has opted out.
NOTE: The callback is *not* invoked when identity is temporarily unavailable and the auto-refresh keeps failing. In this case, the SDK continues using the existing advertising token as long as it hasn't expired. @@ -265,7 +265,7 @@ Initializes the SDK and establishes user identity for targeted advertising. Here's what you need to know about this function: - You can call `init()` any time after the SDK has been loaded. The recommended way to do this is by registering a callback function that handles the `SdkLoaded` event using the [Array Push Pattern](#array-push-pattern). By using this pattern you can make sure that your code works regardless of script load order, and that using `async` or `defer` on your script tags does not cause UID2 SDK errors. -- The `identity` property in the `init()` call refers to the `body` property of the response JSON object returned from a successful [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) call with the server-side generated identity. This is a good way to provide the identity if your server-side integration ensures you always have a current token available and it is more convenient to provide it using JavaScript. +- The `identity` property in the `init()` call refers to the `body` property of the response JSON object returned from a successful [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) call with the server-side generated identity. This is a good way to provide the identity if your server-side integration ensures you always have a current token available and it is more convenient to provide it using JavaScript. - If the `identity` property in the `init()` call is falsy, the SDK attempts to load the identity from local storage or the cookie. - Once `init()` is complete, all callbacks receive the `InitCompleted` event. If the `identity` property on the payload of this event is null, no identity could be loaded, and you should therefore [provide a valid identity](#provide-identity). This is the recommended way to provide an identity if your server-side integration does not ensure a current identity is always available, and you need to request it from the server only when necessary. - If you are using a first-party cookie (see [UID2 Storage Format](#uid2-storage-format)) to store the passed UID2 information for the session, a call to `init()` made by a page on a different domain might not be able to access the cookie. You can adjust the settings used for the cookie with the `cookieDomain` and `cookiePath` options. @@ -313,8 +313,8 @@ The `opts` object supports the following properties. | Property | Data Type | Attribute | Description | Default Value | | :--- | :--- | :--- | :--- | :--- | -| `identity` | object | Optional | The `body` property value from a successful [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) call that has been run on the server to generate an identity.
To use the identity from a first-party cookie (see [UID2 Storage Format](#uid2-storage-format)), leave this property empty. | N/A | -| `baseUrl` | string | Optional | The custom base URL of the UID2 operator to use when invoking the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint.
For example: `https://my.operator.com`. | `https://prod.uidapi.com`. | +| `identity` | object | Optional | The `body` property value from a successful [POST /token/generate](../endpoints/post-token-generate.md) or [POST /token/refresh](../endpoints/post-token-refresh.md) call that has been run on the server to generate an identity.
To use the identity from a first-party cookie (see [UID2 Storage Format](#uid2-storage-format)), leave this property empty. | N/A | +| `baseUrl` | string | Optional | The custom base URL of the UID2 operator to use when invoking the [POST /token/refresh](../endpoints/post-token-refresh.md) endpoint.
For example: `https://my.operator.com`. | `https://prod.uidapi.com`. | | `refreshRetryPeriod` | number | Optional | The number of milliseconds after which to retry refreshing a token if an intermittent error occurs.
This value must be >= 1000. | 5000 | | `cookieDomain` | string | Optional | The domain name string to apply to the UID2 cookie (see [UID2 Storage Format](#uid2-storage-format)).
For example, if the `baseUrl` is `https://my.operator.com`, the `cookieDomain` value might be `operator.com`. | `undefined` | | `cookiePath` | string | Optional | The path string to apply to the UID2 cookie (see [UID2 Storage Format](#uid2-storage-format)). | `/` | @@ -391,7 +391,7 @@ It might be easier to use the [callback function](#callback-function) to be noti ### isLoginRequired(): boolean -Specifies whether a UID2 login ([POST /token/generate](../endpoints/post-token-generate.md) call) is required. +Specifies whether a UID2 login ([POST /token/generate](../endpoints/post-token-generate.md) call) is required. ```html