Skip to content

Commit ba28e4d

Browse files
vlochnervlochner
authored
Merge pull request #3 from UnifiedID2/jon-update-examples-to-v2
update API examples to v2
2 parents a19deac + 753ca91 commit ba28e4d

File tree

9 files changed

+297
-90
lines changed

9 files changed

+297
-90
lines changed

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,16 @@
33
The [UID2 framework](https://github.com/UnifiedID2/uid2docs/tree/main) enables publishers to integrate in either of the following ways:
44

55
- Via the standard integration workflow, using the [Client-Side Identity JavaScript SDK](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/sdks/client-side-identity.md) (also known as the UID2 SDK).
6-
- Via a server-only or custom integration, by building a direct integration without using the UID2 SDK.
6+
- Via the server-only (custom) integration workflow, by building a direct integration without using the UID2 SDK.
77

88
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.
99

1010
The following table summarizes both examples and provides links to the example applications, their documentation, and the respective step-by-step integration guides.
1111

1212
| Example Application | Example Description | Primary Audience | Example Documentation| Integration Guide |
1313
| :--- | :--- | :--- | :--- | :--- |
14-
| [UID2 SDK Integration Example](https://example-jssdk-integ.uidapi.com/) | Demonstrates how to use the UID2 services with the [UID2 SDK](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md) to implement the standard UID2 integration workflow. | Publishers with web assets | [UID2 SDK Integration Example](./publisher/standard/README.md) | [UID2 SDK Integration Guide](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/guides/publisher-client-side.md) |
15-
| [Server-Only UID2 Integration Example](https://example-srvonly-integ.uidapi.com/login) |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 Example](./publisher/server_only/README.md) | [Server-Only UID2 Integration Guide](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/guides/custom-publisher-integration.md) |
14+
| [UID2 SDK Integration Example](https://example-jssdk-integ.uidapi.com/) | Demonstrates how to use the UID2 services with the [UID2 SDK](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/sdks/client-side-identity.md) to implement the standard UID2 integration workflow. | Publishers with web assets | [UID2 SDK Integration Example](./publisher/standard/README.md) | [UID2 SDK Integration Guide](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/publisher-client-side.md) |
15+
| [Server-Only UID2 Integration Example](https://example-srvonly-integ.uidapi.com/login) |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 Example](./publisher/server_only/README.md) | [Server-Only UID2 Integration Guide](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/custom-publisher-integration.md) |
1616

1717
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:
1818
- Implement user login and logout.

‎publisher/server_only/README.md‎

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Server-Only UID2 Integration Example
22

3-
[This example](https://example-srvonly-integ.uidapi.com/) demonstrates how a content publisher can use the UID2 services to implement the [custom UID2 integration workflow](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/guides/custom-publisher-integration.md).
3+
[This example](https://example-srvonly-integ.uidapi.com/) demonstrates how a content publisher can use the [UID2 services](https://github.com/UnifiedID2/uid2docs/tree/main) to implement the [custom UID2 integration workflow](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/custom-publisher-integration.md).
44

5-
For an example application using the [Client-Side Identity JavaScript SDK](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md), see [UID2 SDK Integration Example](../standard/README.md).
5+
For an example application using the [Client-Side Identity JavaScript SDK](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/sdks/client-side-identity.md), see [UID2 SDK Integration Example](../standard/README.md).
66

77
>NOTE: While the server side of the example application is implemented in JavaScript using node.js, it is not a requirement. You can use any technology of your choice and refer to the example application for illustration of the functionality that needs to be implemented.
88
@@ -13,19 +13,21 @@ The easiest way to try the example is to use the following docker build command:
1313
```
1414
docker build . -t uid2-publisher-server
1515
docker run -it --rm -p 3000:3000 \
16-
-e UID2_BASE_URL="https://integ.uidapi.com" \
17-
-e UID2_API_KEY="<your-integ-API-key>" \
18-
-e SESSION_KEY="my-session-key" \
16+
-e UID2_BASE_URL="https://operator-integ.uidapi.com" \
17+
-e UID2_API_KEY="{INTEG_API_KEY}" \
18+
-e UID2_CLIENT_SECRET="{CLIENT_KEY}" \
19+
-e SESSION_KEY="{SESSION_KEY}" \
1920
uid2-publisher-server
2021
```
2122

2223
The following table lists the environment variables that you must specify to start the application.
2324

24-
| Parameter | Data Type | Description |
25-
| :--- | :--- | :--- |
26-
| `UID2_BASE_URL` | string | The base URL of the UID2 service. For example:</br>Testing environment: `https://integ.uidapi.com`<br/>Production environment: `https://prod.uidapi.com` |
27-
| `UID2_API_KEY` | string | Your UID2 authentication key for the UID2 service specified in `UID2_BASE_URL`. |
28-
| `SESSION_KEY` | string | The key to the encryption session data stored in application's session cookie. |
25+
| Parameter | Data Type | Description |
26+
|:---------------------|:----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
27+
| `UID2_BASE_URL` | string | The base URL of the UID2 service. For example:</br>Testing environment: `https://operator-integ.uidapi.com`<br/>For details, see [Environments](https://github.com/UnifiedID2/uid2docs/tree/main/api/v2#environments). |
28+
| `UID2_API_KEY` | string | Your UID2 authentication key for the UID2 service specified in `UID2_BASE_URL`. | |
29+
| `UID2_CLIENT_SECRET` | string | Your UID2 client secret for the UID2 service specified in `UID2_BASE_URL`. | |
30+
| `SESSION_KEY` | string | The key to the encryption session data stored in the application session cookie. This can be any arbitrary string. | |
2931

3032
After you see output similar to the following, the example application is up and running.
3133

@@ -40,7 +42,7 @@ If needed, to close the application, terminate the docker container or use the `
4042

4143
## Test the Example Application
4244

43-
The example application illustrates the steps documented in the [Server-Only UID2 Integration Guide](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/guides/custom-publisher-integration.md).
45+
The example application illustrates the steps documented in the [Server-Only UID2 Integration Guide](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/custom-publisher-integration.md).
4446

4547
The application provides three main pages: index (main), example content 1, and example content 2. Access to these pages is possible only after the user completes the login process. If the user is not logged in, they will be redirected to the login page.
4648

@@ -50,11 +52,11 @@ step is omitted, and the login process focuses on integration with the UID2 serv
5052

5153
The following table outlines and annotates the steps you may take to test and explore the example application.
5254

53-
| Step | Description | Comments |
54-
| :---: | :--- | :--- |
55-
| 1 | In your browser, navigate to the application main page at `http://localhost:3000`. | The displayed main (index) page of the example application provides a [login form](views/login.html) for the user to complete the UID2 login process.</br>IMPORTANT: A real-life application must also display a form for the user to express their consent to targeted advertising. |
56-
| 2 | Enter the user email address that you want to use for testing and click **Log In**. | This is a call to the `/login` endpoint ([server.js](server.js)). The login initiated on the server side then calls the [GET /token/generate](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/endpoints/get-token-generate.md#response-format) endpoint and processes the received response. |
57-
| | The main page updates to display links to the two pages with protected content and the established UID2 identity information. | The displayed identity information is the `body` property of the [JSON response payload](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/endpoints/get-token-generate.md#response-format) from the successful `GET /token/generate` response. If the response is successful, the returned identity is saved to a session cookie (a real-world application would use a different way to store session data) and the protected index page is rendered. |
58-
| 3 | Click a content page. | When the user requests the index or content pages, the server reads the user session and extracts the current UID2 identity ([server.js](server.js)). The `advertising_token` on the identity can be used for targeted advertising. |
59-
| 4 | Click the **Back to the main page** link. | Note that the identity contains several timestamps that determine when the advertising token becomes invalid (`identity_expires`) and when the server should attempt to refresh it (`refresh_from`). Every time a protected page is requested, the `verifyIdentity` function ([server.js](server.js)) calls [GET /token/refresh](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/endpoints/get-token-refresh.md) as needed.<br/>The user is automatically logged out in the following cases:<br/>- If the identity expires without being refreshed and refresh attempt fails.<br/>- If the refresh token expires.<br/>- If the refresh attempt indicates that the user has opted out.|
60-
| 5 | To exit the application, click **Log Out**. | This calls the `/logout` endpoint on the server ([server.js](server.js)), which clears the UID2 session and the first-party cookie and presents the user with the login form again.<br/> NOTE: The page displays the **Log Out** button as long as the user is logged it. |
55+
| Step | Description | Comments |
56+
|:----:|:------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
57+
| 1 | In your browser, navigate to the application main page at `http://localhost:3000`. | The displayed main (index) page of the example application provides a [login form](views/login.html) for the user to complete the UID2 login process.</br>IMPORTANT: A real-life application must also display a form for the user to express their consent to targeted advertising. |
58+
| 2 | Enter the user email address that you want to use for testing and click **Log In**. | This is a call to the `/login` endpoint ([server.js](server.js)). The login initiated on the server side then calls the [POST /token/generate](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-generate.md#decrypted-json-response-format) endpoint and processes the received response. |
59+
| | The main page is updated to display links to the two pages with protected content and the established UID2 identity information. | The displayed identity information is the `body` property of the [JSON response payload](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-generate.md#decrypted-json-response-format) from the successful `POST /token/generate` response. If the response is successful, the returned identity is saved to a session cookie (a real-world application would use a different way to store session data) and the protected index page is rendered. |
60+
| 3 | Click either of the two sample content pages. | When the user requests the index or content pages, the server reads the user session and extracts the current UID2 identity ([server.js](server.js)). The `advertising_token` on the identity can be used for targeted advertising. |
61+
| 4 | Click the **Back to the main page** link. | Note that the identity contains several timestamps that determine when the advertising token becomes invalid (`identity_expires`) and when the server should attempt to refresh it (`refresh_from`). Every time a protected page is requested, the `verifyIdentity` function ([server.js](server.js)) calls [POST /token/refresh](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-refresh.md) as needed.<br/>The user is automatically logged out in the following cases:<br/>- If the identity expires without being refreshed and refresh attempt fails.<br/>- If the refresh token expires.<br/>- If the refresh attempt indicates that the user has opted out. |
62+
| 5 | To exit the application, click **Log Out**. | This calls the `/logout` endpoint on the server ([server.js](server.js)), which clears the UID2 session and the first-party cookie and presents the user with the login form again.<br/> NOTE: The page displays the **Log Out** button as long as the user is logged it. |

0 commit comments

Comments
 (0)