Skip to content

Commit

Permalink
update the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ian-Nara
Ian-Nara committed Oct 27, 2023
1 parent c799731 commit 9ed632f
Show file tree
Hide file tree
Showing 5 changed files with 32 additions and 30 deletions.
14 changes: 8 additions & 6 deletions docs/endpoints/post-token-generate.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -141,9 +141,11 @@ If the `status` value is anything other than `success`, the `message` field prov

## Test Identities

| Type | Identity | Purpose | Next Endpoint |
| :--- | :--- | :--- | :--- |
| Email | `[email protected]` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified email address. | [POST /token/validate](post-token-validate.md) |
| Email | `[email protected]` | Using this email for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) |
| Phone | `+12345678901` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified phone number. | [POST /token/validate](post-token-validate.md) |
| Phone | `+00000000000` | Using this phone number for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) |
| Type | Identity | Purpose | Next Endpoint |
|:------|:-----------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------|
| Email | `[email protected]` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified email address. | [POST /token/validate](post-token-validate.md) |
| Email | `[email protected]` | Using this email for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) |
| Email | `[email protected]` | Using this email for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) |
| Phone | `+12345678901` | Test that the `advertising_token` you've cached matches the `advertising_token` for the specified phone number. | [POST /token/validate](post-token-validate.md) |
| Phone | `+00000000002` | Using this phone number for the request always generates an `optout` response. | [POST /token/generate](post-token-generate.md) |
| Phone | `+00000000000` | Using this phone number for the request always generates an identity response with a `refresh_token` that results in an `optout` response. | [POST /token/refresh](post-token-refresh.md) |
4 changes: 2 additions & 2 deletions docs/endpoints/post-token-refresh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ Here's what you need to know about this endpoint:

Using either of the following parameters in a [POST /token/generate](post-token-generate.md) request always generates an identity response with a `refresh_token` that results in a logout response when used with the `POST /token/refresh` endpoint:

- The `optout@email.com` email address
- The `+00000000000` phone number
- The `refresh-optout@example.com` email address
- The `+00000000002` phone number

### Request Example

