Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 6 additions & 14 deletions docs/endpoints/post-token-generate.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,6 @@ Requests a UID2 token generated from a user's <Link href="../ref-info/glossary-u

Used by: This endpoint is used mainly by publishers.

:::important
The `optout_check` parameter, required with a value of `1`, checks whether the user has opted out.
:::

<!-- uid2_euid_diff re legal basis for admonition above -->

Expand Down Expand Up @@ -46,7 +43,7 @@ Here's what you need to know about sending requests to this endpoint:
### Unencrypted JSON Body Parameters

:::important
You must include only **one** of the following four conditional parameters, plus the required `optout_check` parameter with a value of `1`, as key-value pairs in the JSON body of the request when encrypting it.
You must include only **one** of the following four conditional parameters as key-value pairs in the JSON body of the request when encrypting it.
:::

| Body Parameter | Data Type | Attribute | Description |
Expand All @@ -55,7 +52,6 @@ You must include only **one** of the following four conditional parameters, plus
| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of a [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address. |
| `phone` | string | Conditionally Required | The [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number for which to generate tokens. |
| `phone_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#phone-number-hash-encoding) hash of a [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number. |
| `optout_check` | number | Required | Checks whether the user has opted out. Include this parameter with a value of `1`.|

### Request Examples

Expand All @@ -67,33 +63,29 @@ The following are unencrypted JSON request body examples for each parameter, one

```json
{
"email": "username@example.com",
"optout_check": 1
"email": "username@example.com"
}
```
```json
{
"email_hash": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=",
"optout_check": 1
"email_hash": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="
}
```
```json
{
"phone": "+12345678901",
"optout_check": 1
"phone": "+12345678901"
}
```
```json
{
"phone_hash": "wdN1alhrbw1Bmz49GzKGdPvGxLhCNn7n3teAOQ/FSK4=",
"optout_check": 1
"phone_hash": "wdN1alhrbw1Bmz49GzKGdPvGxLhCNn7n3teAOQ/FSK4="
}
```

Here's an encrypted token generation request example for an email hash:

```sh
echo '{"email_hash": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=","optout_check":1}' | python3 uid2_request.py https://prod.uidapi.com/v2/token/generate [Your-Client-API-Key] [Your-Client-Secret]
echo '{"email_hash": "tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ="}' | python3 uid2_request.py https://prod.uidapi.com/v2/token/generate [Your-Client-API-Key] [Your-Client-Secret]
```
For details, and code examples in different programming languages, see [Encrypting Requests and Decrypting Responses](../getting-started/gs-encryption-decryption.md).

Expand Down
16 changes: 8 additions & 8 deletions docs/getting-started/gs-encryption-decryption.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ This section includes encryption and decryption code examples in different progr
For the [POST&nbsp;/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&nbsp;/token/generate](../endpoints/post-token-generate.md) or [POST&nbsp;/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", "optout_check": 1}`.
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"}`.
:::

### Prerequisites and Notes
Expand Down Expand Up @@ -228,8 +228,8 @@ Usage:
echo '<json>' | python3 uid2_request.py <url> <api_key> <client_secret>

Example:
echo '{"email": "test@example.com", "optout_check": 1}' | python3 uid2_request.py https://prod.uidapi.com/v2/token/generate PRODGwJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=
echo '{"email": "test@example.com"}' | python3 uid2_request.py https://prod.uidapi.com/v2/token/generate PRODGwJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=


Refresh Token Usage:
python3 uid2_request.py <url> --refresh-token <refresh_token> <refresh_response_key>
Expand Down Expand Up @@ -356,7 +356,7 @@ public class Uid2Request {
+ "java -jar Uid2Request-jar-with-dependencies.jar <url> <api_key> <client_secret>" + "\n\n"

+ "Example:" + "\n "
+ "echo '{\"email\": \"test@example.com\", \"optout_check\": 1}' | java -jar Uid2Request-jar-with-dependencies.jar https://prod.uidapi.com/v2/token/generate PRODGwJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=" + "\n\n\n"
+ "echo '{\"email\": \"test@example.com\"}' | java -jar Uid2Request-jar-with-dependencies.jar https://prod.uidapi.com/v2/token/generate PRODGwJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=" + "\n\n\n"

+ "Refresh Token Usage:" + "\n "
+ "java -jar Uid2Request-jar-with-dependencies.jar <url> --refresh-token <refresh_token> <refresh_response_key>" + "\n\n"
Expand Down Expand Up @@ -466,8 +466,8 @@ Usage:
echo '<json>' | .\uid2_request <url> <api_key> <client_secret>

Example:
echo '{"email": "test@example.com", "optout_check": 1}' | .\uid2_request https://prod.uidapi.com/v2/token/generate UID2-C-L-999-fCXrMM.fsR3mDqAXELtWWMS+xG1s7RdgRTMqdOH2qaAo= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=
echo '{"email": "test@example.com"}' | .\uid2_request https://prod.uidapi.com/v2/token/generate UID2-C-L-999-fCXrMM.fsR3mDqAXELtWWMS+xG1s7RdgRTMqdOH2qaAo= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=


Refresh Token Usage:
.\uid2_request <url> --refresh-token <refresh_token> <refresh_response_key>
Expand Down Expand Up @@ -810,8 +810,8 @@ func printUsage() {
echo '<json>' | go run uid2_request.go <url> <api_key> <client_secret>

Example:
echo '{"email": "test@example.com", "optout_check": 1}' | go run uid2_request.go https://prod.uidapi.com/v2/token/generate UID2-C-L-999-fCXrMM.fsR3mDqAXELtWWMS+xG1s7RdgRTMqdOH2qaAo= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=
echo '{"email": "test@example.com"}' | go run uid2_request.go https://prod.uidapi.com/v2/token/generate UID2-C-L-999-fCXrMM.fsR3mDqAXELtWWMS+xG1s7RdgRTMqdOH2qaAo= wJ0hP19QU4hmpB64Y3fV2dAed8t/mupw3sjN5jNRFzg=


Refresh Token Usage:
go run uid2_request.go <url> --refresh-token <refresh_token> <refresh_response_key>
Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/gs-faqs.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ No, publishers do not need to decrypt <Link href="../ref-info/glossary-uid#gl-ui
#### 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&nbsp;/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 generate the UID2 token by a call to the [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) endpoint, either directly or via one of the UID2 SDKs.
- When you refresh the UID2 token by a call to the [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md) endpoint, either directly or via one of the UID2 SDKs.

#### Where should I make token generation calls&#8212;from the server side or the client side?
Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/gs-opt-out.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ The following steps provide a high-level outline of the opt-out workflow intende

| Participant | Distribution Method |
| :--- | :--- |
| Publishers | A publisher calling [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) with the required `optout_check` parameter set to `1`, or [POST&nbsp;/token/refresh](../endpoints/post-token-refresh.md), receives the opt-out response instead of the UID2 token. |
| Publishers | A publisher calling [POST&nbsp;/token/generate](../endpoints/post-token-generate.md), or [POST&nbsp;/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).<br/>DSPs can also check the opt-out status of raw UID2s using the [POST&nbsp;/optout/status](../endpoints/post-optout-status.md) endpoint. |
| Advertisers and data providers | The UID2 Operator Service distributes opt-out information to advertisers and data providers via the [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) endpoint. Another option is to check the opt-out status of raw UID2s using the [POST&nbsp;/optout/status](../endpoints/post-optout-status.md) endpoint. |
| Sharers | UID2 sharers can check the opt-out status of raw UID2s using the [POST&nbsp;/optout/status](../endpoints/post-optout-status.md) endpoint. |
Expand Down
19 changes: 8 additions & 11 deletions docs/sdks/sdk-ref-java.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,14 +147,12 @@ If you're using the SDK's HTTP implementation, follow these steps.

2. Call a function that takes the user's email address or phone number as input and generates a `TokenGenerateResponse` object. The following example uses an email address:
```java
TokenGenerateResponse tokenGenerateResponse = publisherUid2Client.generateTokenResponse(TokenGenerateInput.fromEmail("user@example.com").doNotGenerateTokensForOptedOut());
TokenGenerateResponse tokenGenerateResponse = publisherUid2Client.generateTokenResponse(TokenGenerateInput.fromEmail("user@example.com"));
```

:::important
<!-- - Be sure to call the POST&nbsp;/token/generate endpoint only when you have a legal basis to convert the user’s <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> to UID2 tokens for targeted advertising.

- --> Always apply `doNotGenerateTokensForOptedOut()`. This applies a parameter similar to setting `optout_check=1` in the call to the POST&nbsp;/token/generate endpoint (see [Unencrypted JSON Body Parameters](../endpoints/post-token-generate.md#unencrypted-json-body-parameters)).
:::
<!-- :::important
- Be sure to call the POST&nbsp;/token/generate endpoint only when you have a legal basis to convert the user’s <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> to UID2 tokens for targeted advertising.
::: -->

<!-- uid2_euid_diff re legal basis for admonition above (first bullet not in UID2) -->

Expand Down Expand Up @@ -224,19 +222,18 @@ If you're using server-side integration (see [Publisher Integration Guide, Serve
2. Call a function that takes the user's email address or phone number as input and creates a secure request data envelope. See [Encrypting requests](../getting-started/gs-encryption-decryption.md#encrypting-requests). The following example uses an email address:

```java
EnvelopeV2 envelope = publisherUid2Helper.createEnvelopeForTokenGenerateRequest(TokenGenerateInput.fromEmail("user@example.com").doNotGenerateTokensForOptedOut());
EnvelopeV2 envelope = publisherUid2Helper.createEnvelopeForTokenGenerateRequest(TokenGenerateInput.fromEmail("user@example.com"));
```
3. Using an HTTP client library of your choice, post this envelope to the [POST&nbsp;token/generate](../endpoints/post-token-generate.md) endpoint, including headers and body:
1. Headers: Depending on your HTTP library, this might look something like the following:

`.putHeader("Authorization", "Bearer " + UID2_API_KEY)`
`.putHeader("X-UID2-Client-Version", PublisherUid2Helper.getVersionHttpHeader())`
2. Body: `envelope.getEnvelope()`
:::important
<!-- - Be sure to call the POST&nbsp;/token/generate endpoint only when you have a legal basis to convert the user’s <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> to UID2 tokens for targeted advertising.

- --> Always apply `doNotGenerateTokensForOptedOut()`. This applies a parameter similar to setting `optout_check=1` in the call to the POST&nbsp;/token/generate endpoint (see [Unencrypted JSON Body Parameters](../endpoints/post-token-generate.md#unencrypted-json-body-parameters)).
:::
<!-- :::important
- Be sure to call the POST&nbsp;/token/generate endpoint only when you have a legal basis to convert the user’s <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> to UID2 tokens for targeted advertising.
::: -->

<!-- uid2_euid_diff re legal basis for admonition above (first bullet not in UID2) -->

Expand Down
6 changes: 2 additions & 4 deletions docs/sdks/sdk-ref-python.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,17 +158,15 @@ Decryption response codes, and their meanings, are shown in the following table.
2. Call a function that takes the user's email address or phone number as input and generates a `TokenGenerateResponse` object. The following example uses an email address:

```py
token_generate_response = client.generate_token(TokenGenerateInput.from_email("user@example.com").do_not_generate_tokens_for_opted_out())
token_generate_response = client.generate_token(TokenGenerateInput.from_email("user@example.com"))
```

<!-- :::important
Be sure to call this function only when you have a legal basis to convert the user’s <Link href="../ref-info/glossary-uid#gl-dii">directly identifying information (DII)</Link> to UID2 tokens for targeted advertising.
:::
::: -->

<!-- uid2_euid_diff re legal basis for admonition above (not in UID2) -->

`do_not_generate_tokens_for_opted_out()` applies `optout_check=1` in the [POST&nbsp;/token/generate](../endpoints/post-token-generate.md) call. Without this, `optout_check` is omitted to maintain backwards compatibility.

### Client-Server Integration

If you're using client-server integration (see [Client-Server Integration Guide for JavaScript](../guides/integration-javascript-client-server.md)), follow this step:
Expand Down
Loading