|
1 | 1 | # UID2 Integration Examples |
2 | 2 |
|
3 | | -The [UID2 framework](https://unifiedid.com/docs/intro) enables publishers to integrate in either of the following ways: |
| 3 | +Sample sites demonstrating UID2/EUID integration patterns. |
4 | 4 |
|
5 | | -- Via the standard integration workflow, using the [UID2 SDK for JavaScript](https://unifiedid.com/docs/sdks/client-side-identity) (also known as the UID2 SDK). |
6 | | -- Via the server-only (custom) integration workflow, by building a direct integration without using the UID2 SDK. |
| 5 | +## Prerequisites |
7 | 6 |
|
8 | | -If you are a content publisher interested in generating UID2 tokens for the real-time bidding (RTB) bid stream and want to see how you can use the UID2 services and which integration fits your needs best, you can build and run an example application for each integration. |
| 7 | +### 1. Set Up Environment Variables |
9 | 8 |
|
10 | | -The following table summarizes both examples and provides links to the example applications, their documentation, and the respective step-by-step integration guides. |
| 9 | +Copy one of the sample environment files: |
11 | 10 |
|
12 | | -| Environment | Documentation | Description | Primary Audience | Integration Guide | |
13 | | -|-------------|----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
14 | | -| Node.js | [UID2 SDK Integration Example](./publisher/standard/README.md) | Demonstrates how to use the UID2 services with the [UID2 client SDK](https://unifiedid.com/docs/sdks/client-side-identity) to implement the standard UID2 integration workflow. | Publishers with web assets | [Client SDK Integration Guide](https://unifiedid.com/docs/guides/publisher-client-side) | |
15 | | -| Node.js | [Server-Only UID2 Integration Example](https://github.com/UnifiedID2/uid2-examples/tree/main/publisher/server_only) | Demonstrates how to use the UID2 services to implement a custom (server-only) UID2 integration workflow without relying on an SDK for establishing client UID2 identity and retrieving advertising tokens. | App developers and CTV broadcasters | [Server-Only UID2 Integration Guide](https://unifiedid.com/docs/guides/custom-publisher-integration) | |
16 | | -| Java | [Java SDK Integration Example](./publisher/uid2-java-test-site/README.md) | Demonstrates use of the [UID2 Java SDK](https://github.com/IABTechLab/uid2-client-java) for both a server-only UID2 integration, and a standard (client SDK and server SDK) integration. | Publishers with web assets, app developers, CTV broadcasters | [Server-Only](https://unifiedid.com/docs/guides/custom-publisher-integration); [Client SDK](https://unifiedid.com/docs/guides/publisher-client-side) | |
| 11 | +```bash |
| 12 | +# For UID2 |
| 13 | +cp .env.sample.uid2 .env |
| 14 | + |
| 15 | +# For EUID |
| 16 | +cp .env.sample.euid .env |
| 17 | +``` |
| 18 | + |
| 19 | +Edit `.env` and add your credentials: |
| 20 | +- `UID_API_KEY` - Your API key |
| 21 | +- `UID_CLIENT_SECRET` - Your client secret |
| 22 | +- `UID_CSTG_SERVER_PUBLIC_KEY` - Your CSTG public key |
| 23 | +- `UID_CSTG_SUBSCRIPTION_ID` - Your CSTG subscription ID |
17 | 24 |
|
18 | | -The example applications illustrate the basic steps that you need to consider for your integration. For example, you need to decide how to do the following: |
19 | | -- Implement user login and logout. |
20 | | -- Manage UID2 identity information and use it for targeted advertising. |
21 | | -- Refresh tokens. |
22 | | -- Deal with missing identities. |
23 | | -- Handle user opt-outs. |
| 25 | +### 2. Run a Local Operator (Required) |
24 | 26 |
|
25 | | -## Docker Compose Setup |
| 27 | +These sample sites require a local UID2 operator instance. |
| 28 | + |
| 29 | +1. Clone the operator repo: |
| 30 | + ```bash |
| 31 | + git clone https://github.com/IABTechLab/uid2-operator.git |
| 32 | + ``` |
26 | 33 |
|
27 | | -This repository includes Docker Compose configuration for easy development and testing of multiple UID2 integration examples. |
| 34 | +2. Follow the setup instructions in the [uid2-operator README](https://github.com/IABTechLab/uid2-operator#readme) |
28 | 35 |
|
29 | | -### Quick Start |
| 36 | +3. Ensure the operator is running on `http://localhost:8080` |
| 37 | + |
| 38 | +--- |
| 39 | + |
| 40 | +## Running the Sample Sites |
| 41 | + |
| 42 | +### Start All Services |
30 | 43 |
|
31 | | -**Start all services:** |
32 | 44 | ```bash |
33 | 45 | docker-compose up -d |
34 | 46 | ``` |
35 | 47 |
|
36 | | -**Start a single service:** |
| 48 | +### Stop All Services |
| 49 | + |
| 50 | +```bash |
| 51 | +docker-compose down |
| 52 | +``` |
| 53 | + |
| 54 | +### Start a Single Service |
| 55 | + |
37 | 56 | ```bash |
38 | | -# Start only the Prebid.js client-side integration |
| 57 | +# Start only prebid-client |
39 | 58 | docker-compose up -d prebid-client |
40 | 59 |
|
41 | 60 | # Start with live logs (foreground) |
42 | 61 | docker-compose up prebid-client |
43 | 62 | ``` |
44 | 63 |
|
45 | | -**Stop services:** |
46 | | -```bash |
47 | | -# Stop all services |
48 | | -docker-compose down |
| 64 | +### Stop a Single Service |
49 | 65 |
|
50 | | -# Stop a single service |
| 66 | +```bash |
51 | 67 | docker-compose stop prebid-client |
52 | 68 | ``` |
53 | 69 |
|
54 | | -**View logs:** |
55 | | -```bash |
56 | | -# View all logs |
57 | | -docker-compose logs -f |
| 70 | +### Rebuild After Code Changes |
58 | 71 |
|
59 | | -# View logs for a specific service |
60 | | -docker-compose logs -f prebid-client |
61 | | -``` |
62 | | - |
63 | | -**Rebuild and restart:** |
64 | 72 | ```bash |
65 | | -# Rebuild and restart all services |
| 73 | +# Rebuild all |
66 | 74 | docker-compose up -d --build |
67 | 75 |
|
68 | | -# Rebuild and restart a single service |
| 76 | +# Rebuild a single service |
69 | 77 | docker-compose up -d --build prebid-client |
70 | 78 | ``` |
71 | 79 |
|
72 | | -### Available Services |
73 | | - |
74 | | -- **`prebid-client`** - Prebid.js client-side integration (Port: 3031) |
75 | | -- **`javascript-sdk-client`** - JavaScript SDK client-server integration (Port: 3051) |
76 | | -- *More services will be added as they are containerized* |
| 80 | +--- |
77 | 81 |
|
78 | | -### Environment Configuration |
| 82 | +## Available Sample Sites |
79 | 83 |
|
80 | | -This repository includes sample environment files for both UID2 and EUID configurations: |
| 84 | +| Service Name | Description | Port | URL | |
| 85 | +|--------------|-------------|------|-----| |
| 86 | +| `javascript-sdk-client-side` | JavaScript SDK Client Side | 3031 | http://localhost:3031 | |
| 87 | +| `javascript-sdk-client-server` | JavaScript SDK Client Server | 3032 | http://localhost:3032 | |
| 88 | +| `server-side` | Server Side Integration | 3033 | http://localhost:3033 | |
| 89 | +| `javascript-sdk-react-client-side` | JavaScript SDK React | 3034 | http://localhost:3034 | |
| 90 | +| `google-secure-signals-client-server` | Google Secure Signals Client Server | 3041 | http://localhost:3041 | |
| 91 | +| `google-secure-signals-client-side` | Google Secure Signals Client Side | 3042 | http://localhost:3042 | |
| 92 | +| `google-secure-signals-server-side` | Google Secure Signals Server Side | 3043 | http://localhost:3043 | |
| 93 | +| `google-secure-signals-react-client-side` | Google Secure Signals React | 3044 | http://localhost:3044 | |
| 94 | +| `prebid-client` | Prebid Client Side | 3051 | http://localhost:3051 | |
| 95 | +| `prebid-client-server` | Prebid Client Server | 3052 | http://localhost:3052 | |
| 96 | +| `prebid-client-side-deferred` | Prebid Client Side Deferred | 3053 | http://localhost:3053 | |
| 97 | +| `prebid-secure-signals-client-side` | Prebid Secure Signals | 3061 | http://localhost:3061 | |
81 | 98 |
|
82 | | -- **`.env.sample.uid2`** - UID2 configuration template |
83 | | -- **`.env.sample.euid`** - EUID configuration template |
| 99 | +--- |
84 | 100 |
|
85 | | -**To get started:** |
86 | | - |
87 | | -1. Copy the appropriate sample file to `.env`: |
88 | | - ```bash |
89 | | - # For UID2 |
90 | | - cp .env.sample.uid2 .env |
91 | | - |
92 | | - # For EUID |
93 | | - cp .env.sample.euid .env |
94 | | - ``` |
| 101 | +## Run Without Local Operator (Using Integ Environment) |
95 | 102 |
|
96 | | -2. Update the `.env` file with your credentials: |
97 | | - - Replace `your-api-key` with your actual API key |
98 | | - - Replace `your-client-secret` with your actual client secret |
99 | | - - Update other placeholder values as needed |
| 103 | +If you don't want to run a local operator, you can use HTTPS with custom domains to hit the integration environment operator instead. |
100 | 104 |
|
101 | | -The sample files include all necessary environment variables for running the examples, including configuration for: |
102 | | -- Core API endpoints |
103 | | -- JavaScript SDK settings |
104 | | -- Google Secure Signals integration |
105 | | -- Prebid integration |
106 | | -- React client examples |
107 | | -- UI/Display preferences |
| 105 | +This setup: |
| 106 | +- Uses `https://` with subdomains (e.g., `https://prebid-client.sample-dev.com`) |
| 107 | +- Connects to the UID2 integration operator (no local operator required) |
| 108 | +- Requires certificate setup and hosts file configuration |
108 | 109 |
|
| 110 | +See [tools/reverse-proxy/README.md](tools/reverse-proxy/README.md) for setup instructions. |
0 commit comments