Aul UI d2 5574 identity map v3 technical sample #915
There are no files selected for viewing
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
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
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
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| <!-- Used by 4 docs: guides/integration-advertiser-dataprovider-endpoints.md | guides/integration-advertiser-dataprovider-overview.md | sdks/isdk-ref-java.md | sdks/isdk-ref-python.md --> | ||
|
|
||
| import Link from '@docusaurus/Link'; | ||
|
|
||
| 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. | ||
|
|
||
| For step-by-step setup instructions and to run the example, see the README.md file: [UID2 Integration Technical Sample](https://github.com/IABTechLab/uid2docs/blob/main/static/examples/identity-map-integration-example/README.md). |
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| UID2_BASE_URL=https://operator-integ.uidapi.com | ||
| UID2_API_KEY=your_api_key_here | ||
| UID2_SECRET_KEY=your_secret_key_here |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| # Environment variables | ||
| .env | ||
|
|
||
| # Python cache | ||
| __pycache__/ | ||
| *.pyc | ||
|
|
||
| # Virtual environments (legacy and uv) | ||
| venv/ | ||
| .venv/ | ||
|
|
||
| # uv lock file | ||
| uv.lock | ||
|
|
||
| # Database files | ||
| *.db | ||
|
|
||
| .idea |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| 3.13 |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,123 @@ | ||
| # UID2 Integration Technical Sample | ||
|
|
||
| **Complete UID2 integration example demonstrating Identity Map v3 flow.** | ||
|
|
||
| This sample shows a pattern for mapping email addresses and phone numbers to UID2 tokens, handling optouts, managing token refresh cycles, and performing a sample attribution analysis based on both current and previous UID2s. | ||
|
|
||
| ## Project Structure | ||
|
|
||
| ``` | ||
| identity-map-integration-example/ | ||
| ├── src/ # Python source code | ||
| │ ├── complete_demo.py # End-to-end demo workflow | ||
| │ ├── map_identities.py # Core UID2 mapping logic | ||
| │ ├── attribution_analysis.py # Attribution analysis example | ||
| │ ├── config.py # Configuration loading | ||
| │ ├── database.py # Database schema and utilities | ||
| │ ├── uid_client_wrapper.py # UID2 client with retry logic | ||
| │ └── populate_*.py # Test data generation scripts | ||
| ├── .env # UID2 credentials (create from .env.example) | ||
| ├── pyproject.toml # Project configuration | ||
| └── README.md # This file | ||
| ``` | ||
|
|
||
| ## Quick Start | ||
|
|
||
| ### 1. Install Dependencies | ||
| ```bash | ||
| # Install uv (Python package manager) | ||
| curl -LsSf https://astral.sh/uv/install.sh | sh | ||
|
|
||
| # Install project dependencies | ||
| uv sync | ||
| ``` | ||
|
|
||
| ### 2. Configure UID2 Credentials | ||
| ```bash | ||
| cp .env.example .env | ||
| # Edit .env with your UID2 integration credentials | ||
| ``` | ||
|
|
||
| Required `.env` format: | ||
| ``` | ||
| UID2_BASE_URL=operator-integ.uidapi.com | ||
| UID2_API_KEY=your_api_key_here | ||
| UID2_SECRET_KEY=your_secret_key_here | ||
| ``` | ||
|
|
||
| ### 3. Run Complete Demo | ||
| ```bash | ||
| # Full workflow: test data population → UID2 mapping → attribution analysis | ||
| uv run src/complete_demo.py | ||
| ``` | ||
|
|
||
| ### 4. Run Individual Components | ||
| ```bash | ||
| # Generate test data only | ||
| uv run src/populate_test_uid_mappings.py | ||
|
|
||
| # Run UID2 mapping only | ||
| uv run src/map_identities.py | ||
|
|
||
| # Run attribution analysis only | ||
| uv run src/attribution_analysis.py | ||
| ``` | ||
|
|
||
| ## Core UID2 Integration Patterns | ||
|
|
||
| ### Identity Mapping Workflow | ||
|
|
||
| **Key Integration Points:** | ||
| 1. **Batch Processing** (`src/map_identities.py:build_uid2_input()`) - Process sequential batches of up to 5,000 emails and/or phone numbers per request | ||
| 2. **Retry Logic** (`src/uid_client_wrapper.py:generate_identity_map_with_retry()`) - Exponential backoff for network resilience | ||
| 3. **Response Handling** (`src/map_identities.py:process_uid2_response()`) - Process mapped, opted-out, and invalid identifiers | ||
|
|
||
| ## Sample Database Schema | ||
|
|
||
| **Core `uid_mapping` table:** | ||
| ```sql | ||
| CREATE TABLE uid_mapping ( | ||
| uid_mapping_id INTEGER PRIMARY KEY, | ||
| dii TEXT NOT NULL, -- Email or phone (+E.164) | ||
| dii_type TEXT NOT NULL, -- 'email' or 'phone' | ||
| current_uid TEXT, -- Current UID2 token | ||
| previous_uid TEXT, -- Previous UID2 token (only available for 90 days after rotation, afterwards NULL) | ||
| refresh_from TIMESTAMP, -- When to refresh mapping | ||
| opt_out BOOLEAN DEFAULT FALSE -- The user has opted out, we shouldn't attempt to map this user again | ||
| ); | ||
| ``` | ||
|
|
||
| **Key business logic queries:** | ||
| ```sql | ||
| -- Records needing mapping (never mapped + refresh expired) | ||
| SELECT uid_mapping_id, dii, dii_type | ||
| FROM uid_mapping | ||
| WHERE opt_out = FALSE | ||
| AND (current_uid IS NULL OR refresh_from < datetime('now')); | ||
|
|
||
| -- Attribution joins using both current and previous UID2s | ||
| SELECT * FROM impressions imp | ||
| JOIN uid_mapping um ON (imp.uid = um.current_uid OR imp.uid = um.previous_uid) | ||
| WHERE um.opt_out = FALSE; | ||
| ``` | ||
|
|
||
| ## Script Reference | ||
|
|
||
| | Script | Purpose | Key Integration Concepts | | ||
| |--------|---------|--------------------------------------------------| | ||
| | `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-UID2 joins, measurement patterns | | ||
| | `src/complete_demo.py` | End-to-end workflow | Full integration validation | | ||
|
|
||
| ## Production Integration Checklist | ||
|
|
||
| **Patterns for UID2 Integration:** | ||
|
|
||
| ✅ **Request Limits**: Maximum 5,000 emails and/or phone numbers per request | ||
| ✅ **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 | ||
| ✅ **Raw UID2 Refresh**: Re-map raw UID2s when they reach `refresh_from` timestamps | ||
| ✅ **State Persistence**: Track mapping state |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| [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" | ||
| requires-python = ">=3.13" | ||
| dependencies = [ | ||
| "python-dotenv>=1.0.0", | ||
| "uid2-client>=2.6.0", | ||
| ] | ||
|
|
||
| [dependency-groups] | ||
| dev = [ | ||
| "black>=23.0.0", | ||
| ] |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| #!/usr/bin/env python3 | ||
| """ | ||
| Simple demo of joining impression and conversion data via current and previous UIDs | ||
| """ | ||
| import sqlite3 | ||
| import traceback | ||
| from database import get_connection | ||
|
|
||
|
|
||
| def attribution_analysis(conn: sqlite3.Connection) -> None: | ||
| """Run simple attribution analysis query""" | ||
| cursor = conn.cursor() | ||
|
|
||
| attribution_query = """ | ||
| SELECT | ||
| imp.impression_id, | ||
| conv.conversion_id, | ||
| conv.conversion_value, | ||
| imp.campaign_id, | ||
| um.dii, | ||
| um.current_uid | ||
| FROM impressions imp | ||
| 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() | ||
|
Contributor
There was a problem hiding this comment. why do we want to order by random here?
Contributor
Author
There was a problem hiding this comment. 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. |
||
| LIMIT 10 | ||
| """ | ||
|
|
||
| cursor.execute(attribution_query) | ||
| results = cursor.fetchall() | ||
|
|
||
| print("Sample Attribution Results:") | ||
| print( | ||
| f"{'Impression':<12} {'Conversion':<12} {'Value':<10} {'Campaign':<12} {'DII':<40} {'UID':<15}" | ||
| ) | ||
| print("-" * 110) | ||
|
|
||
| for row in results: | ||
| imp_id, conv_id, value, campaign, dii, uid = row | ||
| print( | ||
| f"{imp_id:<12} {conv_id:<12} ${value:<9.2f} {campaign:<12} {dii:<40} {uid:<15}" | ||
| ) | ||
|
|
||
|
|
||
| def main(): | ||
| try: | ||
| conn = get_connection() | ||
| attribution_analysis(conn) | ||
| except Exception as e: | ||
| print(f"Attribution analysis failed: {e}") | ||
| traceback.print_exc() | ||
| finally: | ||
| if "conn" in locals(): | ||
| conn.close() | ||
|
|
||
|
|
||
| if __name__ == "__main__": | ||
| main() | ||
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If this is the identical copy, same edits and preferably a snippet... same as prior comment.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.