Aul UI d2 5559 integration page 2 #900
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
aulme
force-pushed
the
aul-UID2-5559-integration-page-2
branch
from
9670d94 to
18174c2
Compare
genwhittTTD
requested changes
Jun 30, 2025
| @@ -399,6 +400,10 @@ import Link from '@docusaurus/Link'; | |||
| <dd>An unencrypted alphanumeric identifier created through the UID2 APIs or SDKs with the user's <a href="#gl-dii">directly identifying information</a> (email address or phone number) as input. The raw UID2 is encrypted to create a <a href="#gl-uid2-token">UID2 token</a>. The raw UID2 is a unique value; no two raw UID2s are the same. Raw UID2s, and their associated UID2 tokens, are case sensitive.</dd> | |||
| <dd>For details, see <a href="uid-identifier-types">UID2 Identifier Types</a>.</dd> | |||
|
|
|||
| <dt><MdxJumpAnchor id="gl-refresh-timestamp"><a href="#gl-refresh-timestamp">Refresh timestamp</a></MdxJumpAnchor></dt> | |||
| <dd>In the context of mapping <a href="#gl-dii">DII</a> to raw UID2s, a refresh timestamp is a Unix timestamp (in seconds) returned in the <code>r</code> field of the <a href="../endpoints/post-identity-map-v3">POST /identity/map</a> endpoint response. This timestamp indicates when the raw UID2 may refresh. It is guaranteed that the raw UID2 won't refresh before this timestamp, but it may or may not refresh after this time.</dd> | |||
There was a problem hiding this comment.
Not keen on use of "may" since it has two key meanings, permission or possibility. Suggest:
r field of the POST /identity/map endpoint response. The raw UID2 is guaranteed to be valid until this timestamp. It is refreshed at some point after this time.|
|
||
| Metadata supplied with the UID2 generation request indicates the <Link href="../ref-info/glossary-uid#gl-salt-bucket">salt bucket</Link> used for generating the UID2. Salt buckets persist and correspond to the underlying <Link href="../ref-info/glossary-uid#gl-dii">DII</Link> used to generate a UID2. Use the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint to return which salt buckets rotated since a given timestamp. The returned rotated salt buckets inform you which UID2s to refresh. | ||
| The V3 Identity Map API provides a refresh timestamp (`r` field) in the response that indicates when each raw UID2 may refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data. |
There was a problem hiding this comment.
3 mods: 1) move r field def, 2) reword "may". Also 3) Add a link on the mention of the API.:
The POST /identity/map endpoint provides a refresh timestamp in the response (r field) that indicates a timestamp, after which each raw UID2 might refresh. Use this timestamp to determine when to regenerate raw UID2s for your stored data.
| :::info | ||
| When mapping and remapping emails, do not make any assumptions about the number of buckets, their rotation dates, or the specific bucket that an email gets assigned to. | ||
| :::note | ||
| We recommend checking for refresh opportunities daily. It is guaranteed that the raw UID2 won't refresh before the indicated timestamp. Afterward the UID2 has a chance to rotate. |
There was a problem hiding this comment.
Edit to second sentence:
At some point after that time, the raw UID2 is refreshed.
| #### How often should UID2s be refreshed for incremental updates? | ||
|
|
||
| The recommended cadence for updating audiences is daily. | ||
|
|
||
| Even though each salt bucket is updated roughly once a year, individual bucket updates are spread over the year. This means that about 1/365th of all buckets are rotated daily. If fidelity is critical, consider calling the [POST /identity/buckets](../endpoints/post-identity-buckets.md) endpoint more frequently; for example, hourly. | ||
| A raw UID2 for a specific user changes at least once per year as part of the UID2 rotation process. The V3 Identity Map API provides refresh timestamps that indicate when each raw UID2 may refresh. We recommend checking these timestamps daily to ensure your UID2s remain current and valid for audience targeting. |
There was a problem hiding this comment.
- may > might + 2) "UID2 rotation" sounds to me as though we just rotate values -- slightly misleading. Suggest:
A raw UID2 for a specific user changes at least once per year. The V3 Identity Map API provides refresh timestamps that indicate a point after which each raw UID2 might refresh. We recommend checking these timestamps daily to ensure your UID2s remain current and valid for audience targeting.
| @@ -242,7 +239,7 @@ Here are some frequently asked questions for demand-side platforms (DSPs). | |||
| - [How do I know which decryption key to apply to a UID2?](#how-do-i-know-which-decryption-key-to-apply-to-a-uid2) | |||
| - [Where do I get the decryption keys?](#where-do-i-get-the-decryption-keys) | |||
| - [How many decryption keys may be present in memory at any point?](#how-many-decryption-keys-may-be-present-in-memory-at-any-point) | |||
| - [How do I know if/when the salt bucket has rotated?](#how-do-i-know-ifwhen-the-salt-bucket-has-rotated) | |||
| - [How do I know when to refresh mapped UID2s?](#how-do-i-know-when-to-refresh-mapped-uid2s) | |||
There was a problem hiding this comment.
Here we should have "raw UID2s" in the link and the title:
| @@ -267,17 +264,23 @@ You can use one of the server-side SDKs (see [SDKs: Summary](../sdks/summary-sdk | |||
|
|
|||
| There may be thousands of decryption keys present in the system at any given point. | |||
|
|
|||
| #### How do I know if/when the salt bucket has rotated? | |||
| #### How do I know when to refresh mapped UID2s? | |||
There was a problem hiding this comment.
How do I know when to refresh mapped raw UID2s?
| #### How do I know if/when the salt bucket has rotated? | ||
| #### How do I know when to refresh mapped UID2s? | ||
|
|
||
| If you are maintaining mapping of DII to raw UID2s, you should use the refresh timestamp returned from the [POST /identity/map](../endpoints/post-identity-map-v3.md) endpoint. The response includes a refresh timestamp (`r` field) that indicates when each UID2 may refresh. |
|
|
||
| The DSP is not privy to when the UID2 salt bucket rotates. This is similar to a DSP being unaware if users cleared their cookies. Salt bucket rotation has no significant impact on the DSP. | ||
| The DSP is not privy to when the UID2 salt rotates. This is similar to a DSP being unaware if users cleared their cookies. Salt rotation has no significant impact on the DSP. |
There was a problem hiding this comment.
We should leave salts out as much as poss (though there was a previous instance where I think we needed it). Removing it twice here:
The DSP is not privy to when the raw UID2 rotates. This is similar to a DSP being unaware if users cleared their cookies. Raw UID2 rotation has no significant impact on the DSP.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.