diff --git a/README.md b/README.md index 0c6d7bc56..de96c02ba 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,14 @@ -# Unified ID 2.0 API Documentation +# UID 2.0 -## Table Of Contents -* [Overview](#overview) -* [Environment](#environment) -* [Authentication](#authentication) -* [Error Codes](#error-codes) -* [Email Normalization](#email-normalization) -* [Encoding Query Parameter Values](#encode-query-parameter-values) -* [Endpoints](#endpoints) -* [Integration Workflows](#integration-workflows) -* [License](#license) +| [Click here to visit the UID 2.0 API Documentation](/api/README.md) +## Introduction -## Overview +Addressable advertising enables publishers and developers to provide the content and services consumers have come to enjoy, whether through mobile apps, streaming TV, or web experiences. This value exchange of the open internet has not always been well understood by, or communicated to, consumers. As the industry reduces reliance on the third-party cookie, we have an opportunity to move towards a new and better approach to identity for the open internet. This improved approach empowers content creators to have the value exchange conversations with consumers while giving them more control and transparency over their data. -**Building a better foundation for identity on the open internet** +Unified ID 2.0 (UID2) is a deterministic identifier based on PII (e.g., email or phone number) with complete user transparency and privacy controls. The UID2 identifier ties logged-in experiences from publisher websites, mobile apps, and CTV apps. With several layers of security and privacy measures, UID2s safely distribute across the open internet. Initially built by The Trade Desk, responsibility for UID2 will transfer in mid-2021 to independent organizations for open-source code management, governance, administration, and system operations. UID2 is non-proprietary and accessible to constituents across the advertising ecosystem - including Advertisers, Publishers, DSPs, SSPs, SSOs, CDPs, CMPs, Identity Providers, Data Providers, and Measurement Providers - while they remain in compliance with a code of conduct. -Addressable advertising enables publishers and developers to provide the content and services consumers have come to enjoy, whether through mobile apps, streaming TV, or web experiences. The value exchange of the open internet has not always been well understood by, or communicated to, consumers. As the industry reduces reliance on the third-party cookie, we have an opportunity to move towards a new and better approach to identity for the open internet. The improved approach empowers content creators to have value exchange conversations with consumers while giving them more control and transparency over their data. - -Unified ID 2.0 (UID2) is a deterministic identifier based on authenticated PII (e.g., email or phone number) with complete user transparency and privacy controls. The UID2 identifier ties to logged-in experiences applied to publisher websites, mobile apps, and CTV apps. With several layers of privacy protection, UID2s can safely distribute across the open internet. Initially built by The Trade Desk, operational responsibility for UID2 will transfer in mid-2021 to an independent organization. The independent organization will open-source the relevant code. UID2 is non-proprietary and accessible to constituents across the advertising ecosystem - including Advertisers, Publishers, DSPs, SSPs, SSOs, CDPs, CMPs, Identity Providers, Data Providers, and Measurement Providers - while they remain in compliance with a code of conduct. - -UID2’s goal is to enable deterministic identity for advertising opportunities on the open internet with full consumer transparency and controls. UID2 provides a collaborative framework for all constituents and a healthy, open internet by utilizing a transparent and interoperable approach. - -**Guiding Principles** - -+ Independently Governed: UID2 will be operated by unbiased organizations, with the transition from The Trade Desk to independent governance anticipated mid-2021. The Trade Desk built the framework and code to transition to the independent governing body. -+ Interoperable: UID2 is accessible to all constituents in the advertising ecosystem who abide by the code of conduct. This includes DSPs, SSPs, data providers, measurement providers, and identity services. -+ Open Source: UID2 is transparent and offers its code open-source. -+ Nonproprietary: UID2 provides a collaborative framework for all constituents in the advertising ecosystem who are willing to comply with a code of conduct. -+ Secure and Privacy-Safe: UID2 leverages multiple layers of security, cryptography, and encryption to ensure user PII and data is safe. -+ Transparency and Consent: Users understand where their ID is shared and what data is associated with it. Users have control to revoke their consent and permissions. - -**Contact Info** - -If you want to contact the relevant team at The Trade Desk to access UID2, please use the email aliases below. Note that this is only temporary, and when the system moves to independent governance access will be through various industry groups. -+ UID2publishers@thetradedesk.com - If you are a publisher or developer -+ UID2partners@thetradedesk.com - If you are a brand, agency, data provider, DSP, SSP, CDP, or related company - -## Environment - -All UID2 endpoints use the same base URL. - -| Environment | Base URL | -| --- | --- | -| Testing | ```https://integ.uidapi.com/v1``` | - -e.g. https://integ.uidapi.com/v1/token/generate - -## Authentication - -Authenticate to UID2 endpoints using a bearer token in the request's authorization header. Contact %placeholder% to request a bearer token. - -```Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=``` - -## Email Normalization - -When sending email addresses in a request, normalize email addresses prior to sending. - -1. Remove leading and trailing spaces. -2. Remove `.` (ASCII code 46) from the username of the email address. `jane.doe@example.com` normalizes to `janedoe@example.com`. -3. Remove `+` (ASCII code 43) and all subsequent characters from the username of the email address. `janedoe+home@example.com` normalizes to `janedoe@example.com`. -4. Convert all ASCII characters to lowercase. - -## Encoding Query Parameter Values - -When passing query parameter values in with a request, ensure the query parameter value is URL-encoded. Use Javascript's `encodeURIcomponent()` or your coding language's equivalent. - -## Response Structure and Status Codes - -All endpoints return responses utilizing the following body and status messaging structure. The `status` property may include endpoint-specific values. The `message` property returns additional information for non-`success` statuses. - -```json -{ - "status": [success|unauthorized|client_error|...] - "body": { - "property": "propertyValue" - } - "message": "Descriptive message" -} -``` - -| Status | HTTP Status Code | Additional Notes | -| --- | --- | --- | -| `success` | 200 | | -| `optout` | 200 | This status only returns for authorized requests. The user opted out. | -| `client_error` | 400 | See the `message` field for more information about missing or invalid parameters. | -| `invalid_token` | 400 | This status only returns for authorized requests. The request specified an invalid identity token. | -| `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 action. | - -## Endpoints - -[Click here to view an endpoint listing.](/v1/endpoints/README.md) - -## Integration Guides -See Integration guides [here.](/v1/guides/README.md) +UID2’s goal is to enable deterministic identity for advertising opportunities on the open internet with consumer transparency and controls. UID2 provides a collaborative framework for all constituents and a healthy, open internet by utilizing a transparent and interoperable approach. ## License -All work, articafts are licensed under the Apache License, Version 2.0. See [LICENSE](http://www.apache.org/licenses/LICENSE-2.0.txt) for the full license text. +All work and artifacts are licensed under the Apache License, Version 2.0. See [LICENSE](http://www.apache.org/licenses/LICENSE-2.0.txt) for the full license text. \ No newline at end of file diff --git a/api/README.md b/api/README.md new file mode 100644 index 000000000..677aaab13 --- /dev/null +++ b/api/README.md @@ -0,0 +1,106 @@ +# Unified ID 2.0 API Documentation + +## Table Of Contents +* [Overview](#overview) +* [Contact Info](#contact-info) +* [Environment](#environment) +* [Authentication](#authentication) +* [Email Normalization](#email-normalization) +* [Encoding Query Parameter Values](#encoding-query-parameter-values) +* [Response Structure and Status Codes](#response-structure-and-status-codes) +* [Endpoints](#endpoints) +* [Integration Guides](#integration-guides) +* [License](#license) + + +## Overview + +**Building a better foundation for identity on the open internet** + +Addressable advertising enables publishers and developers to provide the content and services consumers have come to enjoy, whether through mobile apps, streaming TV, or web experiences. The value exchange of the open internet has not always been well understood by, or communicated to, consumers. As the industry reduces reliance on the third-party cookie, we have an opportunity to move towards a new and better approach to identity for the open internet. The improved approach empowers content creators to have value exchange conversations with consumers while giving them more control and transparency over their data. + +Unified ID 2.0 (UID2) is a deterministic identifier based on authenticated PII (e.g., email or phone number) with complete user transparency and privacy controls. The UID2 identifier ties to logged-in experiences applied to publisher websites, mobile apps, and CTV apps. With several layers of privacy protection, UID2s can safely distribute across the open internet. Initially built by The Trade Desk, operational responsibility for UID2 will transfer in mid-2021 to an independent organization. The independent organization will open-source the relevant code. UID2 is non-proprietary and accessible to constituents across the advertising ecosystem - including Advertisers, Publishers, DSPs, SSPs, SSOs, CDPs, CMPs, Identity Providers, Data Providers, and Measurement Providers - while they remain in compliance with a code of conduct. + +UID2’s goal is to enable deterministic identity for advertising opportunities on the open internet with full consumer transparency and controls. UID2 provides a collaborative framework for all constituents and a healthy, open internet by utilizing a transparent and interoperable approach. + +**Guiding Principles** + ++ Independently Governed: UID2 will be operated by unbiased organizations, with the transition from The Trade Desk to independent governance anticipated mid-2021. The Trade Desk built the framework and code to transition to the independent governing body. ++ Interoperable: UID2 is accessible to all constituents in the advertising ecosystem who abide by the code of conduct. This includes DSPs, SSPs, data providers, measurement providers, and identity services. ++ Open Source: UID2 is transparent and offers its code open-source. ++ Nonproprietary: UID2 provides a collaborative framework for all constituents in the advertising ecosystem who are willing to comply with a code of conduct. ++ Secure and Privacy-Safe: UID2 leverages multiple layers of security, cryptography, and encryption to ensure user PII and data is safe. ++ Transparency and Control: Users understand where their ID is shared and what data is associated with it. Users have control to revoke their consent and permissions. + +## Contact Info + +For access to UID2, contact the relevant team at The Trade Desk shown below. Contacting The Trade Desk for access is temporary. When the system moves to independent governance, the governing organizations will handle access requests. + +| If you are a... | Contact Email | +| --- | --- | +| App Developer
Publisher | UID2publishers@thetradedesk.com | +| Agency
Brand
CDP
Data Provider
DSP
SSP | UID2partners@thetradedesk.com | + +## Environment + +All UID2 endpoints use the same base URL. + +| Environment | Base URL | +| --- | --- | +| Testing | ```https://integ.uidapi.com/v1``` | + +e.g. https://integ.uidapi.com/v1/token/generate + +## Authentication + +Authenticate to UID2 endpoints using a bearer token in the request's authorization header. + +```Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=``` + +## Email Normalization + +When sending email addresses in a request, normalize email addresses prior to sending. + +1. Remove leading and trailing spaces. +2. Convert all ASCII characters to lowercase. + +For email accounts ending in gmail.com: + +1. Remove `.` (ASCII code 46) from the username of the email address. `jane.doe@gmail.com` normalizes to `janedoe@gmail.com`. +2. Remove `+` (ASCII code 43) and all subsequent characters from the username of the email address. `janedoe+home@gmail.com` normalizes to `janedoe@gmail.com`. + +## Encoding Query Parameter Values + +When passing query parameter values in with a request, ensure the query parameter value is URL-encoded. Use Javascript's `encodeURIcomponent()` or your coding language's equivalent. + +## Response Structure and Status Codes + +All endpoints return responses utilizing the following body and status messaging structure. The `status` property may include endpoint-specific values. The `message` property returns additional information for non-`success` statuses. + +```json +{ + "status": [success|unauthorized|client_error|...] + "body": { + "property": "propertyValue" + } + "message": "Descriptive message" +} +``` + +| Status | HTTP Status Code | Additional Notes | +| --- | --- | --- | +| `success` | 200 | | +| `optout` | 200 | This status only returns for authorized requests. The user opted out. | +| `client_error` | 400 | See the `message` field for more information about missing or invalid parameters. | +| `invalid_token` | 400 | This status only returns for authorized requests. The request specified an invalid identity token. | +| `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 action. | + +## Endpoints + +[Click here to view an endpoint listing.](./v1/endpoints/README.md) + +## Integration Guides +[Click here to view integration guides.](./v1/guides/README.md) + +## License +All work and artifacts are licensed under the Apache License, Version 2.0. See [LICENSE](http://www.apache.org/licenses/LICENSE-2.0.txt) for the full license text. diff --git a/v1/.gitkeep b/api/v1/.gitkeep similarity index 100% rename from v1/.gitkeep rename to api/v1/.gitkeep diff --git a/v1/endpoints/.gitkeep b/api/v1/endpoints/.gitkeep similarity index 100% rename from v1/endpoints/.gitkeep rename to api/v1/endpoints/.gitkeep diff --git a/v1/endpoints/README.md b/api/v1/endpoints/README.md similarity index 83% rename from v1/endpoints/README.md rename to api/v1/endpoints/README.md index b676760f8..6090ca98f 100644 --- a/v1/endpoints/README.md +++ b/api/v1/endpoints/README.md @@ -1,4 +1,4 @@ -[UID2 Documentation](../../README.md) > v1 > Endpoints +[UID2 API Documentation](../../README.md) > v1 > Endpoints # Endpoints @@ -9,7 +9,6 @@ | [GET /token/generate](./get-token-generate.md) | Generate a UID2 token from an email address or hashed email address. | | [GET /token/validate](./get-token-validate.md) | Validate that an advertising token matches the provided email or email hash. | | [GET /token/refresh](./get-token-refresh.md) | Generate a new token for a user by specifying their refresh_token from GET /token/generate. | -| | | ## Identity Maps diff --git a/api/v1/endpoints/get-identity-buckets.md b/api/v1/endpoints/get-identity-buckets.md new file mode 100644 index 000000000..217d68a5b --- /dev/null +++ b/api/v1/endpoints/get-identity-buckets.md @@ -0,0 +1,53 @@ +[UID2 API Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /identity/buckets + +# GET /identity/buckets + +Monitor for rotated salt buckets. No salt buckets will be rotated until September 1, 2021. The `body` will return empty until rotations on September 1, 2021 or after. + +Integration workflows that use this endpoint: +* [Advertiser/Data Provider](../guides/advertiser-dataprovider-guide.md) + +## Request + +```GET '{environment}/{version}/identity/buckets?{queryParameter}={queryParameterValue}'``` + +### Query Parameters + +| Query Parameter | Data Type | Attributes | Description | +| --- | --- | --- | --- | +| `since_timestamp` | `date-time` or `integer` | Required | Return buckets with last updated UTC timestamps after the specified date and time.
Specify the the time in ISO 8601 `date-time` format (`YYYY-MM-DDThh:mm:ss`). Ensure the parameter value is URL encoded. | + +#### Example Request + +```curl +curl -L -X GET 'https://integ.uidapi.com/v1/identity/buckets?since_timestamp=2021-03-01T01%3A01%3A01' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' +``` + +## Response + +The endpoint returns a list of ```bucket_id``` and their last updated timestamps. + +```json +{ + "body":[ + { + "bucket_id":"a3pPl64opk", + "last_updated":"2021-03-01T00:00:00" + }, + { + "bucket_id":"aENdq9K3VQ", + "last_updated":"2021-03-01T00:00:00" + }, + { + "bucket_id":"adVEM9ywVo", + "last_updated":"2021-03-01T00:00:00" + } + ], + "status":"success" +} +``` + +| Property | Format | Description | +| --- | --- | --- | +| `bucket_id` | `string` | The bucket_id associated to the timestamp. | +| `last_Updated` | `date-time` | The UTC timestamp of the last time the bucket salt was rotated in ISO 8601 format (`YYYY-MM-DDThh:mm:ss`) | \ No newline at end of file diff --git a/api/v1/endpoints/get-identity-map.md b/api/v1/endpoints/get-identity-map.md new file mode 100644 index 000000000..96cdf80d2 --- /dev/null +++ b/api/v1/endpoints/get-identity-map.md @@ -0,0 +1,56 @@ +[UID2 API Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /identity/map + +# GET /identity/map + +Retrieve advertising and bucket IDs for one `email` or `email_hash`. + +Integration workflows that use this endpoint: +* [Advertiser/Data Provider](../guides/advertiser-dataprovider-guide.md) + +## Request + +```GET '{environment}/{version}/identity/map?{queryParameter}={queryParameterValue}'``` + +### Query Parameters + +| Query Parameter | Data Type | Attributes | Description | +| --- | --- | --- | --- | +| `email` | `string` | Conditionally Required | The [normalized email address](../../README.md#emailnormalization) of a user. Required when `email_hash` is not included in the request. | +| `email_hash` | `string` | Conditionally Required | The base64-encoded SHA256 hash of the [normalized email address](../../README.md#emailnormalization) of a user. Required when `email` is not included in the request. | + +If `email` and `email_hash` are both supposed in the same request, only the `email` will return a mapping response. + +#### Example Request Using an Email Address + +```sh +curl -L -X GET 'https://integ.uidapi.com/v1/identity/map?email=username@example.com' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' +``` + +#### Example Request Using an Email Hash + +```sh +curl -L -X GET 'https://integ.uidapi.com/v1/identity/map?email_hash=eVvLS%2FVg%2BYZ6%2Bz3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc%3D' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' +``` + +## Response + +The response is a JSON object containing the user's UID2 identifier and bucket identifier. + +```json +{ + "body": { + "identifier": "username@example.com", + "advertising_id": "AdvtiSuYWAZSYe8t4n6sQx0gshoHYZdOzg9qUn/eKgE=", + "bucket_id": "bucketId" + }, + "status":"success" +} +``` + +## Body Response Properties + +| Property | Data Type | Description | +| --- | --- | --- | +| `body.identifier` | `string` | The `email` or `email_hash` provided in the request. | +| `body.advertising_id` | `string` | The identity's advertising ID (raw UID2). | +| `body.bucket_id` | `string` | The identifier of the bucket used for salting the user's `advertising_id`. | \ No newline at end of file diff --git a/v1/endpoints/get-token-generate.md b/api/v1/endpoints/get-token-generate.md similarity index 72% rename from v1/endpoints/get-token-generate.md rename to api/v1/endpoints/get-token-generate.md index 0a7826cf0..90c1004e1 100644 --- a/v1/endpoints/get-token-generate.md +++ b/api/v1/endpoints/get-token-generate.md @@ -1,8 +1,12 @@ -[UID2 Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /token/generate +[UID2 API Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /token/generate # GET /token/generate Generate a UID2 token from an email address or hashed email address. +Integration workflows that use this endpoint: +* [Publisher - Standard](../guides/publisher-client-side.md) +* [Publisher - Custom](../guides/custom-publisher-integration.md) + ## Request ```GET '{environment}/{version}/token/generate?{queryParameter}={queryParameterValue}'``` @@ -11,10 +15,10 @@ Generate a UID2 token from an email address or hashed email address. | Query Parameter | Data Type | Attributes | Description | | --- | --- | --- | --- | -| `email` | `string` | Conditionally Required | The normalized email address of a user. Required when `email_hash` is not included in the request. | -| `email_hash` | `string` | Conditionally Required | Base64 encoded SHA256 hash of the normalized email address of a user. Required when `email` is not included in the request. | +| `email` | `string` | Conditionally Required | The [normalized email address](../../README.md#emailnormalization) of a user. Required when `email_hash` is not included in the request. | +| `email_hash` | `string` | Conditionally Required | The base64-encoded SHA256 hash of the [normalized email address](../../README.md#emailnormalization) of a user. Required when `email` is not included in the request. | -Note: Parameter `email` takes presedence in presence of both `email` and `email_hash` parameters +If `email` and `email_hash` are both supplied in the same request, only the `email` will return a mapping response. #### Example Request Using an Email Address @@ -44,7 +48,6 @@ The response is a JSON object containing the user's advertising, user, and refre { "body": { "advertising_token": "AdvertisingTokenmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=", - "user_token": "UserToken2QQSpWVRd25AGt/HMRtw42u7xzTxBcvWpV3c9NjUbl6WAKS4ycJbWMhmcMo5UsWaMGvds9RhkuA5262tc2B9IfJQmjDLxGfDg+RDUl6qrQTdLkLtQgQooIvEt5/OvIKfg==", "refresh_token": "RefreshToken2F8AAAF2cskumF8AAAF2cskumF8AAAADXwFq/90PYmajV0IPrvo51Biqh7/M+JOuhfBY8KGUn//GsmZr9nf+jIWMUO4diOA92kCTF69JdP71Ooo+yF3V5yy70UDP6punSEGmhf5XSKFzjQssCtlHnKrJwqFGKpJkYA==" }, "status": "success" @@ -56,7 +59,6 @@ The response is a JSON object containing the user's advertising, user, and refre | Property | Data Type | Description | | --- | --- | --- | | `advertising_token` | `string` | An encrypted token for advertising. a.k.a UID Token | -| `user_token` | `string` | An encrypted token containing privacy bits, which should only be used by the source site. | | `refresh_token` | `string` | An encrypted token that can be exchanged with the Unified ID 2.0 Service for the latest set of identity tokens. | diff --git a/v1/endpoints/get-token-refresh.md b/api/v1/endpoints/get-token-refresh.md similarity index 79% rename from v1/endpoints/get-token-refresh.md rename to api/v1/endpoints/get-token-refresh.md index 8be0546e4..c69759e79 100644 --- a/v1/endpoints/get-token-refresh.md +++ b/api/v1/endpoints/get-token-refresh.md @@ -1,8 +1,12 @@ -[UID2 Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /token/refresh +[UID2 API Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /token/refresh # GET /token/refresh Generate a new token for a user by specifying their `refresh_token` obtained from earlier response from [GET /token/generate](./get-token-generate.md). +Integration workflows that use this endpoint: +* [Publisher - Standard](../guides/publisher-client-side.md) +* [Publisher - Custom](../guides/custom-publisher-integration.md) + ## Request ```GET '{environment}/{version}/token/refresh?{queryParameter}={queryParameterValue}'``` @@ -11,7 +15,7 @@ Generate a new token for a user by specifying their `refresh_token` obtained fro | Query Parameter | Data Type | Attributes | Description | | --- | --- | --- | --- | -| `refresh_token` | `string` | Required | The `refresh_token` returned for a user from [GET /token/generate](./get-token-generate.md).| +| `refresh_token` | `string` | Required | The `refresh_token` returned for a user from [GET /token/generate](./get-token-generate.md). Some `refresh_tokens` are generated with URL decoded characters. Please encode the `refresh_token` as a query parameter. | #### Example Request @@ -31,22 +35,20 @@ The response is a JSON object containing new identity tokens for a user or a mes { "body": { "advertising_token": "NewAdvertisingTokenIjb6u6KcMAtd0/4ZIAYkXvFrMdlZVqfb9LNf99B+1ysE/lBzYVt64pxYxjobJMGbh5q/HsKY7KC0Xo5Rb/Vo8HC4dYOoWXyuGUaL7Jmbw4bzh+3pgokelUGyTX19DfArTeIg7n+8cxWQ=", - "user_token": "NewUserTokenksmJSzlosNBOa+mMDu1A3tDarYBIIG4DbeSYn1t33mU6Dl65g5alI+tFHi87ArzK34nZMv7/VtF2NHYDoi4DSXfrqpaAetg76v8a4NUzdLkLtQgQooIvEt5/OvIKfg==", "refresh_token": "NewRefreshTokenAAAF2c8H5dF8AAAF2c8H5dF8AAAADX393Vw94afoVLL6A+qjdSUEisEKx6t42fLgN+2dmTgUavagz0Q6Kp7ghM989hKhZDyAGjHyuAAwm+CX1cO7DWEtMeNUA9vkWDjcIc8yeDZ+jmBtEaw07x/cxoul6fpv2PQ==" }, "status": "success" } ``` - -Note: For opted out user, the response status will be "success" with token values being empty strings. +If a user opted out before the refresh request, the refresh response status will be `success` with empty token values. ### Supplemental Status Information | HTTP Status Code | Status | Response | Description | | --- | --- | --- | --- | | 200 | `success` | Body with identity tokens. | | -| 200 | `optout` | This status only appears for authorized requests and indicates that the user associated to the supplied `refresh_token` opted out. | +| 200 | `optout` | This status only appears for authorized requests and indicates that the user associated with the supplied `refresh_token` opted out. | | 400 | `clienterror` | `Required Parameter Missing: refresh_token` | Ensure the `refresh_token` parameter and value are included with your request. | | 400 | `invalid_token` | `Invalid Token presented {refresh_token_value}` | This message only appears for authorized requests and indicates that the supplied `refresh_token` is invalid. | diff --git a/v1/endpoints/get-token-validate.md b/api/v1/endpoints/get-token-validate.md similarity index 87% rename from v1/endpoints/get-token-validate.md rename to api/v1/endpoints/get-token-validate.md index eb99815cb..076223b96 100644 --- a/v1/endpoints/get-token-validate.md +++ b/api/v1/endpoints/get-token-validate.md @@ -1,8 +1,9 @@ -[UID2 Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /token/validate +[UID2 API Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /token/validate # GET /token/validate -Validate that an advertising token matches the provided email or email hash. -Please use the email or email hash of `validate@email.com` with this endpoint. +Validate that an advertising token matches the provided email or email hash. This is primarily used for testing and troubleshooting new integrations and is not a primary step in the publisher workflow. + +The only accepted email or email hash for this endpoint is `validate@email.com`. ## Request @@ -49,4 +50,3 @@ The response is a JSON object. - diff --git a/api/v1/endpoints/post-identity-map.md b/api/v1/endpoints/post-identity-map.md new file mode 100644 index 000000000..cce72cbcf --- /dev/null +++ b/api/v1/endpoints/post-identity-map.md @@ -0,0 +1,64 @@ +[UID2 API Documentation](../../README.md) > v1 > [Endpoints](./README.md) > POST /identity/map + +# POST /identity/map + +Retrieve advertising and bucket IDs for multiple email addresses or email hashes. Send a maximum of 10,000 combined `email` or `email_hash` per request. + +Integration workflows that use this endpoint: +* [Advertiser/Data Provider](../guides/advertiser-dataprovider-guide.md) + +## Request + +```POST '{environment}/{version}/identity/map'``` + +### Request Properties + +| Property | Data Type | Attributes | Description | +| --- | --- | --- | --- | +| `email` | `string` | Conditionally Required | The [normalized email address](../../README.md#emailnormalization) of a user. Required when `email_hash` is not included in the request. | +| `email_hash` | `string` | Conditionally Required | The base64-encoded SHA256 hash of the [normalized email address](../../README.md#emailnormalization) of a user. Required when `email` is not included in the request. | + +#### Example Request Using an Email Address and an Email Hash + +```sh +curl -L -X POST 'https://integ.uidapi.com/identity/map' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' -H 'Content-Type: application/json' --data-raw '{ + "email":[ + "user@example.com" + ], + "email_hash":[ + "eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=" + ] +}' +``` + +## Response + +The response is a JSON object containing the user's UID2 identifier and bucket identifier. + +```json +{ + "body":{ + "mapped": [ + { + "identifier": "user@example.com", + "advertising_id": "AdvtiSuYWAZSYe8t4n6sQx0gshoHYZdOzg9qUn/eKgE=", + "bucket_id": "bucketId" + }, + { + "identifier": "eVvLS/Vg+YZ6+z3i0NOpSXYyQAfEXqCZ7BTpAjFUBUc=", + "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", + "bucket_id": "bucketId" + } + ] + }, + "status":"success" +} +``` + +## Body Response Properties + +| Property | Data Type | Description | +| --- | --- | --- | +| `body.mapped.identifier` | `string` | The `email` or `email_hash` provided in the request. | +| `body.mapped.advertising_id` | `string` | The identity's advertising ID (raw UID2). | +| `body.mapped.bucket_id` | `string` | The identifier of the bucket used for salting the user's `advertising_id`. | \ No newline at end of file diff --git a/api/v1/guides/README.md b/api/v1/guides/README.md new file mode 100644 index 000000000..9301638e5 --- /dev/null +++ b/api/v1/guides/README.md @@ -0,0 +1,12 @@ +[UID2 API Documentation](../../README.md) > v1 > Integration Guides + +# Integration Guides + +Learn more about UID2 integration by selecting the scenario that best aligns with your organization. + +| Business Entity | Description | +| --- | --- | +| [Publisher - Standard](./publisher-client-side.md) | This integration guide for publishers covers standard web integration scenarios. | +| [Publisher - Custom](./custom-publisher-integration.md) | This integration guide for publishers covers custom integration scenarios for app developers and CTV broadcasters. | +| [DSP](./dsp-guide.md) | This integration guide for DSPs covers handling UID2s for bidding and honoring user opt-outs. | +| [Advertiser/Data Provider](./advertiser-dataprovider-guide.md) | This integration guide for advertisers and data partners covers integration workflows for mapping identity for audience-building and targeting. | \ No newline at end of file diff --git a/api/v1/guides/advertiser-dataprovider-guide.md b/api/v1/guides/advertiser-dataprovider-guide.md new file mode 100644 index 000000000..76d5bc571 --- /dev/null +++ b/api/v1/guides/advertiser-dataprovider-guide.md @@ -0,0 +1,51 @@ +[UID2 API Documentation](../../README.md) > v1 > Integration Guides > Advertiser/Data Provider Integration Guide + +# Overview + +This guide covers integration steps for organizations that collect user data and push it to DSPs. Data collectors include advertisers, data on-boarders, measurement providers, identity graph providers, third-party data providers, and other organizations who send data to DSPs. + +# Integration Steps + +This section outlines the steps data collectors complete to map PII to UID2 identifiers for audience-building and targeting. PII refers to a user's normalized email address or SHA256-hashed and normalized email address. + +![Advertiser Flow](https://mermaid.ink/svg/eyJjb2RlIjoiICBzZXF1ZW5jZURpYWdyYW1cbiAgICBwYXJ0aWNpcGFudCBEUCBhcyBEYXRhIFByb3ZpZGVyXG4gICAgcGFydGljaXBhbnQgVUlEMiBhcyBVSUQyIFNlcnZpY2VcbiAgICBwYXJ0aWNpcGFudCBEU1BcbiAgICBsb29wIDEuIFJldHJpZXZlIGEgVUlEMiBmb3IgUElJIHVzaW5nIHRoZSBpZGVudGl0eSBtYXAgZW5kcG9pbnRzLlxuICAgIERQLT4-VUlEMjogMS1hLiBTZW5kIGEgcmVxdWVzdCBjb250YWluaW5nIFBJSSB0byB0aGUgaWRlbnRpdHkgbWFwcGluZyBlbmRwb2ludHMuXG4gICAgVUlEMi0-PkRQOiAxLWIuIFN0b3JlIHRoZSBVSUQyIGFuZCBzYWx0IGJ1Y2tldCByZXR1cm5lZCBmcm9tIHRoZSBpZGVudGl0eSBtYXBwaW5nIHNlcnZpY2UuXG4gICAgZW5kXG4gICAgRFAtLT4-RFNQOiAyLiBTZW5kIHN0b3JlZCBVSUQycyB0byBEU1BzIHRvIGNyZWF0ZSBhdWRpZW5jZXMuXG5cbiAgICBsb29wIDMuIE1vbml0b3IgZm9yIHNhbHQgYnVja2V0IHJvdGF0aW9ucyByZWxhdGVkIHRvIHlvdXIgc3RvcmVkIFVJRDJzLlxuICAgICAgIERQLT4-VUlEMjogMy1hLiBNb25pdG9yIHNhbHQgYnVja2V0IHJvdGF0aW9ucyB1c2luZyB0aGUgYnVja2V0IHNlcnZpY2UuXG4gICAgICAgVUlEMi0-PkRQOiAzLWIuIFJldHVybiBzYWx0IGJ1Y2tldHMgcm90YXRlZCBzaW5jZSBhIGdpdmVuIHRpbWVzdGFtcC5cbiAgICAgICBEUC0-PlVJRDI6IDMtYy4gQ29tcGFyZSB0aGUgcm90YXRlZCBzYWx0IGJ1Y2tldHMgdG8gc3RvcmVkIFVJRDIgc2FsdCBidWNrZXRzLjxicj5JZiByb3RhdGVkLCByZXNlbmQgUElJIHRvIGlkZW50aXR5IG1hcHBpbmcgc2VydmljZSBmb3IgYSBuZXcgVUlEMi5cbiAgICAgICBVSUQyLT4-RFA6IDMtZC4gU3RvcmUgdGhlIFVJRDIgYW5kIHNhbHQgYnVja2V0IHJldHVybmVkIGZyb20gdGhlIGlkZW50aXR5IG1hcHBpbmcgc2VydmljZS5cbiAgICBlbmRcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJmb3Jlc3QifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0) + +## 1. Retrieve a UID2 for PII using the identity map endpoints. + +| Step | Endpoint | Instruction | +| --- | --- | --- | +| a | [GET /identity/map](../endpoints/get-identity-map.md)
[POST /identity/map](../endpoints/post-identity-map.md) | Send a request containing PII to the identity mapping endpoints. | +| b | [GET /identity/map](../endpoints/get-identity-map.md)
[POST /identity/map](../endpoints/post-identity-map.md) | The returned `advertising_id` (UID2) can be used to target audiences on relevant DSPs.

