Skip to content

Commit a69cfa4

Browse files
lionell-pack-ttdbretg
lionell-pack-ttd
and
bretg
authored
Draft: Add docs for EUID module. (prebid#4603)
* Add docs for EUID module. * linter fixes --------- Co-authored-by: bretg <bgorsline@gmail.com>
1 parent b3429de commit a69cfa4

2 files changed

Lines changed: 189 additions & 1 deletion

File tree

‎dev-docs/modules/userid-submodules/euid.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
layout: userid
3+
title: European Unified ID
4+
description: European Unified ID User ID sub-module
5+
useridmodule: euidIdSystem
6+
---
7+
8+
European Unified ID (EUID) is an open-source identity solution built for the open internet and based on the Unified ID 2.0 solution. It leverages encrypted email data to provide a privacy-conscious, secure, and accurate identity standard designed to meet market requirements in Europe and the UK.
9+
10+
EUID relies on user consent before an ID can be added to the bid stream. Consent can be gathered by SSO providers who have integrated against the EUID framework, or through a publisher's own login and consent mechanism.
11+
12+
To add EUID to your Prebid.js package, run the following:
13+
14+
{: .alert.alert-info :}
15+
gulp build --modules=euidIdSystem
16+
17+
## European Unified ID Registration
18+
19+
European Unified ID is still in the pre-release phase. To obtain an EUID publisher account, get in touch with your UID2 account contact.
20+
21+
Each publisher’s privacy policy should take European Unified ID into account.
22+
23+
## European Unified ID Tokens
24+
25+
EUID tokens are generated on the server side by making an API call to an EUID operator using details provided when you receive EUID publisher access. This API returns a JSON data structure with multiple values, including an advertising token and a refresh token. For full functionality, provide the entire object in one of these ways:
26+
27+
- JSON-encoded as a cookie.
28+
- Included in the configuration object.
29+
30+
For examples, see [European Unified ID Examples](#european-unified-id-examples).
31+
32+
The following sample is fictitious, but shows what the token response object looks like:
33+
34+
```javascript
35+
{
36+
"advertising_token": "...",
37+
"refresh_token": "...",
38+
"identity_expires": 1633643601000,
39+
"refresh_from": 1633643001000,
40+
"refresh_expires": 1636322000000,
41+
"refresh_response_key": "wR5t6HKMfJ2r4J7fEGX9Gw=="
42+
}
43+
```
44+
45+
When this full data structure is provided, the module automatically refreshes the token periodically, as long as the refresh token hasn't expired.
46+
47+
## Client Refresh mode
48+
49+
This is the recommended mode for most scenarios. In this mode, the full response body from the EUID Token Generate or Token Refresh endpoint must be provided to the module. As long as the refresh token remains valid, the module will refresh the advertising token as needed.
50+
51+
To configure the module to use this mode, you must **either**:
52+
53+
1. Set `params.euidCookie` to the name of the cookie which contains the response body as a JSON string, **or**
54+
2. Set `params.euidToken` to the response body as a JavaScript object.
55+
56+
### Client refresh cookie example
57+
58+
In this example, the cookie is called `euid_pub_cookie`.
59+
60+
Cookie:
61+
62+
```javascript
63+
euid_pub_cookie={"advertising_token":"...advertising token...","refresh_token":"...refresh token...","identity_expires":1684741472161,"refresh_from":1684741425653,"refresh_expires":1684784643668,"refresh_response_key":"...response key..."}
64+
```
65+
66+
Configuration:
67+
68+
```javascript
69+
pbjs.setConfig({
70+
userSync: {
71+
userIds: [{
72+
name: 'euid',
73+
params: {
74+
euidCookie: 'euid_pub_cookie'
75+
}
76+
}]
77+
}
78+
});
79+
```
80+
81+
### Client refresh euidToken example
82+
83+
Configuration:
84+
85+
```javascript
86+
pbjs.setConfig({
87+
userSync: {
88+
userIds: [{
89+
name: 'euid',
90+
params: {
91+
euidToken: {
92+
'advertising_token': '...advertising token...',
93+
'refresh_token': '...refresh token...',
94+
// etc. - see the Sample Token below for contents of this object
95+
}
96+
}
97+
}]
98+
}
99+
});
100+
```
101+
102+
## European Unified ID Server-Only Mode
103+
104+
There is a server-only mode where the value of the advertising token can be provided either directly (see the `value` parameter in the [European Unified ID Configuration](#european-unified-id-configuration) section) or via a cookie. In this mode, no attempt is made to automatically refresh the token.
105+
106+
### Cookie-based server-only mode
107+
108+
To use the cookie-based server-only mode, set a cookie named `__euid_advertising_token` to the value of the advertising token only, as shown in this fictitious example:
109+
110+
Cookie: `__euid_advertising_token=eb33b0cb8d354722b9c01a31d4064888`
111+
112+
Configuration:
113+
114+
```javascript
115+
pbjs.setConfig({
116+
userSync: {
117+
userIds: [{
118+
name: 'euid'
119+
}]
120+
}
121+
});
122+
```
123+
124+
### Configuration-based server-only mode
125+
126+
To use the configuration-based server-only mode, set the value directly in the configuration of the module, as shown in this fictitious example:
127+
128+
```javascript
129+
pbjs.setConfig({
130+
userSync: {
131+
userIds: [{
132+
name: 'euid'
133+
value: {
134+
'euid': {
135+
'id': 'eb33b0cb8d354722b9c01a31d4064888'
136+
}
137+
}
138+
}]
139+
}
140+
});
141+
```
142+
143+
## European Unified ID Configuration
144+
145+
The following parameters apply only to the European Unified ID module integration.
146+
147+
{: .table .table-bordered .table-striped }
148+
| Param under userSync.userIds[] | Scope | Type | Description | Example |
149+
| --- | --- | --- | --- | --- |
150+
| name | Required | String | ID value for the EUID module - `"euid"` | `"euid"` |
151+
| value | Optional, Server only | Object | An object containing the value for the advertising token. | See the example above. |
152+
| params.euidToken | Optional, Client refresh | Object | The initial EUID token. This should be `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See the sample token above. |
153+
| params.euidCookie | Optional, Client refresh | String | The name of a cookie which holds the initial EUID token, set by the server. The cookie should contain JSON in the same format as the euidToken param. **If euidToken is supplied, this param is ignored.** | See the sample token above. |
154+
| params.euidApiBase | Optional, Client refresh | String | Overrides the default EUID API endpoint. | `"https://prod.euid.eu"` _(default)_|
155+
| params.storage | Optional, Client refresh | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `localStorage` _(default)_ |
156+
157+
## European Unified ID Examples
158+
159+
In the following example, the publisher has set a cookie called `euid_identity` containing the EUID token generation response object:
160+
161+
```javascript
162+
pbjs.setConfig({
163+
userSync: {
164+
userIds: [{
165+
name: 'euid',
166+
params: {
167+
euidServerCookie: 'euid_identity'
168+
}
169+
}]
170+
}
171+
});
172+
```
173+
174+
In the following example, the publisher has retrieved a server-generated EUID response, and it is currently stored in the JavaScript variable `euidIdentity`:
175+
176+
```javascript
177+
pbjs.setConfig({
178+
userSync: {
179+
userIds: [{
180+
name: 'euid',
181+
params: {
182+
euidToken: euidIdentity
183+
}
184+
}]
185+
}
186+
});
187+
```

‎dev-docs/modules/userid-submodules/unified2.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,8 @@ The following parameters apply only to the Unified ID 2.0 module integration.
6666
| params.uid2Token | Optional | Object | The initial UID2 token. This should be the `body` element of the decrypted response from a call to the `/token/generate` or `/token/refresh` endpoint. | See the sample token above. |
6767
| params.uid2ServerCookie | Optional | String | The name of a cookie that holds the initial UID2 token, set by the server. The cookie should contain JSON in the same format as the alternative uid2Token param. **If uid2Token is supplied, this param is ignored.** | See the sample token above. |
6868
| params.uid2ApiBase | Optional | String | Overrides the default UID2 API endpoint. | `https://prod.uidapi.com` _(default)_ |
69-
| value | Not recommended | Object | Used only if the page has a separate mechanism for storing the UID 2.0 ID. The value is an object containing the values to be sent to the adapters. In this scenario, no URL is called and nothing is added to local storage, and the tokens are **not** automatically refreshed. | `{"uid2": { "id": "eb33b0cb-8d35-4722-b9c0-1a31d4064888"}}` |
69+
| value | Optional | Object | Used only if the page has a separate mechanism for storing the UID 2.0 ID. The value is an object containing the values to be sent to the adapters. In this scenario, no URL is called and nothing is added to local storage, and the tokens are **not** automatically refreshed. | `{"uid2": { "id": "eb33b0cb-8d35-4722-b9c0-1a31d4064888"}}` |
70+
| params.storage | Optional, Client refresh | String | Specify whether to use `cookie` or `localStorage` for module-internal storage. It is recommended to not provide this and allow the module to use the default. | `localStorage` _(default)_ |
7071

7172
## Unified ID 2.0 Examples
7273

0 commit comments

Comments
 (0)