Expand Down
8 changes: 4 additions & 4 deletions docs/endpoints/post-token-validate.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ Used by: This endpoint is used mainly by publishers.
| Body Parameter | Data Type | Attribute | Description |
| :--- | :--- | :--- | :--- |
| `token` | string | Required | The advertising token returned by the [POST /token/generate](post-token-generate.md) response. |
| `email` | string | Conditionally Required | The email address for token validation.<br/>The only valid value is: `validate@email.com`. |
| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of the [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address for token validation (`validate@email.com`).<br/>The only valid value is: `LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI=`. |
| `email` | string | Conditionally Required | The email address for token validation.<br/>The only valid value is: `validate@example.com`. |
| `email_hash` | string | Conditionally Required | The [Base64-encoded SHA-256](../getting-started/gs-normalization-encoding.md#email-address-hash-encoding) hash of the [normalized](../getting-started/gs-normalization-encoding.md#email-address-normalization) email address for token validation (`validate@example.com`).<br/>The only valid value is: `LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI=`. |
| `phone` | string | Conditionally Required | The [normalized](../getting-started/gs-normalization-encoding.md#phone-number-normalization) phone number for which to generate tokens.<br/>The only valid value is: `+12345678901`. |
| `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.<br/>The only valid value is: `EObwtHBUqDNZR33LNSMdtt5cafsYFuGmuY4ZLenlue4=`. |

Expand All @@ -47,13 +47,13 @@ The following are unencrypted JSON request body examples for each parameter, whi
```json
{
"token": "AdvertisingTokenmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b%2FbesPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM%2BewMzXXM8G9j8Q%3D",
"email": "validate@email.com"
"email": "validate@example.com"
}
```
```json
{
"token": "AdvertisingTokenmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b%2FbesPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM%2BewMzXXM8G9j8Q%3D",
"email_hash": "LdhtUlMQ58ZZy5YUqGPRQw5xUMS5dXG5ocJHYJHbAKI="
"email_hash": "ntI244ZRTXwAwpki6/M5cyBYW7h/Wq576lnN3l9+W/c="
}
```
```json
Expand Down
20 changes: 10 additions & 10 deletions docs/getting-started/gs-faqs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,28 +75,28 @@ Yes. The [POST /token/refresh](../endpoints/post-token-refresh.md) can be called

#### How can I test the refresh token workflow?

You can use the `optout@email.com` email address or the `+00000000000` phone number to test your token refresh workflow. Using either parameter value in a request always generates an identity response with a `refresh_token` that results in a logout response.
You can use the `refresh-optout@example.com` email address or the `+00000000002` phone number to test your token refresh workflow. Using either parameter value in a request always generates an identity response with a `refresh_token` that results in a logout response.

The procedure is a little different depending on whether or not you are using an SDK.

##### With SDK:

1. Depending on whether the DII is an email address or a phone number, send a [POST /token/generate](../endpoints/post-token-generate.md) request using one of the following values:
- The `optout@email.com` as the `email` value.
- The hash of `optout@email.com` as the `email_hash` value.
- The `+00000000000` as the `phone` value.
- The hash of `+00000000000` as the `phone_hash` value.
- The `refresh-optout@example.com` as the `email` value.
- The hash of `refresh-optout@example.com` as the `email_hash` value.
- The `+00000000002` as the `phone` value.
- The hash of `+00000000002` as the `phone_hash` value.
2. Wait until the SDK's [background auto-refresh](../sdks/client-side-identity.md#background-token-auto-refresh) attempts to refresh the advertising token (this can take several hours) and observe the refresh attempt fail with the `OPTOUT` status. At this point the SDK also clears the first-party cookie.

##### Without SDK:

1. Depending on whether the [DII](../ref-info/glossary-uid.md#gl-dii) is an email address or a phone number, send a [POST /token/generate](../endpoints/post-token-generate.md) request using one of the following values:
- The `optout@email.com` as the `email` value.
- The hash of `optout@email.com` as the `email_hash` value.
- The `+00000000000` as the `phone` value.
- The hash of `+00000000000` as the `phone_hash` value.
- The `refresh-optout@example.com` as the `email` value.
- The hash of `refresh-optout@example.com` as the `email_hash` value.
- The `+00000000002` as the `phone` value.
- The hash of `+00000000002` as the `phone_hash` value.
2. Store the returned `refresh_token` for use in the following step.
3. Send a [POST /token/refresh](../endpoints/post-token-refresh.md) request with the `refresh_token` (saved in step 2) as the `token` value.<br/>The body response should be empty, and the `status` value should be set to `optout` because the `optout@email.com` email and the `+00000000000` phone number always result in a logged out user.
3. Send a [POST /token/refresh](../endpoints/post-token-refresh.md) request with the `refresh_token` (saved in step 2) as the `token` value.<br/>The body response should be empty, and the `status` value should be set to `optout` because the `refresh-optout@example.com` email and the `+00000000002` phone number always result in a logged out user.

#### What is the uniqueness and rotation policy for UID2 tokens?

Expand Down
16 changes: 8 additions & 8 deletions docs/guides/snowflake_integration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ The following sections include query examples for each solution, which are ident
```
For example:
```
select UID2, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_IDENTITY_MAP('validate@email.com', 'email'));
select UID2, BUCKET_ID, UNMAPPED from table({DATABASE_NAME}.{SCHEMA_NAME}.FN_T_UID2_IDENTITY_MAP('validate@example.com', 'email'));
```

All query examples use the following default values for each name variable:
Expand Down Expand Up @@ -169,13 +169,13 @@ The following queries illustrate how to map a single email address, using the [d
Advertiser solution query for a single email:

```
select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP('validate@email.com', 'email'));
select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP('validate@example.com', 'email'));
```

Data provider solution query for a single email:

```
select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP('validate@email.com', 'email'));
select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP('validate@example.com', 'email'));
```

Query results for a single email:
Expand Down Expand Up @@ -216,7 +216,7 @@ The following table identifies each item in the response, including `NULL` value
+----+--------------------+----------------------------------------------+------------+--------------------+
| ID | EMAIL | UID2 | BUCKET_ID | UNMAPPED |
+----+--------------------+----------------------------------------------+------------+--------------------+
| 1 | validate@email.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL |
| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | NULL |
| 2 | [email protected] | IbW4n6LIvtDj/8fCESlU0QG9K/fH63UdcTkJpAG8fIQ= | a30od4mNRd | NULL |
| 3 | invalid-email | NULL | NULL | INVALID IDENTIFIER |
| 4 | NULL | NULL | NULL | INVALID IDENTIFIER |
Expand Down Expand Up @@ -295,13 +295,13 @@ The following queries illustrate how to map a single email address hash, using t
Advertiser solution query for a single hashed email:

```
select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('validate@email.com', 256)), 'email_hash'));
select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_ADV_SH.ADV.FN_T_UID2_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('validate@example.com', 256)), 'email_hash'));
```

Data provider solution query for a single hashed email:

```
select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('validate@email.com', 256)), 'email_hash'));
select UID2, BUCKET_ID, UNMAPPED from table(UID2_PROD_DP_SH.DP.FN_T_UID2_IDENTITY_MAP(BASE64_ENCODE(SHA2_BINARY('validate@example.com', 256)), 'email_hash'));
```

Query results for a single hashed email:
Expand Down Expand Up @@ -432,7 +432,7 @@ select * from AUDIENCE_WITH_UID2;
+----+--------------------+----------------------------------------------+------------+-------------------------+
| ID | EMAIL | UID2 | BUCKET_ID | LAST_UID2_UPDATE_UTC |
+----+--------------------+----------------------------------------------+------------+-------------------------+
| 1 | validate@email.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | 2021-03-01 00:00:00.000 |
| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | 2021-03-01 00:00:00.000 |
| 2 | [email protected] | Q4A5ZBuBCYfuV3Wd8Fdsx2+i33v7jyFcQbcMG/LH4eM= | ad1ANEmVZ | 2021-03-03 00:00:00.000 |
| 3 | [email protected] | NULL | NULL | NULL |
+----+--------------------+----------------------------------------------+------------+-------------------------+
Expand Down Expand Up @@ -466,7 +466,7 @@ The following table identifies each item in the response. The result includes an
+----+--------------------+----------------------------------------------+------------+-------------------------+-------------------------+
| ID | EMAIL | UID2 | BUCKET_ID | LAST_UID2_UPDATE_UTC | LAST_SALT_UPDATE_UTC |
+----+--------------------+----------------------------------------------+------------+-------------------------+-------------------------+
| 1 | validate@email.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | 2021-03-01 00:00:00.000 | 2021-03-02 00:00:00.000 |
| 1 | validate@example.com | 2ODl112/VS3x2vL+kG1439nPb7XNngLvOWiZGaMhdcU= | ad1ANEmVZ | 2021-03-01 00:00:00.000 | 2021-03-02 00:00:00.000 |
| 3 | [email protected] | NULL | NULL | NULL | NULL |
+----+--------------------+----------------------------------------------+------------+-------------------------+-------------------------+
```
Expand Down

0 comments on commit 9ed632f

Please sign in to comment.