The response returns a user's UID2 and a salt `bucket_id` that rotates annually. When a user's UID2 updates, the salt bucket remains the same. See [3](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-uid2s) for how to check for salt bucket rotation.

We recommend storing a user's UID2 and `bucket_id` in a mapping table for ease of maintenance. See [4](#4-use-an-incremental-process-to-continuously-update-uid2s) for guidance on incremental updates. | + +## 2. Send UID2 to a DSP to build an audience. +Send the `advertising_id` (UID2) from [1](#1-retrieve-a-uid2-for-pii-using-the-identity-map-endpoints) to a DSP while building your audiences. Each DSP has a unique integration process for building audiences. Please follow the integration guidance provided by the DSP for sending UID2s to build an audience. + +## 3. Monitor for salt bucket rotations related to your stored UID2s. +Because a UID2 is an identifier for a user at a particular moment in time, a user's UID2 will rotate at least once a year. + +We recommend checking salt bucket rotation daily for active users. While salt buckets rotate annually, the date they rotate may change. Checking salt bucket rotation every day ensures your integration has the current UID2s. + +| Step | Endpoint | Instruction | +| --- | --- | --- | +| a | [GET /identity/buckets](../endpoints/get-identity-buckets.md) | Send a request to the bucket status endpoint for all salt buckets changed since a given timestamp. | +| b | [GET /identity/buckets](../endpoints/get-identity-buckets.md) | The bucket status endpoint will return a list of `bucket_id` and `last_updated` timestamps. | +| c | [GET /identity/map](../endpoints/get-identity-map.md)
[POST /identity/map](../endpoints/post-identity-map.md) | Compare the returned `bucket_id` to the salt buckets of UID2s you've cached.
If a UID2's salt bucket rotated, resent the PII to the identity mapping service for a new UID2. | +| d | [GET /identity/map](../endpoints/get-identity-map.md)
[POST /identity/map](../endpoints/post-identity-map.md) | Store the returned `advertising_id` and `bucket_id`. | + +## 4. Use an incremental process to continuously update UID2s. + +Continuously update and maintain UID2-based audiences utilizing the preceding steps. + +The response from [1](#1-retrieve-a-uid2-for-pii-using-the-identity-map-endpoints) contains mapping information. Cache the mapping between PII (`identifier`), UID2 (`advertising_id`), and salt bucket (`bucket_id`), along with a last updated timestamp. + +Using the results of [3](#3-monitor-for-salt-bucket-rotations-related-to-your-stored-uid2s), repeat [1](#1-retrieve-a-uid2-for-pii-using-the-identity-map-endpoints) to remap UID2s with rotated salt buckets. Repeat [2](#2-send-uid2-to-a-dsp-to-build-an-audience) to update the UID2s in audiences. + +# Frequently Asked Questions +## 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 PII used to generate a UID2. Use the [GET /identity/buckets](../endpoints/get-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. This workflow typically applies to data providers. + +## How often should UIDs be refreshed for incremental updates? +The recommended cadence for updating audiences is daily. + +## How should I generate the SHA256 of PII for mapping? +The system should follow the [email normalization rules](../../README.md#email-normalization) and hash without salting. The value needs to be base64-encoded before sending. \ No newline at end of file diff --git a/api/v1/guides/advertiser-flow-mermaid.md b/api/v1/guides/advertiser-flow-mermaid.md new file mode 100644 index 000000000..80840734c --- /dev/null +++ b/api/v1/guides/advertiser-flow-mermaid.md @@ -0,0 +1,17 @@ + sequenceDiagram + participant DP as Data Provider + participant UID2 as UID2 Service + participant DSP + loop 1. Retrieve a UID2 for PII using the identity map endpoints. + DP->>UID2: 1-a. Send a request containing PII to the identity mapping endpoints. + UID2->>DP: 1-b. Store the UID2 and salt bucket returned from the identity mapping service. + end + DP-->>DSP: 2. Send stored UID2s to DSPs to create audiences. + loop 3. Monitor for salt bucket rotations related to your stored UID2s. + DP->>UID2: 3-a. Monitor salt bucket rotations using the bucket service. + UID2->>DP: 3-b. Return salt buckets rotated since a given timestamp. + DP->>UID2: 3-c. Compare the rotated salt buckets to stored UID2 salt buckets.
If rotated, resend PII to identity mapping service for a new UID2. + UID2->>DP: 3-d. Store the UID2 and salt bucket returned from the identity mapping service. + end + + diff --git a/v1/guides/advertiser-flow-mermaid.png b/api/v1/guides/advertiser-flow-mermaid.png similarity index 100% rename from v1/guides/advertiser-flow-mermaid.png rename to api/v1/guides/advertiser-flow-mermaid.png diff --git a/api/v1/guides/custom-publisher-flow-mermaid.md b/api/v1/guides/custom-publisher-flow-mermaid.md new file mode 100644 index 000000000..e2050deca --- /dev/null +++ b/api/v1/guides/custom-publisher-flow-mermaid.md @@ -0,0 +1,49 @@ + sequenceDiagram + participant U as User + participant P as Publisher + participant UID2 as UID2 Service + participant SSP + Note over U,SSP: 1. Establish Identity + U->>+P: 1-a. The user visits a publisher asset. + P->>-U: 1-b. The publisher explains the value exchange of the open internet and requests a login. + activate U + U->>P: 1-c. The user authenticates and authorizes the creation of a UID2. + deactivate U + activate P + P->>UID2: 1-d. The publisher sends the user's PII to the token generation service. + deactivate P + activate UID2 + UID2->>P: 1-e. The token generation service returns UID2 tokens. + deactivate UID2 + activate P + P->>U: 1-f. The publisher sets a UID2 for the user. + deactivate P + Note over U,SSP: 2. Bid Using UID2 Tokens + + P->>SSP: 2-a. The publisher calls the SSP for ads using the UID2 token. + activate SSP + SSP->>P: 2-b. The SSP returns ads to display. + deactivate SSP + activate P + P->>U: 2-c. The publisher displays the ads to the user. + deactivate P + + Note over U,SSP: 3. Refresh Tokens + U->>P: 3-a. The user returns to a publisher asset. + activate P + P->>UID2: 3-b. The publisher uses a refresh token to request new identity tokens for the user. + deactivate P + activate UID2 + UID2->>P: 3-c. If a user hasn't opted out, the refresh token service returns new identity tokens. + deactivate UID2 + activate P + P->>U: 3-d. The publisher sets the new UID2 for the user. + deactivate P + + Note over U,SSP: 4. User Logout + U->>P: 4-a. The user logs out from a publisher asset. + activate P + P->>U: 4-b. The user's identity clears. + deactivate P + + \ No newline at end of file diff --git a/v1/guides/custom-publisher-flow-mermaid.md.svg b/api/v1/guides/custom-publisher-flow-mermaid.md.svg similarity index 100% rename from v1/guides/custom-publisher-flow-mermaid.md.svg rename to api/v1/guides/custom-publisher-flow-mermaid.md.svg diff --git a/v1/guides/custom-publisher-flow-mermaid.png b/api/v1/guides/custom-publisher-flow-mermaid.png similarity index 100% rename from v1/guides/custom-publisher-flow-mermaid.png rename to api/v1/guides/custom-publisher-flow-mermaid.png diff --git a/api/v1/guides/custom-publisher-integration.md b/api/v1/guides/custom-publisher-integration.md new file mode 100644 index 000000000..c5a75d7d7 --- /dev/null +++ b/api/v1/guides/custom-publisher-integration.md @@ -0,0 +1,78 @@ +[UID2 API Documentation](../../README.md) > v1 > [Integration Guides](README.md) > Custom Publisher Integration Guide + +# Overview + +This guide covers integration steps for app developers and CTV broadcasters who would like to generate identity tokens utilizing UID2 for the bid stream. This guide focuses on publishers who would like to integrate directly with UID2 to create and manage tokens rather than integrate with UID2-enabled single-sign-on or identity providers. + +## Integration Steps + +The following integration steps outline the lifecycle for a user establishing a UID2 token with a publisher and how the UID2 token integrates with the RTB bid stream. + +![Custom Publisher Flow](https://mermaid.ink/svg/eyJjb2RlIjoiICBzZXF1ZW5jZURpYWdyYW1cbiAgICBwYXJ0aWNpcGFudCBVIGFzIFVzZXJcbiAgICBwYXJ0aWNpcGFudCBQIGFzIFB1Ymxpc2hlclxuICAgIHBhcnRpY2lwYW50IFVJRDIgYXMgVUlEMiBTZXJ2aWNlXG4gICAgcGFydGljaXBhbnQgU1NQXG4gICAgTm90ZSBvdmVyIFUsU1NQOiAxLiBFc3RhYmxpc2ggSWRlbnRpdHlcbiAgICBVLT4-K1A6IDEtYS4gVGhlIHVzZXIgdmlzaXRzIGEgcHVibGlzaGVyIGFzc2V0LlxuICAgIFAtPj4tVTogMS1iLiBUaGUgcHVibGlzaGVyIGV4cGxhaW5zIHRoZSB2YWx1ZSBleGNoYW5nZSBvZiB0aGUgb3BlbiBpbnRlcm5ldCBhbmQgcmVxdWVzdHMgYSBsb2dpbi5cbiAgICBhY3RpdmF0ZSBVXG4gICAgVS0-PlA6IDEtYy4gVGhlIHVzZXIgYXV0aGVudGljYXRlcyBhbmQgYXV0aG9yaXplcyB0aGUgY3JlYXRpb24gb2YgYSBVSUQyLlxuICAgIGRlYWN0aXZhdGUgVVxuICAgIGFjdGl2YXRlIFBcbiAgICBQLT4-VUlEMjogMS1kLiBUaGUgcHVibGlzaGVyIHNlbmRzIHRoZSB1c2VyJ3MgUElJIHRvIHRoZSB0b2tlbiBnZW5lcmF0aW9uIHNlcnZpY2UuXG4gICAgZGVhY3RpdmF0ZSBQXG4gICAgYWN0aXZhdGUgVUlEMlxuICAgIFVJRDItPj5QOiAxLWUuIFRoZSB0b2tlbiBnZW5lcmF0aW9uIHNlcnZpY2UgcmV0dXJucyBVSUQyIHRva2Vucy5cbiAgICBkZWFjdGl2YXRlIFVJRDJcbiAgICBhY3RpdmF0ZSBQXG4gICAgUC0-PlU6IDEtZi4gVGhlIHB1Ymxpc2hlciBzZXRzIGEgVUlEMiBmb3IgdGhlIHVzZXIuXG4gICAgZGVhY3RpdmF0ZSBQXG4gICAgTm90ZSBvdmVyIFUsU1NQOiAyLiBCaWQgVXNpbmcgVUlEMiBUb2tlbnNcbiAgXG4gICAgUC0-PlNTUDogMi1hLiBUaGUgcHVibGlzaGVyIGNhbGxzIHRoZSBTU1AgZm9yIGFkcyB1c2luZyB0aGUgVUlEMiB0b2tlbi5cbiAgICBhY3RpdmF0ZSBTU1BcbiAgICBTU1AtPj5QOiAyLWIuIFRoZSBTU1AgcmV0dXJucyBhZHMgdG8gZGlzcGxheS5cbiAgICBkZWFjdGl2YXRlIFNTUFxuICAgIGFjdGl2YXRlIFBcbiAgICBQLT4-VTogMi1jLiBUaGUgcHVibGlzaGVyIGRpc3BsYXlzIHRoZSBhZHMgdG8gdGhlIHVzZXIuXG4gICAgZGVhY3RpdmF0ZSBQXG5cbiAgICBOb3RlIG92ZXIgVSxTU1A6IDMuIFJlZnJlc2ggVG9rZW5zXG4gICAgVS0-PlA6IDMtYS4gVGhlIHVzZXIgcmV0dXJucyB0byBhIHB1Ymxpc2hlciBhc3NldC5cbiAgICBhY3RpdmF0ZSBQXG4gICAgUC0-PlVJRDI6IDMtYi4gVGhlIHB1Ymxpc2hlciB1c2VzIGEgcmVmcmVzaCB0b2tlbiB0byByZXF1ZXN0IG5ldyBpZGVudGl0eSB0b2tlbnMgZm9yIHRoZSB1c2VyLlxuICAgIGRlYWN0aXZhdGUgUFxuICAgIGFjdGl2YXRlIFVJRDJcbiAgICBVSUQyLT4-UDogMy1jLiBJZiBhIHVzZXIgaGFzbid0IG9wdGVkIG91dCwgdGhlIHJlZnJlc2ggdG9rZW4gc2VydmljZSByZXR1cm5zIG5ldyBpZGVudGl0eSB0b2tlbnMuXG4gICAgZGVhY3RpdmF0ZSBVSUQyXG4gICAgYWN0aXZhdGUgUFxuICAgIFAtPj5VOiAzLWQuIFRoZSBwdWJsaXNoZXIgc2V0cyB0aGUgbmV3IFVJRDIgZm9yIHRoZSB1c2VyLlxuICAgIGRlYWN0aXZhdGUgUFxuXG4gICAgTm90ZSBvdmVyIFUsU1NQOiA0LiBVc2VyIExvZ291dFxuICAgIFUtPj5QOiA0LWEuIFRoZSB1c2VyIGxvZ3Mgb3V0IGZyb20gYSBwdWJsaXNoZXIgYXNzZXQuXG4gICAgYWN0aXZhdGUgUFxuICAgIFAtPj5VOiA0LWIuIFRoZSB1c2VyJ3MgaWRlbnRpdHkgY2xlYXJzLlxuICAgIGRlYWN0aXZhdGUgUCIsIm1lcm1haWQiOnsidGhlbWUiOiJmb3Jlc3QifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0) + +## 1. Establish Identity + +This section focuses on publisher-specific steps 1-d, 1-e, and 1-f illustrated in the above diagram. + +| Step | Endpoint/SDK | Instruction | +| --- | --- | --- | +| d | [GET /token/generate](../endpoints/get-token-generate.md) | There are two ways for publishers to establish identity with UID2.
1. Integrate with a UID2-enabled single-sign-on provider.
2. Generate UID2 tokens when a user authenticates using the [GET /token/generate](../endpoints/get-token-generate.md) endpoint. The request includes a user's normalized email address or the base64-encoded SHA256 hash of the user's normalized email address. [Click here to view email normalization rules.](../../README.md#emailnormalization) | +| e | [GET /token/generate](../endpoints/get-token-generate.md) | The token generation service returns UID2 tokens. | +| f | | Place the returned `advertising_token` and `refresh_token` in a store tied to a user. You may consider client-side storage like a first-party cookie or server-side storage. | + +## 2. Bid Using UID2 Tokens + +This section focuses on publisher-specific step 2-a illustrated in the above diagram. + +| Step | Endpoint/SDK | Instruction | +| --- | --- | --- | +| a | | The publisher sends the `advertising_token` from [1](#1-establish-identity) to the SSP for bidding. Send the value as-is. | + +### 3. Refresh Tokens + +Leverage the refresh endpoints to retrieve the latest version of UID2 tokens. UID2 token refreshes are required to sync a user's UID2 rotation and opt-out status. If a user opts out, using their refresh token will end their token refresh chain. + +| Step | Endpoint/SDK | Instruction | +| --- | --- | --- | +| a | | When a user returns to an asset and becomes active again, refresh the identity token before sending it to the SSP. | +| b | [GET /token/refresh](../endpoints/get-token-refresh.md) | Send the `refresh_token` obtained in [1](#1-establish-identity) as a query parameter. | +| c | [GET /token/refresh](../endpoints/get-token-refresh.md) | The UID2 service issues a new identity token for users that haven't opted out. | +| d | | Place the returned `advertising_token` and `refresh_token` in a store tied to a user. You may consider client-side storage like a first-party cookie or server-side storage. | + +We recommend refreshing active user identity tokens every 5 minutes. +There is no need to refresh tokens for inactive users. + +### 4. User Logout + +| Step | Endpoint/SDK | Instruction | +| --- | --- | --- | +| a | | The user logs out from a publisher asset. | +| b | | Remove the UID2 tokens you have stored for that user. No interaction with the UID2 service is required. | + +# Frequently Asked Questions + +### Do I need to decrypt tokens? +No, publishers do not need to decrypt tokens. + +### How will I be notified of user opt-out? +The token refresh process handles user opt-outs. Using their refresh token automatically clears their session and disrupts their ```refresh_token``` chain when a user opts out. No manual action is required. + +### What is the uniqueness and rotation policy for UID2 token? + +The UID2 service encrypts tokens using random initialization vectors. The encrypted UID2 is unique for a given user as they browse the internet. At every refresh, the token re-encrypts. This mechanism ensures that untrusted parties cannot track a user's identity. + +### How can I test my integration? +There are two built-in tools you can use to test your integration. + +#### Test that PII sent and returned tokens match +You can use the [GET /token/validate](../endpoints/get-token-validate.md) endpoint to check whether the PII you are sending through [GET /token/generate](../endpoints/get-token-generate.md) is valid. + +1. Send a [GET /token/generate](../endpoints/get-token-generate.md) request using `validate@email.com` as `email`, or create a base64-encoded SHA256 hash of `validate@email.com` and send it through as an email hash. Store the `advertising_token` returned to use in step 2. +2. Send a [GET /token/validate](../endpoints/get-token-validate.md) request using the `email` or `email_hash` you sent in step 1 and the `token` as the `advertising_token` returned in step 1. If the response returns `true`, the `email` or `email_hash` you sent as a request in step 1 match the token you received in the response of step 1. If it returns `false`, there may be an issue with the way you are sending email addresses or email hashes. + +#### Test refresh token logout workflow + +You can use the email address `optout@email.com` to test your token refresh workflow. Using this email for the request always generates an identity response with a `refresh_token` that results in a logout response. + +1. Send a [GET /token/generate](../endpoints/get-token-generate.md) request using `optout@email.com` as `email`, or create a base64-encoded SHA256 hash of `optout@email.com` and send it through as an email hash. Store the `refresh_token` returned to use in step 2. +2. Send a [GET /token/validate](../endpoints/get-token-validate.md) request using the `email` or `email_hash` you sent in step 1 and the `refresh_token` as the `refresh_token` returned in step 1. The `body` response should be empty because the `optout@email.com` email always results in a logged out refresh token. diff --git a/v1/guides/dsp-guide-flow-mermaid.md b/api/v1/guides/dsp-guide-flow-mermaid.md similarity index 100% rename from v1/guides/dsp-guide-flow-mermaid.md rename to api/v1/guides/dsp-guide-flow-mermaid.md diff --git a/v1/guides/dsp-guide-flow-mermaid.png b/api/v1/guides/dsp-guide-flow-mermaid.png similarity index 100% rename from v1/guides/dsp-guide-flow-mermaid.png rename to api/v1/guides/dsp-guide-flow-mermaid.png diff --git a/v1/guides/dsp-guide-optout-check-mermaid.md b/api/v1/guides/dsp-guide-optout-check-mermaid.md similarity index 100% rename from v1/guides/dsp-guide-optout-check-mermaid.md rename to api/v1/guides/dsp-guide-optout-check-mermaid.md diff --git a/v1/guides/dsp-guide-optout-check-mermaid.png b/api/v1/guides/dsp-guide-optout-check-mermaid.png similarity index 100% rename from v1/guides/dsp-guide-optout-check-mermaid.png rename to api/v1/guides/dsp-guide-optout-check-mermaid.png diff --git a/api/v1/guides/dsp-guide.md b/api/v1/guides/dsp-guide.md new file mode 100644 index 000000000..395435633 --- /dev/null +++ b/api/v1/guides/dsp-guide.md @@ -0,0 +1,50 @@ +[UID2 API Documentation](../../README.md) > v1 > [Integration Guides](README.md) > DSP Integration Guide + +# Overview + +This guide is for DSPs who transact on UID2s in the bid stream. + +# Integration Steps + +The following describes the integration workflow for DSP to support UID2 as part of RTB. + +There are two components for DSP integrations. +1. Decrypt UID2 tokens to use in RTB. +2. Honor user opt-outs. + +![DSP Flow](https://mermaid.ink/svg/eyJjb2RlIjoiICBzZXF1ZW5jZURpYWdyYW1cbiAgICBwYXJ0aWNpcGFudCBVIGFzIFVzZXJcbiAgICBwYXJ0aWNpcGFudCBQIGFzIFB1Ymxpc2hlclxuICAgIHBhcnRpY2lwYW50IFNTUFxuICAgIHBhcnRpY2lwYW50IERTUFxuICAgIHBhcnRpY2lwYW50IFRDIGFzIFRyYW5zcGFyZW5jeSAmIENvbnRyb2wgUG9ydGFsXG4gICAgVS0-PlA6IEEgdXNlciB2aXNpdHMgYSBwdWJsaXNoZXIgYXNzZXQuXG4gICAgUC0-PlNTUDogVGhlIHB1Ymxpc2hlciBtYWtlcyBhbiBSVEIgY2FsbC5cbiAgICBTU1AtPj5EU1A6IFRoZSBTU1AgY2FsbHMgYSBEU1AgZm9yIGJpZC5cbiAgICBsb29wIDEuIFVzZSBVSUQyIFRva2VucyBpbiBSVEJcbiAgICBEU1AtPj5EU1A6IDEtYS4gRGVjcnlwdCBVSUQyIHRva2Vucy5cbiAgICBEU1AtPj5EU1A6IDEtYi4gRXhlY3V0ZSBiaWRkaW5nIGxvZ2ljLlxuICAgIGVuZFxuICAgIGxvb3AgMi4gSG9ub3IgdXNlciBvcHQtb3V0LlxuICAgIFUtPj5UQzogMi1hLiBVc2VyIG9wdHMgb3V0IHRocm91Z2ggdGhlIFRyYW5zcGFyZW5jeSBhbmQgQ29udHJvbCBwb3J0YWwuXG4gICAgVEMtPj5EU1A6IDItYi4gRFNQIGhhbmRsZXMgb3B0LW91dC5cbiAgICBlbmRcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJmb3Jlc3QifSwidXBkYXRlRWRpdG9yIjpmYWxzZX0) + +## 1. Decrypt UID2 tokens to use in RTB. + +| Step | SDK | Instruction | +| --- | --- | --- | +| a | [DSP SDK](../sdks/dsp-client-v1-overview.md) | Leverage the provided SDK to decrypt incoming UID2 tokens. The response contains the `UID2` and the UID2 creation time (`established_timestamp`). DSPs are required to honor opt-out protocol for UID2s. Please see [2](#2-honor-user-opt-outs) for more information | + +Leverage the provided [SDK](../sdks/dsp-client-v1-overview.md) to decrypt incoming UID2 tokens. The response contains the UID2 and the UID2 creation time (`established_timestamp`). DSPs are required to check the most recent opt-out timestamp (`optout_timestamp`) for a UID2 and honor the opt-out. The following diagram illustrates opt-out logic. + +![DSP Opt Out Check](dsp-guide-optout-check-mermaid.png) + +The logic for the check opt-out step is: +```java +if (established_timestamp < optout_timestamp) { + // Opted out +} +``` +## 2. Honor user opt-outs. + +DSPs establish a pre-configured URL or endpoint for the UID2 service to send opt-outs generated by users through the Transparency and Control Portal. When the UID2 service calls the configured interface, it should record the opt-out timestamp for the corresponding UID2. + +The callback will contain the following data. + +| Parameter | Description | +| --- | --- | +| `identity` | The UID2 for the user who opted out | +| `timestamp` | The time when the user opted out | + + +# Frequently Asked Questions +### How do I know which decryption key to apply to a UID2? +Updating decryption keys is handled automatically by the provided [DSP SDK](../sdks/dsp-client-v1-overview.md). Metadata supplied with the UID2 token discloses the timestamp of encryption, which informs which decryption key applies. + +### Where do I get the decryption keys? +The [DSP SDK](../sdks/dsp-client-v1-overview.md) library communicates with the UID2 service in the background and periodically fetches the latest keys. \ No newline at end of file diff --git a/api/v1/guides/publisher-client-side.md b/api/v1/guides/publisher-client-side.md new file mode 100644 index 000000000..29c35e82f --- /dev/null +++ b/api/v1/guides/publisher-client-side.md @@ -0,0 +1,91 @@ +[UID2 API Documentation](../../README.md) > v1 > [Integration Guides](README.md) > Publisher Integration Guide + +# Overview + +This guide covers integration steps for publishers with web assets who would like to generate identity tokens utilizing UID2 for the bid stream. This guide focuses on publishers who would like to integrate directly with UID2 to create and manage tokens rather than integrate with UID2-enabled single-sign-on or identity providers. + +## Integration Steps + +The following integration steps outline the lifecycle for a user establishing a UID2 token with a publisher and how the UID2 token integrates with the RTB bid stream. + +![Publisher Flow](https://mermaid.ink/svg/eyJjb2RlIjoiICBzZXF1ZW5jZURpYWdyYW1cbiAgICBwYXJ0aWNpcGFudCBVIGFzIFVzZXJcbiAgICBwYXJ0aWNpcGFudCBQIGFzIFB1Ymxpc2hlclxuICAgIHBhcnRpY2lwYW50IFVJRDIgYXMgVUlEMiBTZXJ2aWNlXG4gICAgcGFydGljaXBhbnQgU1NQXG4gICAgTm90ZSBvdmVyIFUsU1NQOiAxLiBFc3RhYmxpc2ggSWRlbnRpdHlcbiAgICBVLT4-K1A6IDEtYS4gVGhlIHVzZXIgdmlzaXRzIGEgcHVibGlzaGVyIGFzc2V0LlxuICAgIFAtPj4tVTogMS1iLiBUaGUgcHVibGlzaGVyIGV4cGxhaW5zIHRoZSB2YWx1ZSBleGNoYW5nZSBvZiB0aGUgb3BlbiBpbnRlcm5ldCBhbmQgcmVxdWVzdHMgYSBsb2dpbi5cbiAgICBhY3RpdmF0ZSBVXG4gICAgVS0-PlA6IDEtYy4gVGhlIHVzZXIgYXV0aGVudGljYXRlcyBhbmQgYXV0aG9yaXplcyB0aGUgY3JlYXRpb24gb2YgYSBVSUQyLlxuICAgIGRlYWN0aXZhdGUgVVxuICAgIGFjdGl2YXRlIFBcbiAgICBQLT4-VUlEMjogMS1kLiBUaGUgcHVibGlzaGVyIHNlbmRzIHRoZSB1c2VyJ3MgUElJIHRvIHRoZSB0b2tlbiBnZW5lcmF0aW9uIHNlcnZpY2UuXG4gICAgZGVhY3RpdmF0ZSBQXG4gICAgYWN0aXZhdGUgVUlEMlxuICAgIFVJRDItPj5QOiAxLWUuIFRoZSB0b2tlbiBnZW5lcmF0aW9uIHNlcnZpY2UgcmV0dXJucyBVSUQyIHRva2Vucy5cbiAgICBkZWFjdGl2YXRlIFVJRDJcbiAgICBhY3RpdmF0ZSBQXG4gICAgUC0-PlU6IDEtZi4gVGhlIHB1Ymxpc2hlciBzZXRzIGEgVUlEMiBmb3IgdGhlIHVzZXIuXG4gICAgZGVhY3RpdmF0ZSBQXG4gICAgTm90ZSBvdmVyIFUsU1NQOiAyLiBCaWQgVXNpbmcgVUlEMiBUb2tlbnNcbiAgXG4gICAgUC0-PlNTUDogMi1hLiBUaGUgcHVibGlzaGVyIGNhbGxzIHRoZSBTU1AgZm9yIGFkcyB1c2luZyB0aGUgVUlEMiB0b2tlbi5cbiAgICBhY3RpdmF0ZSBTU1BcbiAgICBTU1AtPj5QOiAyLWIuIFRoZSBTU1AgcmV0dXJucyBhZHMgdG8gZGlzcGxheS5cbiAgICBkZWFjdGl2YXRlIFNTUFxuICAgIGFjdGl2YXRlIFBcbiAgICBQLT4-VTogMi1jLiBUaGUgcHVibGlzaGVyIGRpc3BsYXlzIHRoZSBhZHMgdG8gdGhlIHVzZXIuXG4gICAgZGVhY3RpdmF0ZSBQXG5cbiAgICBOb3RlIG92ZXIgVSxTU1A6IDMuIFJlZnJlc2ggVG9rZW5zXG4gICAgVS0-PlVJRDI6IDMtYS4gVGhlIFNESyBzZW5kcyBhIHJlcXVlc3QgdG8gcmVmcmVzaCB0aGUgVUlEMiB1c2luZyB0aGUgcmVmcmVzaCB0b2tlbi5cbiAgICBhY3RpdmF0ZSBVSUQyXG4gICAgVUlEMi0-PlU6IDMtYi4gSWYgYSB1c2VyIGhhc24ndCBvcHRlZCBvdXQsIHRoZSByZWZyZXNoIHRva2VuIHNlcnZpY2UgcmV0dXJucyBuZXcgaWRlbnRpdHkgdG9rZW5zLlxuICAgIGRlYWN0aXZhdGUgVUlEMlxuICAgIE5vdGUgb3ZlciBVLFNTUDogNC4gVXNlciBMb2dvdXRcbiAgICBVLT4-UDogNC1hLiBUaGUgdXNlciBsb2dzIG91dCBmcm9tIGEgcHVibGlzaGVyIGFzc2V0LlxuICAgIGFjdGl2YXRlIFBcbiAgICBQLT4-VTogNC1iLiBUaGUgdXNlcidzIGlkZW50aXR5IGNsZWFycy5cbiAgICBkZWFjdGl2YXRlIFAiLCJtZXJtYWlkIjp7InRoZW1lIjoiZm9yZXN0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9) + +### 1. Establish Identity + +This section focuses on publisher-specific steps 1-d, 1-e, and 1-f illustrated in the above diagram. + +| Step | Endpoint/SDK | Instruction | +| --- | --- | --- | +| d | [GET /token/generate](../endpoints/get-token-generate.md) | There are two ways for publishers to establish identity with UID2.
1. Integrate with a UID2-enabled single-sign-on provider.
2. Generate UID2 tokens when a user authenticates using the [GET /token/generate](../endpoints/get-token-generate.md) endpoint. The request includes a user's normalized email addres +| e | [GET /token/generate](../endpoints/get-token-generate.md) | The token generation service returns UID2 tokens. | +| f | [UID2 client-side identity SDK](../sdks/client-side-identity-v1.md) | Send returned UID2 tokens from step e to the SDK using `identity` mechanism below. The mechanism ensures UID2 tokens are available for the user until they logout. | + +#### Client-Side SDK Identity Mechanism + +```html + +``` + +### 2. Bid Using UID2 Tokens + +This section focuses on publisher-specific step 2-a illustrated in the above diagram. + +| Step | Endpoint/SDK | Instruction | +| --- | --- | --- | +| a | [UID2 client-side identity SDK](../sdks/client-side-identity-v1.md) | The established identity is available client-side for bidding. The mechnanism below returns access to a user's `advertising_token` to pass to SSPs. | + +#### Client-Side SDK Identity Access Mechanism + +```html + +``` + +### 3. Refresh Tokens + +| Step | Endpoint/SDK | Instruction | +| --- | --- | --- | +| a | [UID2 client-side identity SDK](../sdks/client-side-identity-v1.md) | The SDK automatically refreshes UID2 tokens. No manual action is required. | +| b | [UID2 client-side identity SDK](../sdks/client-side-identity-v1.md) | If a user hasn't opted out, the refresh token returns new identity tokens. | + +If you decide to integrate using options other than the SDK, we recommend refreshing identity tokens every 5 minutes. + +### 4. User Logout + +| Step | Endpoint/SDK | Instruction | +| --- | --- | --- | +| a | | The user logs out from a publisher asset. | +| b | [UID2 client-side identity SDK](../sdks/client-side-identity-v1.md) | Remove UID2 tokens from the user's local storage thwne they log out. Use the `disconnect` mechanism from the SDK to clear out UID2 tokens. | + +#### Client-Side SDK Disconnect Identity + +```html + +``` + +# Frequently Asked Questions +### How will I be notified of user opt-out? +The token refresh process handles user opt-outs. If a user opts out, using their refresh token automatically clears their session. [UID2 client-side SDK](../sdks/client-side-identity-v1.md). No manual action is required. + +### How can I test my integration? +There are two built-in tools you can use to test your integration. + +#### Test that PII sent and returned tokens match +You can use the [GET /token/validate](../endpoints/get-token-validate.md) endpoint to check whether the PII you are sending through [GET /token/generate](../endpoints/get-token-generate.md) is valid. + +1. Send a [GET /token/generate](../endpoints/get-token-generate.md) request using `validate@email.com` as `email`, or create a base64-encoded SHA256 hash of `validate@email.com` and send it through as an email hash. Store the `advertising_token` returned to use in step 2. +2. Send a [GET /token/validate](../endpoints/get-token-validate.md) request using the `email` or `email_hash` you sent in step 1 and the `token` as the `advertising_token` returned in step 1. If the response returns `true`, the `email` or `email_hash` you sent as a request in step 1 match the token you received in the response of step 1. If it returns `false`, there may be an issue with the way you are sending email addresses or email hashes. + +#### Test refresh token logout workflow + +You can use the email address `optout@email.com` to test your token refresh workflow. Using this email for the request always generates an identity response with a `refresh_token` that results in a logout response. + +1. Send a [GET /token/generate](../endpoints/get-token-generate.md) request using `optout@email.com` as `email`, or create a base64-encoded SHA256 hash of `optout@email.com` and send it through as an email hash. Store the `refresh_token` returned to use in step 2. +2. Send a [GET /token/validate](../endpoints/get-token-validate.md) request using the `email` or `email_hash` you sent in step 1 and the `refresh_token` as the `refresh_token` returned in step 1. The `body` response should be empty because the `optout@email.com` email always results in a logged out refresh token. diff --git a/api/v1/guides/publisher-flow-mermaid.md b/api/v1/guides/publisher-flow-mermaid.md new file mode 100644 index 000000000..e53dc0ef2 --- /dev/null +++ b/api/v1/guides/publisher-flow-mermaid.md @@ -0,0 +1,42 @@ + sequenceDiagram + participant U as User + participant P as Publisher + participant UID2 as UID2 Service + participant SSP + Note over U,SSP: 1. Establish Identity + U->>+P: 1-a. The user visits a publisher asset. + P->>-U: 1-b. The publisher explains the value exchange of the open internet and requests a login. + activate U + U->>P: 1-c. The user authenticates and authorizes the creation of a UID2. + deactivate U + activate P + P->>UID2: 1-d. The publisher sends the user's PII to the token generation service. + deactivate P + activate UID2 + UID2->>P: 1-e. The token generation service returns UID2 tokens. + deactivate UID2 + activate P + P->>U: 1-f. The publisher sets a UID2 for the user. + deactivate P + Note over U,SSP: 2. Bid Using UID2 Tokens + + P->>SSP: 2-a. The publisher calls the SSP for ads using the UID2 token. + activate SSP + SSP->>P: 2-b. The SSP returns ads to display. + deactivate SSP + activate P + P->>U: 2-c. The publisher displays the ads to the user. + deactivate P + + Note over U,SSP: 3. Refresh Tokens + U->>UID2: 3-a. The SDK sends a request to refresh the UID2 using the refresh token. + activate UID2 + UID2->>U: 3-b. If a user hasn't opted out, the refresh token service returns new identity tokens. + deactivate UID2 + Note over U,SSP: 4. User Logout + U->>P: 4-a. The user logs out from a publisher asset. + activate P + P->>U: 4-b. The user's identity clears. + deactivate P + + \ No newline at end of file diff --git a/v1/guides/publisher-flow-mermaid.png b/api/v1/guides/publisher-flow-mermaid.png similarity index 100% rename from v1/guides/publisher-flow-mermaid.png rename to api/v1/guides/publisher-flow-mermaid.png diff --git a/v1/sdks/.gitkeep b/api/v1/sdks/.gitkeep similarity index 100% rename from v1/sdks/.gitkeep rename to api/v1/sdks/.gitkeep diff --git a/v1/sdks/README.md b/api/v1/sdks/README.md similarity index 88% rename from v1/sdks/README.md rename to api/v1/sdks/README.md index 6163cd2e3..5f478837c 100644 --- a/v1/sdks/README.md +++ b/api/v1/sdks/README.md @@ -1,4 +1,4 @@ -[UID2 Documentation](../../README.md) > v1 > SDKs +[UID2 API Documentation](../../README.md) > v1 > SDKs # SDKs diff --git a/v1/sdks/client-side-identity-v1.md b/api/v1/sdks/client-side-identity-v1.md similarity index 93% rename from v1/sdks/client-side-identity-v1.md rename to api/v1/sdks/client-side-identity-v1.md index 6a1caf88f..c02eeea7f 100644 --- a/v1/sdks/client-side-identity-v1.md +++ b/api/v1/sdks/client-side-identity-v1.md @@ -1,4 +1,4 @@ -[UID2 Documentation](../../README.md) > v1 > [SDKs](./README.md) > Client-Side Identity +[UID2 API Documentation](../../README.md) > v1 > [SDKs](./README.md) > Client-Side Identity # Client-Side Identity SDK diff --git a/api/v1/sdks/dsp-client-v1-overview.md b/api/v1/sdks/dsp-client-v1-overview.md new file mode 100644 index 000000000..eed8ea30c --- /dev/null +++ b/api/v1/sdks/dsp-client-v1-overview.md @@ -0,0 +1,52 @@ +[UID2 API Documentation](../../README.md) > v1 > [SDKs](./README.md) > RTB Sdk + +# RTB SDK Client + +The UID2 RTB SDK facilitates decrypting UID2 tokens to access the raw UID2. + +The following describes the general contract for client SDKs. Naming conventions and other things will be language-specific (e.g. C# vs Go). + +Currently available libraries: ++ C# ++ C++ + +## Initialization + +| Parameter | Description | +| --- | --- | +| `endpoint` | Endpoint for UID2 service | +| `authKey` | Authentication token belonging to the client | +| `refreshIntervalMs` | Refresh cadence in milliseconds for fetching the decryption keys
Recommended value: 5 minutes (`300,000` milliseconds) | +| `retryIntervalMs` | Retry cadence in milliseconds to retry the request when encountering an error
Recommended value: 30 seconds (`30,000` milliseconds) | + + +## Interface + +Call the following method during RTB. + +```java +public Response Decrypt(String encryptedToken) +``` + +The response consists of the following properties: + +| Property | Description | +| --- | --- | +| `Status` | Status indicating the result of decryption. See ResponseStatus enum below | +| `Uid2` | UID2 identifying the user | +| `Established` | Timestamp at which the User established the UID2 on the Publisher | + + +Response Statuses + +| Value | Description | +| --- | --- | +| `Success` | UID2 token was successfully decrypted | +| `NotAuthorizedForKey` | The client does not have the right to decrypt this identity| +| `NotInitialized` | The client library is waiting to be initialized | +| `InvalidPayload` | The incoming encrypted token is not a valid payload | +| `ExpiredToken` | The incoming token is expired | +| `KeysNotSynced` | The client has failed to synchronize keys from UID2 service | +| `VersionNotSupported` | The client library does not support the encrypted token's version | + + diff --git a/v1/endpoints/get-identity-buckets.md b/v1/endpoints/get-identity-buckets.md deleted file mode 100644 index 25413c81a..000000000 --- a/v1/endpoints/get-identity-buckets.md +++ /dev/null @@ -1,25 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /identity/buckets - -# GET /identity/buckets - -Monitor for rotated salt buckets. - -## Request - -### Query Parameters - -| Query Parameter | Data Type | Attributes | Description | -| --- | --- | --- | --- | -| `since_timestamp` | `date-time` | | Return buckets with last updated UTC timestamps after the specified date and time. | - -## Response - -```json -[ - { - "bucket_id" : "last_update_timestamp" - } -] -``` - -## Body Response Properties \ No newline at end of file diff --git a/v1/endpoints/get-identity-map.md b/v1/endpoints/get-identity-map.md deleted file mode 100644 index 9bf873e79..000000000 --- a/v1/endpoints/get-identity-map.md +++ /dev/null @@ -1,52 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > [Endpoints](./README.md) > GET /identity/map - -# GET /identity/map - -Retrieve advertising and bucket IDs for one `email` or `email_hash`. - -## Request - -```GET '{environment}/{version}/identity/map?{queryParameter}={queryParameterValue}'``` - -### Query Parameters - -| Query Parameter | Data Type | Attributes | Description | -| --- | --- | --- | --- | -| `email` | `string` | Conditionally Required | The normalized email address of a user. Required when `email_hash` is not included in the request. | -| `email_hash` | `string` | Conditionally Required | The SHA256 hash of the normalized email address of a user. Required when `email` is not included in the request. | - -#### Example Request Using an Email Address - -```sh -curl -L -X GET 'https://integ.uidapi.com/v1/identity/map?email=username@example.com' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' -``` - -#### Example Request Using an Email Hash - -```sh -curl -L -X GET 'https://integ.uidapi.com/v1/identity/map?email_hash=795BCB4BF560F9867AFB3DE2D0D3A94976324007C45EA099EC14E90231540547' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' -``` - -## Response - -The response is a JSON object containing the user's UID2 identifier and bucket identifier. - -```json -{ - "mapped": [ - { - "identifier": "user@example.com", - "advertising_id": "AdvtiSuYWAZSYe8t4n6sQx0gshoHYZdOzg9qUn/eKgE=", - "bucket_id": "bucketId" - } - ] -} -``` - -## Body Response Properties - -| Property | Data Type | Description | -| --- | --- | --- | -| `mapped.identifier` | `string` | The `email` or `email_hash` provided in the request. | -| `mapped.advertising_id` | `string` | The identity's advertising ID. | -| `mapped.bucket_id` | `string` | Bucket Id corresponding to that User identifier. | \ No newline at end of file diff --git a/v1/endpoints/post-identity-map.md b/v1/endpoints/post-identity-map.md deleted file mode 100644 index ddaa41278..000000000 --- a/v1/endpoints/post-identity-map.md +++ /dev/null @@ -1,58 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > [Endpoints](./README.md) > POST /identity/map - -# POST /identity/map - -Retrieve advertising and bucket IDs for multiple email addresses or email hashes. Send a maximum of 10,000 combined `email` or `email_hash` per request. - -## Request - -```POST '{environment}/{version}/identity/map'``` - -### Request Properties - -| Property | Data Type | Attributes | Description | -| --- | --- | --- | --- | -| `email` | List of `string` | Conditionally Required | A list of normalized email addresses for multiple users. Required when `email_hash` is not included in the request. | -| `email_hash` | List of `string` | Conditionally Required | A list of SHA256 hashes of normalized email addresses for multiple users. Required when `email` is not included in the request. | - -#### Example Request Using an Email Address and an Email Hash - -```sh -curl -L -X POST 'https://integ.uidapi.com/identity/map' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' -H 'Content-Type: application/json' --data-raw '{ - "email":[ - "user@example.com" - ], - "email_hash":[ - "795BCB4BF560F9867AFB3DE2D0D3A94976324007C45EA099EC14E90231540547" - ] -}' -``` - -## Response - -The response is a JSON object containing the user's UID2 identifier and bucket identifier. - -```json -{ - "mapped": [ - { - "identifier": "user@example.com", - "advertising_id": "AdvtiSuYWAZSYe8t4n6sQx0gshoHYZdOzg9qUn/eKgE=", - "bucket_id": "bucketId" - }, - { - "identifier": "795BCB4BF560F9867AFB3DE2D0D3A94976324007C45EA099EC14E90231540547", - "advertising_id": "AdvIvSiaum0P5s3X/7X8h8sz+OhF2IG8DNbEnkWSbYM=", - "bucket_id": "bucketId" - } - ] -} -``` - -## Body Response Properties - -| Property | Data Type | Description | -| --- | --- | --- | -| `mapped.identifier` | `string` | The `email` or `email_hash` provided in the request. | -| `mapped.advertising_id` | `string` | The identity's advertising ID. | -| `mapped.bucket_id` | `string` | Bucket Id corresponding to that User identifier. | \ No newline at end of file diff --git a/v1/endpoints/post-token-logout.md b/v1/endpoints/post-token-logout.md deleted file mode 100644 index 96db8e62f..000000000 --- a/v1/endpoints/post-token-logout.md +++ /dev/null @@ -1,29 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > [Endpoints](./README.md) > POST /token/logout - -# POST /token/logout -Logout from a UID2 identity session. - -## Request - -```POST '{environment}/{version}/token/logout?{queryParameter}={queryParameterValue}'``` - -### Query Parameters - -| Query Parameter | Data Type | Attributes | Description | -| --- | --- | --- | --- | -| `email` | `string` | Required | The normalized email address of a user. | - -#### Example Request Using an Email Address - -```sh -curl -L -X POST 'https://integ.uidapi.com/v1/token/logout?email=username@example.com' -H 'Authorization: Bearer YourTokenBV3tua4BXNw+HVUFpxLlGy8nWN6mtgMlIk=' -``` - -## Response - -The response is a standard HTTP response code. - - -``` -OK -``` diff --git a/v1/guides/README.md b/v1/guides/README.md deleted file mode 100644 index 091e16650..000000000 --- a/v1/guides/README.md +++ /dev/null @@ -1,13 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > Integration Guides - -# Integration Guides - -The following Guides cover different integration scenarios - -| Target Use Case | Description | -| --- | --- | -| [Publisher](./publisher-client-side.md) | Standard Integration Guide for Publisher on Web | -| [Custom Integration](./custom-publisher-integration.md) | Custom Integration Guide for Publisher for non-Web | -| [DSP](./dsp-guide.md) | Integration Guide for DSP wanting to use UID2 in Bidding | -| [Advertiser/Data Provider](./advertiser-dataprovider-guide.md) | Integration for Advertiser/Data Provider to target UID2 Audience | - diff --git a/v1/guides/advertiser-dataprovider-guide.md b/v1/guides/advertiser-dataprovider-guide.md deleted file mode 100644 index 195a05301..000000000 --- a/v1/guides/advertiser-dataprovider-guide.md +++ /dev/null @@ -1,49 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > Integration Guides > Advertiser/Data Provider Integration Guide - -# Overview - -Following are the steps that Data Providers/Advertisers can take to map PII to UID2 for targeting and audience building purposes. - -Note: PII refers to email address or SHA256 of normaled email address. - -![Advertiser Flow](advertiser-flow-mermaid.png) - - -# Steps - -## 1 Map PII to UID2 - -Use the [/identity/map](../endpoints/post-identity-map.md) endpoint to map PII to UID2. The UID2 thus returned can be used to target audiences on relavant DSPs and for other use cases. - -## 2 Send UID2 based Audience -This will be a DSP specific endpoint/mechanism and is out of scope for this document. Follow DSP specific Integration for sending UID2 based audience. - -## 3 Check for Bucket Updates - -By it's very design, the UID2 is an id for a user at a particular moment in time. A user's UID2 can and will rotate once a year. One can choose to either blanketly update their segments on daily basis or can implement incremental updates by querying bucket rotation status. - -Bucket status endpoint [/identity/buckets](../endpoints/get-identity-buckets.md) can return the buckets that have their associated UID2s rotated since a given timestamp. - -## 4 Incremental Update UID2 - -Leveraging Steps 1 and 3, a system can continously update its UID2 based audiences to the DSP. The response from Step 1 contains mapped UID2 and corresponding "bucket_id" associated with it. While UID2 can rotate, the bucket_id will stay constant for the given user. - -From Step 1. the system can store the Mapping between PII and Bucket ID along with last updated timestamp. e.g. - -``` -PIIIdentifier, BucketId, Updated Timestamp -``` - -By querying the Bucket info described in Step 3, the system can repeat step 1 and 2 for the UIDs associated with the updated buckets. - -# Frequently Asked Questions -### Q: How does a holder of UID2 know when to refresh the UID2 due to salt rotation? -Metadata supplied with the UID2 generation request indicates the salt bucket used for generating the UID2. Salt buckets are persistent and correspond to the underlying PII. Use the API provided to return which salt buckets rotated since a given timestamp. The returned rotated salt buckets inform the UID2 holder which UID2s to refresh. This workflow typically applies to data providers. - -### Q: How often should IDs be refreshed for incremental updates? -The recommended cadence for updating audiences is daily. - -### Q: How should i generate the SHA256 of PII for mapping? -The system should follow the email normalization rules (described in the [Overview document](../../README.md)) and hash without salting. The value needs to be base64 encoded before it can be sent. - - diff --git a/v1/guides/advertiser-flow-mermaid.md b/v1/guides/advertiser-flow-mermaid.md deleted file mode 100644 index 4638e422a..000000000 --- a/v1/guides/advertiser-flow-mermaid.md +++ /dev/null @@ -1,11 +0,0 @@ - sequenceDiagram - participant Data Provider - participant UID Service - participant DSP - Data Provider->>UID Service: 1. Map PII to UID2 - UID Service->>Data Provider: Mapped UID2s along with Bucket Info - Data Provider-->>DSP: 2. Send UID2 based Audience - loop Refresh - Data Provider->>UID Service: 3. Check for Bucket Updates - end - Data Provider->>UID Service: 4. Incremental Update UID2. diff --git a/v1/guides/custom-publisher-flow-mermaid.md b/v1/guides/custom-publisher-flow-mermaid.md deleted file mode 100644 index 5e8d7db8c..000000000 --- a/v1/guides/custom-publisher-flow-mermaid.md +++ /dev/null @@ -1,16 +0,0 @@ - sequenceDiagram - participant User - participant Publisher - participant UID Service - participant SSP - - User->>Publisher: 1 Visits - User->>Publisher: 2 Authenticates - Publisher->>UID Service: 3-1 Generate UID2 - UID Service->>Publisher: 3-2 UID2 Tokens Returned - Publisher-->>SSP: 4-1 Calling SSP for Ads - Publisher-->>User: 4-2 Ads Displayed to User - User->>Publisher: 5-1 Revisits Publisher - Publisher-->>UID Service: 5-2 Refresh UID2 Tokens - UID Service-->>Publisher: Refreshed UID2 Tokens - User->>Publisher: 6 User Logout diff --git a/v1/guides/custom-publisher-integration.md b/v1/guides/custom-publisher-integration.md deleted file mode 100644 index 84a24264c..000000000 --- a/v1/guides/custom-publisher-integration.md +++ /dev/null @@ -1,50 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > Integration Guides > Custom Publisher Integration Guide - -# Overview - -Following is the Lifecycle for User establishing UID2 on publisher and how it integrates with RTB. - -![Custom Publisher Flow](custom-publisher-flow-mermaid.png) - - -### Steps - -Steps 3-1, 4-1, 5-2, 6 are integration points for Publisher - -## 3-1 Generate UID2 - -The publisher calls the token generation endpoint [/token/generate](../endpoints/get-token-generate.md) endpoint for the user by providing either their email address or SHA256 hash of normalized email address (See Normalization rules [here](../../README.md). The returned tokens should be placed in a store tied to the User (e.g. first-party cookie, or server-side storage) as publisher sees fit. - -## 4-1 Calling SSP for Ads -The Publisher needs to pass the "advertising_token" part of the UID2 Tokens payload (from step 3-1) to the SSP for RTB purposes. The value needs to be passed as is. - -## 5-2 Refresh UID2 -Publisher must keep the UID2 Tokens fresh by leveraging the refresh API. Following two user lifecycle events should be used: -1 User returning to the site. -2 An interval has passed (recommedation of 5 minutes) since the last refresh. - -No refresh needs to be done for inactive user. - -The UID2 Tokens can be refreshed by passing the "refresh_token" part of the UID2 Tokens (from step 3-1) to the [/token/refresh](../endpoints/get-token-refresh.md) endpoint. - -Refreshing the tokens is necessary to sync user's opt-out and UID2 rotation in the background. After refresh, the Publisher should update the set of tokens as done in step 3-1. - -## 6 User Logout -Publisher should remove the UID2 Tokens stored for that user. No interaction with UID Service is required. - -# Frequently Asked Questions - -### Q: Do I need to decrypt any of the Tokens? -No, Publisher does not need to decrypt any tokens. - -### Q: How will I be notified of user opt-out? -User opt-outs are handled as part of token refresh. No more Publisher action is necessary. - -### Q: What is the uniqueness and rotation policy for UID2 Token? -The tokens are encrypted using random initialization vectors, so the encrypted payload will look different for a given user as they browse through the Internet. The token also gets re-encrypted on every refresh. The intent of the mechanism is to ensure that a User's identity is un-trackable by non-trusted parties. - - - - - - diff --git a/v1/guides/dsp-guide.md b/v1/guides/dsp-guide.md deleted file mode 100644 index 80b547493..000000000 --- a/v1/guides/dsp-guide.md +++ /dev/null @@ -1,49 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > Integration Guides > DSP Integration Guide - -# Overview - -The following describes the integration workflow for DSP to support UID2 as part of RTB. - -The DSP has to integrate two use cases: -1. Decrypting UID2 on RTB Requests. -2. Honoring opt-out for the User. -![DSP Guide Flow](dsp-guide-flow-mermaid.png) -Note: T&C Portal refers to Transperancy and Control Portal - -### Steps - -Step 1-4 and Step 2-2 are integration points for DSP to implement. - -## 1-4 Decrypting UID2 Token - -The DSP should leverage the provided [SDK](../sdks/dsp-client-v1-overview.md) to decrypt the incoming UID2 Token. Library response will contain the UID2 and the timestamp that identity was established (established_timestamp). The DSP is required to check against the most recent opt-out timestamp (optout_timestamp) for that UID2 (if it exists) to honor opt out. Following describes the logic. - -![DSP Opt Out Check](dsp-guide-optout-check-mermaid.png) - -The logic for Check Opt-out step is: -```java -if (established_timestamp < optout_timestamp) { - // Opted out -} -``` - -## 2-2 Handle Opt-out - -The DSP will get a call-back on a pre-configured URL when a User opts out from the T&C Portal. The DSP should record the opt out timestamp for the corresponding UID2, to be later used for bidding (see above). - -The callback will contain the following two pieces of information - -| Parameter | Description | -| --- | --- | -| identity | UID2 for the user opting out | -| timestamp | Time at which the user opted out | - - -# Frequently Asked Questions -### Q: How do companies interfacing with UID2 tokens know which decryption key to apply? -Updating decryption keys is handled automatically by the provided SDK. Metadata supplied with the UID2 token discloses the timestamp of encryption, which informs which decryption key applies. - -### Q: Where do I get the decrypting keys? -The library will talk to the UID Service in the background and periodically fetch the up-to-date keys. - - diff --git a/v1/guides/publisher-client-side.md b/v1/guides/publisher-client-side.md deleted file mode 100644 index 3ab919657..000000000 --- a/v1/guides/publisher-client-side.md +++ /dev/null @@ -1,55 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > Integration Guides > Publisher Integration Guide - -# Overview - -Following is the Lifecycle for User establishing UID2 on publisher and how it integrates with RTB. - -![Publisher Flow](publisher-flow-mermaid.png) - -### Steps - -Steps 3, 4, 5-1, 6, 7-2 are integration points for Publisher. - -## 3 Generate UID2 - -Identity tokens can be established either by using a UID2 Enabled SSO or for Publisher to generate Identity themselves via [/token/generate](../endpoints/get-token-generate.md) endpoint as part of user authentication. - -## 4 UID Set for User - -Once UID2 tokens are returned from the step above, they should be passed on to the [UID2 Client Library](../sdks/client-side-identity-v1.md) using the mechanism below. This ensures that UID2 tokens are available for the user until they logout. - -```html - -``` - -## 5-1 Calling SSP for Ads - -Once established, the identity is available for client to use for RTB purposes. The following snippet gives access to the identity that can be passed to SSPs. - -```html - -``` - -## 6 Refresh UID2 -UID2 Tokens are refreshed automatically by the [UID2 Client Library](../sdks/client-side-identity-v1.md) and no action needs to be taken. This is mentioned for informational purpose only. - -## 7-2 User Identity Cleared - -It is impotant to remove UID2 tokens from the user's storage when they logout. Use the following snippet to cleare out UID2 tokens. - -```html - -``` - -# Frequently Asked Questions -### Q: How will I be notified of user optout? -User opt-outs are handled as part of token refresh process, which is automatically handled by the [UID2 Client Library](../sdks/client-side-identity-v1.md). No integration action is neeeded. - diff --git a/v1/guides/publisher-flow-mermaid.md b/v1/guides/publisher-flow-mermaid.md deleted file mode 100644 index e48cb4ce3..000000000 --- a/v1/guides/publisher-flow-mermaid.md +++ /dev/null @@ -1,16 +0,0 @@ - sequenceDiagram - participant User - participant Publisher - participant UID Service - participant SSP - - User->>Publisher: 1 Visits - User->>Publisher: 2 Authenticates - Publisher->>UID Service: 3 Generate UID2 - Publisher->>User: 4 UID2 Set for User - Publisher-->>SSP: 5-1 Calling SSP for Ads - Publisher-->>User: 5-2 Ads Displayed to User - User-->>UID Service: 6 Refresh UID2 - UID Service-->User: UID Tokens Refreshed - User->>Publisher: 7-1 Logout - Publisher->>User: 7-2 User Identity Cleared \ No newline at end of file diff --git a/v1/sdks/dsp-client-v1-overview.md b/v1/sdks/dsp-client-v1-overview.md deleted file mode 100644 index 2c4cb8ccc..000000000 --- a/v1/sdks/dsp-client-v1-overview.md +++ /dev/null @@ -1,48 +0,0 @@ -[UID2 Documentation](../../README.md) > v1 > [SDKs](./README.md) > RTB Sdk - -# RTB Bidding SDK Client - -The UID2 Client facilitates decrypting the UID Tokens and accessing UID. - -The following describes general contract for client SDKs. Naming conventions and other things will be langauge specific (e.g. C# vs Go). - -## Initialization - -| Parameter | Description | -| --- | --- | -| endpoint | Endpoint for UID2 Service | -| authKey | Authentication Token belonging to the client | -| refreshIntervalMs | Refresh cadence for fetching the keys the Decrypting keys (in milliseconds). Recommended Value: 5 minutes | -| retryIntervalMs | Retry cadence in case of error (in milliseconds). Recommended Value: 30 seconds | - - -## Interface - -The following method is called on the client SDK at real time bidding. - - -```java -public Response Decrypt(String encryptedToken) -``` - -Response consists of following properties -| Property | Description | -| --- | --- | -| Status | Status indicating the result of decryption. See ResponseStatus enum below | -| Uid2 | UID2 identifying the user | -| Established | Timestamp at which the User established the UID2 on the Publisher | - - -ResponseStatus: - -| Value | Description | -| --- | --- | -| Success | UIDToken was successfully decrypted | -| NotAuthorizedForKey | The client does not have the right to decrypt this Identity| -| NotInitialized | The client library is still waiting to be initialized | -| InvalidPayload | The incoming encryptedToken is not a valid payload | -| ExpiredToken | The incoming token is Expired | -| KeysNotSynced | The client has failed to synchronize keys from UID2 Service | -| VersionNotSupported | The Client library does not suppert that version of the encrypted token | - -