|
| 1 | +# Deferred UID2/EUID Integration with Prebid.js (using mergeConfig) |
| 2 | + |
| 3 | +This example demonstrates how to integrate UID2 or EUID with Prebid.js using **deferred configuration**. Unlike the standard integration where UID2/EUID is configured on page load, this pattern uses `mergeConfig()` and `refreshUserIds()` to add the identity module *after* the page has already loaded. |
| 4 | + |
| 5 | +## Use Cases |
| 6 | + |
| 7 | +This pattern is useful for: |
| 8 | + |
| 9 | +- **Async Login**: User logs in after the page has loaded |
| 10 | +- **Delayed Consent**: Consent is given asynchronously (e.g., via a consent management platform) |
| 11 | +- **Single Page Applications (SPAs)**: Dynamic login/logout without full page reloads |
| 12 | +- **Lazy Loading**: Only load UID2/EUID when actually needed |
| 13 | +- **User State Changes**: Handle logout and re-login scenarios |
| 14 | + |
| 15 | +## How It Works |
| 16 | + |
| 17 | +### Standard Flow (for comparison) |
| 18 | +```javascript |
| 19 | +// Page load: UID2 configured immediately |
| 20 | +pbjs.setConfig({ |
| 21 | + userSync: { |
| 22 | + userIds: [{ name: 'uid2', params: {...} }] |
| 23 | + } |
| 24 | +}); |
| 25 | +``` |
| 26 | + |
| 27 | +### Deferred Flow (this example) |
| 28 | +```javascript |
| 29 | +// Step 1: Page load - Prebid configured WITHOUT UID2 |
| 30 | +pbjs.setConfig({ |
| 31 | + userSync: { |
| 32 | + syncDelay: 5000, |
| 33 | + auctionDelay: 1000, |
| 34 | + // Note: NO userIds configured here! |
| 35 | + } |
| 36 | +}); |
| 37 | + |
| 38 | +// Step 2: Later (after login, consent, etc.) - Add UID2 via mergeConfig |
| 39 | +pbjs.mergeConfig({ |
| 40 | + userSync: { |
| 41 | + userIds: [{ |
| 42 | + name: 'uid2', |
| 43 | + params: { |
| 44 | + uid2ApiBase: 'https://operator-integ.uidapi.com', |
| 45 | + |
| 46 | + subscriptionId: 'your-subscription-id', |
| 47 | + serverPublicKey: 'your-server-public-key' |
| 48 | + } |
| 49 | + }] |
| 50 | + } |
| 51 | +}); |
| 52 | + |
| 53 | +// Step 3: Trigger user ID refresh to generate the token |
| 54 | +await pbjs.refreshUserIds(); |
| 55 | +``` |
| 56 | + |
| 57 | +## Key Prebid.js APIs |
| 58 | + |
| 59 | +| API | Purpose | |
| 60 | +|-----|---------| |
| 61 | +| `pbjs.setConfig()` | Initial configuration (without UID2) | |
| 62 | +| `pbjs.mergeConfig()` | Add/update configuration without replacing existing config | |
| 63 | +| `pbjs.refreshUserIds()` | Trigger user ID module to fetch/generate new IDs | |
| 64 | +| `pbjs.getUserIds()` | Get current user IDs (check if token was generated) | |
| 65 | + |
| 66 | +## Live Examples |
| 67 | + |
| 68 | +- **UID2**: [https://unifiedid.com/examples/cstg-prebid-deferred-example/](https://unifiedid.com/examples/cstg-prebid-deferred-example/) |
| 69 | +- **EUID**: [https://euid.eu/examples/cstg-prebid-deferred-example/](https://euid.eu/examples/cstg-prebid-deferred-example/) |
| 70 | + |
| 71 | +## Running Locally |
| 72 | + |
| 73 | +### Using Docker Compose (recommended) |
| 74 | + |
| 75 | +From the repository root: |
| 76 | + |
| 77 | +```bash |
| 78 | +docker compose up prebid-client-side-deferred |
| 79 | +``` |
| 80 | + |
| 81 | +Access at: http://localhost:3053 |
| 82 | + |
| 83 | +### Using the Reverse Proxy |
| 84 | + |
| 85 | +```bash |
| 86 | +docker compose up |
| 87 | +``` |
| 88 | + |
| 89 | +Access at: http://prebid-deferred.sample-dev.com (requires hosts file configuration) |
| 90 | + |
| 91 | +## Environment Variables |
| 92 | + |
| 93 | +| Variable | Description | Default | |
| 94 | +|----------|-------------|---------| |
| 95 | +| `UID_CLIENT_BASE_URL` | API base URL for client-side calls | `https://operator-integ.uidapi.com` | |
| 96 | +| `UID_CSTG_SUBSCRIPTION_ID` | Your CSTG subscription ID | Test value provided | |
| 97 | +| `UID_CSTG_SERVER_PUBLIC_KEY` | Your CSTG server public key | Test value provided | |
| 98 | +| `UID_STORAGE_KEY` | localStorage key for token storage | `__uid2_advertising_token` | |
| 99 | +| `IDENTITY_NAME` | Display name (UID2 or EUID) | `UID2` | |
| 100 | +| `DOCS_BASE_URL` | Base URL for documentation links | `https://unifiedid.com/docs` | |
| 101 | + |
| 102 | +## Testing Flow |
| 103 | + |
| 104 | +1. **Page loads** - Observe that Prebid is loaded but UID2 shows "Not yet configured (deferred)" |
| 105 | +2. **Enter email** - Type an email address in the input field |
| 106 | +3. **Click "Configure UID2 with mergeConfig()"** - This triggers: |
| 107 | + - `pbjs.mergeConfig()` to add UID2 configuration |
| 108 | + - `pbjs.refreshUserIds()` to generate the token |
| 109 | +4. **Observe results** - Token appears in the status tables |
| 110 | +5. **Test opt-out ** - Use `[email protected]` to see opt-out behavior |
| 111 | + |
| 112 | +## Documentation |
| 113 | + |
| 114 | +- [UID2 Client-Side Integration Guide for Prebid.js](https://unifiedid.com/docs/guides/integration-prebid-client-side) |
| 115 | +- [EUID Client-Side Integration Guide for Prebid.js](https://euid.eu/docs/guides/integration-prebid-client-side) |
| 116 | +- [Prebid.js User ID Module](https://docs.prebid.org/dev-docs/modules/userId.html) |
| 117 | +- [Prebid.js setConfig/mergeConfig](https://docs.prebid.org/dev-docs/publisher-api-reference/setConfig.html) |
| 118 | + |
| 119 | +## Related Examples |
| 120 | + |
| 121 | +- [client-side](../client-side/) - Standard Prebid + UID2 (configured on page load) |
| 122 | +- [client-server](../client-server/) - Server-side token generation with Prebid |
| 123 | + |
0 commit comments