Merge pull request #907 from IABTechLab/aul-UID2-5558-identity-map-v3-http-migration-guide

POST Identity Map V3 improvements and tests for sample code

Author: aulme

docs/endpoints/post-identity-buckets.md

@@ -16,7 +16,7 @@ Used by: This endpoint is used mainly by advertisers and data providers. For det
 :::important
 If you're using the latest version of `POST /v3/identity/map`, v3, you don't need to use `POST /identity/buckets` at all. You only need to use it if you're using the earlier version, `POST /v2/identity/map`.
 
-If you're using the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements.
+If you're using the V2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration From V2 Identity Map](post-identity-map-v3.md#migration-from-v2-identity-map).
 :::
 
 ## Request Format

docs/endpoints/post-identity-map-v3.md

@@ -95,7 +95,7 @@ The following are unencrypted JSON request body examples to the `POST /identity/
 }
 ```
 
-Here's an encrypted request example to the `POST /identity/map` endpoint for a phone number:
+Here's an encrypted request example to the `POST /identity/map` endpoint for phone numbers:
 
 ```sh
 echo '{"phone": ["+12345678901", "+441234567890"]}' | python3 uid2_request.py https://prod.uidapi.com/v3/identity/map [YOUR_CLIENT_API_KEY] [YOUR_CLIENT_SECRET]
@@ -115,7 +115,7 @@ The response arrays preserve the order of input arrays. Each element in the resp
 
 Input values that cannot be mapped to a raw UID2 are mapped to an error object with the reason for unsuccessful mapping. An unsuccessful mapping occurs if the DII is invalid or has been opted out from the UID2 ecosystem. In these cases, the response status is `success` but no raw UID2 is returned.
 
-The following example shows input and response.
+The following example shows the input and corresponding response.
 
 Input:
 
@@ -153,7 +153,7 @@ Response:
       "phone": [],
       "phone_hash": []
     },
-    "status":"success"
+    "status": "success"
 }
 ```
 
@@ -190,7 +190,92 @@ The following table lists the `status` property values and their HTTP status cod
 | Status | HTTP Status Code | Description |
 | :--- | :--- | :--- |
 | `success` | 200 | The request was successful. The response will be encrypted. |
-| `client_error` | 400 | The request had missing or invalid parameters.|
+| `client_error` | 400 | The request had missing or invalid parameters. |
 | `unauthorized` | 401 | The request did not include a bearer token, included an invalid bearer token, or included a bearer token unauthorized to perform the requested operation. |
 
 If the `status` value is anything other than `success`, the `message` field provides additional information about the issue.
