Aul UI d2 5574 identity map v3 technical sample #915

aulme · 2025-07-21T06:04:36Z

No description provided.

sophia-chen-ttd · 2025-07-22T05:17:35Z

static/examples/identity-map-integration-example/src/attribution_analysis.py

+    JOIN uid_mapping um ON (imp.uid = um.current_uid OR imp.uid = um.previous_uid)
+    JOIN conversions conv ON (conv.uid = um.current_uid OR conv.uid = um.previous_uid)
+    WHERE um.opt_out = FALSE
+    ORDER BY RANDOM()


why do we want to order by random here?

Just for the demo - we're showing 10 rows, if we don't order by random you'll just see a bunch of rows for the same impression.

sophia-chen-ttd · 2025-07-22T06:53:44Z

static/examples/identity-map-integration-example/README.md

+
+### 3. Run Complete Demo
+```bash
+# Full workflow: test data → UID2 mapping → attribution analysis


I think it would help to be more specific that it is 'test data population'

Sure, will add

genwhittTTD

I didn't finish. looks great but multiple small copy fixes.

Hoping you could address and I could look again tomorrow -- or even, if you want, I could address... but there are a couple of questions I've marked. Hope this helps anyway. I will look again tomorrow.

genwhittTTD · 2025-07-23T21:31:34Z

docs/guides/integration-advertiser-dataprovider-endpoints.md


+## Integration Example
+
+For a complete demonstration of a working integration that includes all the recommended patterns, see the [UID2 Identity Map V3 Integration Example](https://github.com/IABTechLab/uid2docs/blob/main/static/examples/identity-map-integration-example).


V3 > v3 -- could we do this in the destination please? Or say Version 3

genwhittTTD · 2025-07-23T21:32:47Z

docs/guides/integration-advertiser-dataprovider-endpoints.md

+## Integration Example
+
+For a complete demonstration of a working integration that includes all the recommended patterns, see the [UID2 Identity Map V3 Integration Example](https://github.com/IABTechLab/uid2docs/blob/main/static/examples/identity-map-integration-example).
+While the sample is implemented using the Python SDK, the integration patterns are applicable to any SDK or direct API integration.


This isn't the main meaning for "while" so better not to use it, to avoid possible misunderstanding..
From
While the sample is implemented using the Python SDK, the integration patterns are applicable to any SDK or direct API integration.
To
The sample uses the Python SDK, but the integration patterns are applicable to any SDK or direct API integration.

genwhittTTD · 2025-07-23T21:35:20Z

docs/guides/integration-advertiser-dataprovider-endpoints.md

+For a complete demonstration of a working integration that includes all the recommended patterns, see the [UID2 Identity Map V3 Integration Example](https://github.com/IABTechLab/uid2docs/blob/main/static/examples/identity-map-integration-example).
+While the sample is implemented using the Python SDK, the integration patterns are applicable to any SDK or direct API integration.
+
+For step-by-step setup instructions and to run the example, see the [Integration Example README](https://github.com/IABTechLab/uid2docs/blob/main/static/examples/identity-map-integration-example/README.md).


For the link copy, use the title of the destination doc. In which case we don't need "the" also.
From:
see the [Integration Example README]
To:
see [UID2 Integration Technical Sample]

genwhittTTD · 2025-07-23T21:36:11Z

docs/guides/integration-advertiser-dataprovider-overview.md

 | [5: Monitor for Raw UID2 Refresh](#5-monitor-for-raw-uid2-refresh) | Use the refresh timestamp (`r` field) returned from the [POST&nbsp;/identity/map](../endpoints/post-identity-map.md) endpoint to determine when to refresh Raw UID2s. |
 | [6: Monitor for Opt-Out Status](#6-monitor-for-opt-out-status) | API call to the [POST /optout/status](../endpoints/post-optout-status.md) endpoint. |

+## Integration Example


Is this identical copy? If yes -- on the short term, same edits.
But, better if we implement as a snippet. I can do it if you want.

A question. Is this applicable to Snowflake, and/or AWS Entity Resolution?

Yes, it is and it is applicable to Snowflake. Gian is finishing changes to that doc now. This is not applicable to AWS Entity Resolution.

I'll make changes you've suggested above across the board.
Didn't know about snippets, could you please help with that?

genwhittTTD · 2025-07-23T21:38:52Z

docs/sdks/sdk-ref-python.md

 mixed_response = client.generate_identity_map(mixed_input)
 ```

