Aul UI d2 5559 integration page 2

[aulme]

No description provided.

[genwhittTTD]

Some copy comments. Plus there are broken links... posting in the thread.

[genwhittTTD]

Not keen on use of "may" since it has two key meanings, permission or possibility. Suggest:

In the context of mapping DII to raw UID2s, a refresh timestamp is a Unix timestamp (in seconds) returned in the 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.

[genwhittTTD]

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.

[genwhittTTD]

Edit to second sentence:

At some point after that time, the raw UID2 is refreshed.

[genwhittTTD]

1. 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.

[genwhittTTD]

Here we should have "raw UID2s" in the link and the title:

• How do I know when to refresh mapped raw UID2s?

[genwhittTTD]

How do I know when to refresh mapped raw UID2s?

[genwhittTTD]

may > might

[genwhittTTD]

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.

[genwhittTTD]

I've done only a partial review. It'd be easier if I could check in mods myself. Pending input on that. Otherwise I'll finish the review... but it's more time for both of us, I think.

[genwhittTTD]

1. This is a broken link, plus old FAQ copy that doesn't exist in the file (2 instances)

2. It looks as though the copy was updated to "How do I know when to refresh mapped raw UID2s?" but this FAQ also appears in the DSP section. We can't have the same title twice in one file -- anchors will not work as expected. Could we adjust one slightly? Like, it doesn't need to say "mapped" maybe, you could take it out of the first one so that each is unique?

[genwhittTTD]

1. broken link

2. no period at the end here, since the link copy has a question mark. Otherwise the output looks like this: "How do I know when to refresh a raw UID2?."

[genwhittTTD]

Raw UID2s > raw UID2s

We don't initial cap "raw" unless it's in a heading.

[genwhittTTD]

Code tag on the field title:
(r field) > (r field)

[genwhittTTD]

Two things here:

1. Raw UID2 > raw UID2

2. "when each Raw UID2 might refresh." -- is that correct? I don't think so. It indicates a date, before which the UID2 will not update and after that timestamp it will at some point.

Also BTW I'm uneasy about using "refresh" for the salt rotation since that word is already headily used in the context of UID2, mainly for refreshing tokens.

In fact, I prefer to answer we gave earlier (line 182). We should just cross-reference to that, not have two slightly different versions of the same info.

[aulme]

That is indeed related - refresh here is also about replacing expired tokens with non-expired ones. I get the idea though, happy to change.

[genwhittTTD]

Some more comments marked.

I feel it's laborious for me to ask you to make these mods to conform to doc dept standards, but it's necessary. That's part of why I offered to do some of this work. Anyway, most of this looks great.

Discussed with gmsdelmundo in our last meeting... I think it would be really good if we update the text representation of POST /identity/map to include the version, since we now have two documented versions: POST /v3/identity/map and POST /v2/identity/map. I think it would add a little bit of clarity. Just a suggestion for now. I could implement it later, too.

[genwhittTTD]

We should not say "older integration approach" -- previous is fine, but also we should call it out by version. Words like older and newer are easily missed in updates. We recommend the latest, people should upgrade ASAP, but for any specific data, let's call out what version it applies to.

[genwhittTTD]

Add a comma before the last item (style decision in our docs, and in technical docs in general):

   UID->>ADP: 5-c. Store the new raw UID2 (u), refresh timestamp (r), and optionally previous UID2 (p) returned from the POST /identity/map endpoint.

[genwhittTTD]

Please also store the URL for the updated diagram, as we have for previous iterations, in this file. Same for the other updated diagram.

Nice catches on the couple of things you fixed on the diagram by the way.

[genwhittTTD]

Not sure where to comment this. But, we now have two pairs of image files and only one pair of source files. We need a source file for each image file. Plus the file naming doesn't match. Per doc guidelines we need a source file of the same name for each image file.

[aulme]

It looks like the image source file has many previous iterations of the image rather than just one. Happy to separate it out though.

[genwhittTTD]

Same on line 10 and line 20: just add the comma. Here:

UID->>ADP: 5-c. Store the new raw UID2 (u), refresh timestamp (r) and optionally previous UID2 (p) returned from the POST /identity/map endpoint.

[genwhittTTD]

Not sure why we don't include optionally the previous UID2, in this one instance?

[genwhittTTD]

this is good wording :-)

[genwhittTTD]

with stored refresh timestamps > with the stored refresh timestamps

[genwhittTTD]

This one needs to link to the v2 endpoint until the Snowflake docs are updated, I think.