+
+## Migration From V2 Identity Map
+
+### Migration Overview
+
+The V3 Identity Map API provides several improvements over V2:
+
+- **Simplified Refresh Management**: Monitor for UID2s reaching `refresh_from` timestamps instead of polling <Link href="../ref-info/glossary-uid#gl-salt-bucket-id">salt buckets</Link> for rotation
+- **Previous UID2 Access**: Access to previous raw UID2s for 90 days after rotation for campaign measurement
+- **Single Endpoint**: Use only `/v3/identity/map` instead of both `/v2/identity/map` and `/v2/identity/buckets`
+- **Multiple Identity Types In One Request**: Process emails and phone numbers in a single request
+- **Improved Performance**: The V3 API uses significantly less bandwidth for the same amount of DII
+
+### Key Differences Between V2 and V3
+
+| Feature                        | V2 Implementation                           | V3 Implementation                          |
+|:-------------------------------|:--------------------------------------------|:-------------------------------------------|
+| **Endpoints Required**         | `/v2/identity/map` + `/v2/identity/buckets` | `/v3/identity/map` only                    |
+| **Identity Types per Request** | Single identity type only                   | Multiple identity types                    |
+| **Refresh Management**         | Monitor salt bucket rotations via `/identity/buckets` endpoint              | Re-map when past `refresh_from` timestamps |
+| **Previous UID2 Access**       | Not available                               | Available for 90 days        |
+
+### Required Changes
+
+#### 1. **Update Endpoint URL**
+
+```python
+# Before (V2)
+url = '/v2/identity/map'
+
+# After (V3) 
+url = '/v3/identity/map'
+```
+
+#### 2. **Update V3 Response Parsing Logic**
+
+**V2 Response Parsing**:
+```python
+# V2: Process mapped/unmapped objects with identifier lookup
+for item in response['body']['mapped']:
+    raw_uid = item['advertising_id']
+    bucket_id = item['bucket_id']
+    original_identifier = item['identifier']
+    # Store mapping using identifier as key
+    store_mapping(original_identifier, raw_uid, bucket_id)
+```
+
+**V3 Response Parsing**:
+```python
+# V3: Process array-indexed responses
+for index, item in enumerate(response['body']['email']):
+    original_email = request_emails[index]  # Use array index to correlate
+    if 'u' in item:
+        # Successfully mapped
+        current_uid = item['u']
+        previous_uid = item.get('p')  # Available for 90 days after rotation, otherwise None
+        refresh_from = item['r']
+        store_mapping(original_email, current_uid, previous_uid, refresh_from)
+    elif 'e' in item:
+        # Handle unmapped with reason
+        handle_unmapped(original_email, item['e'])
+```
+
+#### 3. **Replace Salt Bucket Monitoring with Refresh Timestamp Logic**
+**V3 Approach (Refresh Timestamps)**:
+
+```python
+import time
+
+def is_refresh_needed(mapping):
+    now = int(time.time() * 1000)  # Convert to milliseconds
+    return now >= mapping['refresh_from']
+
+# Check individual mappings for refresh needs
+to_remap = [mapping for mapping in mappings if is_refresh_needed(mapping)]
+remap_identities(to_remap)
+```
+
+### Additional Resources
+
+For SDK-specific migration guidance, see:
+- [SDK for JavaScript V3](../sdks/sdk-ref-javascript-v3.md) for client-side implementations
+- [SDK for Java](../sdks/sdk-ref-java.md) for server-side implementations (see Usage for Advertisers/Data Providers section)
+
+For general information about identity mapping, see [Advertiser/Data Provider Integration Overview](../guides/integration-advertiser-dataprovider-overview.md).

docs/endpoints/post-identity-map.md

@@ -20,7 +20,7 @@ For details about the UID2 opt-out workflow and how users can opt out, see [User
 This documentation is for version 2 of this endpoint, which is not the latest version. For the latest version, v3, see [POST /identity/map](post-identity-map-v3.md).
 
 :::note
-If you're using the earlier version, we recommend that you upgrade as soon as possible, to take advantage of improvements.
+If you're using the V2 version, we recommend that you upgrade as soon as possible, to take advantage of improvements. For migration guidance, see [Migration From V2 Identity Map](post-identity-map-v3.md#migration-from-v2-identity-map).
 :::
 
 ## Batch Size and Request Parallelization Requirements

test/python/.gitignore

@@ -0,0 +1,107 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.cache
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Linux
+*~
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# Logs
+*.log
+
+# Test results
+test-results/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath
+*.sage.py
+
+# Environments
+.env
+.env.local
+.env.*.local
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Local test data
+test_data/
+temp/
+tmp/ 

test/python/README.md

@@ -0,0 +1,24 @@
+# UID2 Documentation Python Tests
+
+This directory contains Python tests for the code samples in the [POST /identity/map v3 documentation](../../docs/endpoints/post-identity-map-v3.md). The tests verify that the Python code examples in the documentation work correctly and demonstrate proper usage patterns.
+
+## Quick Start
+
+### Prerequisites
+
+1. **Install UV** (Python package manager):
+   ```bash
+   pip install uv
+   ```
+
+## Environment Configuration
+Fill the following environment variables into the `.env` file. The file is gitignored.
+- `UID2_BASE_URL` - Integration environment endpoint
+- `UID2_API_KEY` - Test API key
+- `UID2_SECRET_KEY` - Test secret key
+
+### Run Tests
+```bash
+cd test/python
+uv run pytest
+```

test/python/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "uid2-docs-python-tests"
+version = "0.1.0"
+description = "Python tests for UID2 documentation code samples"
+requires-python = ">=3.8"
+dependencies = [
+    "uid2-client>=3.0.0a1",
+    "pytest>=7.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest-cov>=4.0.0", 
+]
+
+[tool.pytest.ini_options]
+testpaths = ["."]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--tb=short",
+    "--disable-warnings",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning",
+]