Skip to content

update API examples to v2 #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 18 commits into from
Sep 16, 2022
Merged

update API examples to v2 #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
c4055c0
update v2 example for server_only
jon8787 Sep 8, 2022
0f8c71c
check nonce in request matches nonce in response
jon8787 Sep 9, 2022
06610c9
ensure we can still refresh tokens that were generated with V1 or ear…
jon8787 Sep 12, 2022
ccb6d7a
upgrade UID2 SDK Integration Example to v2
jon8787 Sep 12, 2022
624b7d4
change crypto library from https://nodejs.org/api/webcrypto.html#web-…
jon8787 Sep 13, 2022
ac8dcd5
update links and docs for v2
jon8787 Sep 13, 2022
d868018
update links to Operator
jon8787 Sep 14, 2022
27bfd50
update links to Operator
jon8787 Sep 14, 2022
b2a9760
clarify that SESSION_KEY can be any string
jon8787 Sep 14, 2022
9e56ea4
Update README.md
elenaTTD Sep 15, 2022
23cfa4b
Update README.md
elenaTTD Sep 16, 2022
8c89df6
Misc. minor format and grammar updates
elenaTTD Sep 16, 2022
dab9575
Misc. minor format updates
elenaTTD Sep 16, 2022
2670afb
Update README.md
elenaTTD Sep 16, 2022
21bc6c5
minor wording update in a cross-ref
elenaTTD Sep 16, 2022
d4be07c
Update README.md
elenaTTD Sep 16, 2022
c3702a9
fix tab text on the server-only example
jon8787 Sep 16, 2022
753ca91
Merge branch 'main' into jon-update-examples-to-v2
elenaTTD Sep 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,16 @@
The [UID2 framework](https://github.com/UnifiedID2/uid2docs/tree/main) enables publishers to integrate in either of the following ways:

- 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).
- Via a server-only or custom integration, by building a direct integration without using the UID2 SDK.
- Via the server-only (custom) integration workflow, by building a direct integration without using the UID2 SDK.

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.

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

| Example Application | Example Description | Primary Audience | Example Documentation| Integration Guide |
| :--- | :--- | :--- | :--- | :--- |
| [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) |
| [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) |
| [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) |
| [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) |

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:
- Implement user login and logout.
Expand Down
40 changes: 21 additions & 19 deletions publisher/server_only/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Server-Only UID2 Integration Example

[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).
[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).

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).
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).

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

Expand All @@ -13,19 +13,21 @@ The easiest way to try the example is to use the following docker build command:
```
docker build . -t uid2-publisher-server
docker run -it --rm -p 3000:3000 \
-e UID2_BASE_URL="https://integ.uidapi.com" \
-e UID2_API_KEY="<your-integ-API-key>" \
-e SESSION_KEY="my-session-key" \
-e UID2_BASE_URL="https://operator-integ.uidapi.com" \
-e UID2_API_KEY="{INTEG_API_KEY}" \
-e UID2_CLIENT_SECRET="{CLIENT_KEY}" \
-e SESSION_KEY="{SESSION_KEY}" \
uid2-publisher-server
```

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

| Parameter | Data Type | Description |
| :--- | :--- | :--- |
| `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` |
| `UID2_API_KEY` | string | Your UID2 authentication key for the UID2 service specified in `UID2_BASE_URL`. |
| `SESSION_KEY` | string | The key to the encryption session data stored in application's session cookie. |
| Parameter | Data Type | Description |
|:---------------------|:----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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). |
| `UID2_API_KEY` | string | Your UID2 authentication key for the UID2 service specified in `UID2_BASE_URL`. | |
| `UID2_CLIENT_SECRET` | string | Your UID2 client secret for the UID2 service specified in `UID2_BASE_URL`. | |
| `SESSION_KEY` | string | The key to the encryption session data stored in the application session cookie. This can be any arbitrary string. | |

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

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

## Test the Example Application

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).
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).

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.

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

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

| Step | Description | Comments |
| :---: | :--- | :--- |
| 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. |
| 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. |
| | 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. |
| 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. |
| 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.|
| 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. |
| Step | Description | Comments |
|:----:|:------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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. |
| 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. |
| | 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. |
| 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. |
| 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. |
| 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. |
Loading