+### Integration Example


If this is the identical copy, same edits and preferably a snippet... same as prior comment.

There's a subtle difference for Python SDK vs the others - in other places I say that the pattern is applicable despite the example using Python SDK, here I don't. Not sure it's worth keeping them separate though - happy to make it the same.

@aulme that makes sense, thx. But I do think we should have a snippet. I think it'd be OK to still have that line in the Python SDK doc... it's kind of unnecessary data but I don't think it sounds weird. It's just info.

LMK if you want me to do that for you in the branch.

genwhittTTD · 2025-07-23T21:49:26Z

static/examples/identity-map-integration-example/README.md

+WHERE opt_out = FALSE 
+AND (current_uid IS NULL OR refresh_from < datetime('now'));
+
+-- Attribution joins using both current and previous UIDs


UIDs > UID2s

static/examples/identity-map-integration-example/README.md

genwhittTTD · 2025-07-23T21:50:07Z

static/examples/identity-map-integration-example/README.md

+
+**Patterns for UID2 Integration:**
+
+✅ **Request Limits**: Maximum 5,000 DIIs per request  


As previous. Don't say DIIs anywhere.

genwhittTTD · 2025-07-23T21:50:42Z

static/examples/identity-map-integration-example/README.md

+✅ **Sequential Processing**: No parallel requests to UID2 service  
+✅ **Retry Logic**: Exponential backoff for network failures  
+✅ **Optout Handling**: Permanent exclude opted out users from future processing
+✅ **Token Refresh**: Re-map tokens when they reach `refresh_from` timestamps  


Is it tokens, not raw UID2s?

Sorry, I raw UID2s, used colloquially

genwhittTTD · 2025-07-23T21:51:13Z

static/examples/identity-map-integration-example/pyproject.toml

+[project]
+name = "identity-map-tech-sample-2"
+version = "0.1.0"
+description = "UID2 Identity Map V3 technical sample demonstrating email/phone to UID2 mapping with proper optout handling"


V3 > v3

optout handling > opt-out handling

genwhittTTD

@aulme thanks for the fixes. One more small mod on the shared cotent, for a line break.
Some instances of UID that should be UID2, still.
Also instances of DIIs -- I'd really like if we didn't have this, even in the code. It's not correct.

All else looks great, thx.

genwhittTTD · 2025-07-24T15:23:25Z

docs/guides/integration-advertiser-dataprovider-endpoints.md

+### Integration Example
+
+For a complete demonstration of a working integration that includes all the recommended patterns, see the [UID2 Identity Map v3 Integration Example](https://github.com/IABTechLab/uid2docs/blob/main/static/examples/identity-map-integration-example).
+The sample uses the Python SDK, but the integration patterns are applicable to any SDK or direct API integration.


Need one extra line break to make a new para. Assuming you want a new para here. Same for all 4 instances.

genwhittTTD · 2025-07-24T16:09:11Z

docs/sdks/sdk-ref-python.md

 mixed_response = client.generate_identity_map(mixed_input)
 ```

+### Integration Example


@aulme that makes sense, thx. But I do think we should have a snippet. I think it'd be OK to still have that line in the Python SDK doc... it's kind of unnecessary data but I don't think it sounds weird. It's just info.

LMK if you want me to do that for you in the branch.

genwhittTTD · 2025-07-24T16:12:06Z

static/examples/identity-map-integration-example/README.md

+| `src/populate_test_uid_mappings.py` | Creates 100k test records | Database schema, DII formatting |
+| `src/map_identities.py` | **Core UID2 mapping logic** | Batch processing, retry logic, response handling |
+| `src/populate_test_conversions_impressions.py` | Attribution demo data | UID2 token usage in measurement |
+| `src/attribution_analysis.py` | Attribution analysis | Cross-UID joins, measurement patterns |


genwhittTTD · 2025-07-24T16:12:54Z

static/examples/identity-map-integration-example/src/complete_demo.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""
+Complete demo of UID Identity Mapping:


UID > UID2

Should be everywhere except code. Since this is for the UID2 site, not shared content.

genwhittTTD · 2025-07-24T16:13:07Z

static/examples/identity-map-integration-example/src/complete_demo.py

+Complete demo of UID Identity Mapping:
+   - Creates a test database.
+   - Populates the database with test identity mapping data.
+   - Runs the UID mapping process.


genwhittTTD · 2025-07-24T16:14:08Z

static/examples/identity-map-integration-example/src/map_identities.py

+
+
+def build_uid_input(records: list[IdentityToMap]) -> tuple[IdentityMapV3Input, list[str]]:
+    """Build UID input object from database records. 


genwhittTTD · 2025-07-24T16:14:24Z

static/examples/identity-map-integration-example/src/populate_test_conversions_impressions.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""
+UID Attribution Test Data Population


genwhittTTD · 2025-07-24T16:14:36Z

static/examples/identity-map-integration-example/src/populate_test_conversions_impressions.py

+UID Attribution Test Data Population
+
+Creates impression and conversion test data using actual mapped UIDs.
+Should be run AFTER UID mapping is complete.


genwhittTTD · 2025-07-24T16:15:00Z

static/examples/identity-map-integration-example/src/populate_test_uid_mappings.py

+
+
+def generate_uid() -> str:
+    """Generate a UID for testing"""


genwhittTTD · 2025-07-24T16:17:22Z

static/examples/identity-map-integration-example/src/populate_test_uid_mappings.py

+    print(f"  Opted out: {opted_out_count}")
+    print(f"  Up for refresh: {refresh_needed_count}")
+    print(f"  Never mapped: {never_mapped_count}")
+    print(f"  Invalid DIIs: {invalid_dii_count}")


Can we get "DIIs" out? Maybe even out of the code? It would be better to say DII. It's a collective term. More than one email address or phone number is still DII.

There are multiple instances. I didn't mark them because they're in the code but if we change them all it will work I think? It would be good to not have this, even in the code.

aulme added 2 commits July 21, 2025 13:42

Integration Sample for Identity Map V3

2c56c71

Moved code to /src folder

2d72ae2

aulme requested review from gmsdelmundo, sophia-chen-ttd and vishalegbert-ttd July 21, 2025 06:16

sophia-chen-ttd reviewed Jul 22, 2025

View reviewed changes

aulme added 2 commits July 22, 2025 15:50

Added references to sample from various docs

b39b927

Better wording

8ae1c19

genwhittTTD requested changes Jul 23, 2025

View reviewed changes

Addressing Gen's feedback

8588213

genwhittTTD requested changes Jul 24, 2025

View reviewed changes

genwhittTTD and others added 5 commits July 25, 2025 12:56

implemented snippet + resequenced in Adv guides

0ead1ec

addressed comments

846610b

fix build issue due to missing import statement

b67e514

updated links

af5fa1e

fix broken links

bb2191d

miyaichi mentioned this pull request Aug 19, 2025

Jpn translation update 914 934 #935

Merged


		## Integration Example

		For a complete demonstration of a working integration that includes all the recommended patterns, see the [UID2 Identity Map V3 Integration Example](https://github.com/IABTechLab/uid2docs/blob/main/static/examples/identity-map-integration-example).


		Patterns for UID2 Integration:

		✅ Request Limits: Maximum 5,000 DIIs per request



		def build_uid_input(records: list[IdentityToMap]) -> tuple[IdentityMapV3Input, list[str]]:
		"""Build UID input object from database records.

Aul UI d2 5574 identity map v3 technical sample #915

Are you sure you want to change the base?

Aul UI d2 5574 identity map v3 technical sample #915

Uh oh!

Conversation

aulme commented Jul 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

genwhittTTD left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

genwhittTTD left a comment

Choose a reason for hiding this comment

Uh oh!

genwhittTTD Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

genwhittTTD Jul 24, 2025 •

edited

Loading