Tech content updates to the example app docs.

README.md

@@ -0,0 +1,20 @@
+# UID2 Integration Examples
+
+If you are a content publisher interested in generating identity tokens utilizing UID2 for the RTB bid stream, you can build and run either of the two example applications to see how you can use the UID2 services and which integration fits your needs best.
+
+Both examples illustrate the basic steps that you need to consider for your integration. For example, you need to decide how to implement user login and logout, how to manage UID2 identity information and use it for targeted advertising, how to refresh tokens, deal with missing identities, and handle user opt-outs.
+
+The following table summarizes both examples. 
+
+| Example Documentation | Primary Audience | Example Description | Integration Steps |
+| :--- | :--- | :--- | :--- |
+| [UID2 SDK Integration Example](./publisher/standard/README.md) | Publishers with web assets | Demonstrates how to use the UID2 services with the [Client-Side Identity JavaScript SDK](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md) (also known as the UID2 SDK) to implement the standard UID2 integration workflow.  | [UID2 SDK Integration Guide](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/guides/publisher-client-side.md) |
+| [Server-Only UID2 Integration Example](./publisher/server_only/README.md) | App developers and CTV broadcasters | 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.  | [Server-Only UID2 Integration Guide](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/guides/custom-publisher-integration.md) |
+
+The documentation for each example includes instructions on how to build and run the application and suggests steps that you may take to test and explore it. Each step is annotated with comments that explain what takes place on the backend and how the UID2 services work.
+
+
+
+
+
+

publisher/server_only/README.md

@@ -0,0 +1,60 @@
+# Server-Only UID2 Integration Example
+
+This example 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).
+
+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).
+
+>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.
+
+## Build and Run the Example Application
+
+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" \
+    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. |
+
+After you see output similar to the following, the example application is up and running.
+
+```
+> uid2-publisher@1.0.0 start /usr/src/app
+> node server.js
+
+Example app listening at http://localhost:3000
+```
+
+If needed, to close the application, terminate the docker container or use the `Ctrl+C` keyboard shortcut.
+
+## 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 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.
+
+Submitting the login form simulates logging in to a publisher's application in the real world. Normally the login
+would require checking the user's secure credentials (for example, a password), but for demonstration purposes this
+step is omitted, and the login process focuses on integration with the UID2 services instead.
+
+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.  |

publisher/standard/README.md

@@ -1,15 +1,15 @@
-# UID2 Publisher Integration Example (Standard)
+# UID2 SDK Integration Example
 
-This example demonstrates how a content publisher can work with UID2 services and UID2 JavaScript SDK
-to implement the standard UID2 publisher integration workflow (XREF).
+This example demonstrates how a content publisher can use the UID2 services and the [Client-Side Identity JavaScript SDK](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md) (also known as the UID2 SDK) to implement the [standard UID2 integration workflow](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/guides/publisher-client-side.md).
 
-While the server side of the example application is implemented in JavaScript using node.js, it is not
-a requirement. The server side can be implemented using any technology of your choice, and you can use
-the example application as a reference of the functionality that needs to be implemented.
+For an example application without using the UID2 SDK, see [Server-Only UID2 Integration Example](../server_only/README.md).
 
-## Building and Running the Example
+>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.
 
-The easiest way to trying the example is to rely on docker:
+## Build and Run the Example Application
+
+The easiest way to try the example is to use the following docker build command:
 
 ```
 docker build . -t uid2-publisher-standard
@@ -19,52 +19,36 @@ docker run -it --rm -p 3000:3000 \
     uid2-publisher-standard
 ```
 
-The following parameters must be specified in form of environment variables to start the application:
+The following table lists the environment variables that you must specify to start the application.
 
-| Setting | Description |
-| :--- | :--- |
-| `UID2_BASE_URL` | Base URL of the UID2 services. For example, production uid2 services are available on `https://prod.uidapi.com` |
-| `UID2_API_KEY` | Your UID2 authentication key for the UID2 service above. |
+| 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`. |
 
-Once the application starts up successfully, you should see output similar to below:
+After you see output similar to the following, the example application is up and running.
 
 ```
 > uid2-publisher@1.0.0 start /usr/src/app
 > node server.js
 
 Example app listening at http://localhost:3000
 ```
+If needed, to close the application, terminate the docker container or use the `Ctrl+C` keyboard shortcut.
 
-You should then be able to navigate to the application's main page in your browser: `http://localhost:3000`.
-
-You can quit the application by terminating the docker container or by hitting `Ctrl+C`.
-
-## Key Points
-
-Example follows the steps of the UID2 publisher integration workflow (XREF).
-
-The index page provides a login form for the user to complete the UID2 login process. A real application
-would need to display information for user to express their consent to targeted advertising.
-
-Once the user supplies their email address and hit the `Login` button, they will hit the `/login` endpoint (XREF to server.js).
-The login process on the server side will call `GET /token/generate` (XREF) and process the received response.
-If the response indicates success, the returned identity (`body` properity of the response JSON) will be passed
-to the `login` view (XREF to file) for rendering client side JavaScript.
+## Test the Example Application
 
-The client side JavaScript calls the UID2 client SDK `init()` function passing it the identity from `/token/generate`.
-If the identity is valid, it will be stored in a first party UID2 cookie for use on subsequent page loads.
+The example application illustrates the steps documented in the [UID2 SDK Integration Guide](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/guides/publisher-client-side.md). For an overview of the high-level workflow for establishing UID2 identity, API reference, and explanation of the UID2 cookie format, see [Client-Side Identity JavaScript SDK](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md).
 
-Next the user can navigate back to the main (index) page. The page view (XREF to index view) calls the `init()`
-function this time without passing an explicit identity, requesting for it to be loaded from the first party cookie
-instead. When the UID2 finishes initialising, it will invoke the passed callback function `onUid2IdentityUpdated()`.
-The callback will update the page elements with the state of UID2 identity: it is the place where one should place
-their logic for initiating targeted advertising.
+The following table outlines and annotates the steps you may take to test and explore the example application.
 
-As the user keeps the page open or as they keep refreshing it over time, the UID2 JavaScript SDK will be validating
-whether the advertising token is up-to-date and refresh it automatically when needed. If the refresh succeeds, or
-if the user opts out, or the refresh token expires, the callback function will be invoked and the UI elements
-will be updated with the current state of UID2 identity.
+| Step | Description | Comments |
+| :---: | :--- | :--- |
+| 1 | In your browser, navigate to the application main page at `http://localhost:3000`. | The displayed main ([index](views/index.html)) page of the example application provides a login form 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 | In the text field at the bottom, 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. |
+|   | A confirmation message appears with 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 `GET /token/generate` response. It has been passed to the `login` [view](views/login.html) for rendering client-side JavaScript. Next, the identity information is passed to the [UID2 SDK `init()` function](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md#initopts-object-void). If the identity is valid, the SDK stores it in a [first-party UID2 cookie](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md#uid2-cookie-format) for use on subsequent page loads. |
+| 3 | Click the **Back to the main page** link. | On the updated application main page, note the newly populated **UID2 Advertising Token** value. The [page view](views/index.html) calls the [init() function](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md#initopts-object-void) again, but this time without passing an explicit identity. Instead, the identity is loaded from the first-party cookie. |
+| 4  | (Optional) Right-click the main page to inspect the source code. | When the UID2 SDK initialization is complete, the SDK invokes the passed [callback function](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md#callback-function) (`onUid2IdentityUpdated()` in this example).</br>IMPORTANT: The callback updates the page elements with the state of UID2 identity: this is the place where you should define your logic for initiating targeted advertising. |
+| 5 | Keep the application main page open or refresh it after awhile and note the UID2 identity state, updated counter, and login information values. | In the background, the UID2 SDK continuously validates whether the advertising token is up-to-date and refreshes it automatically when needed. If the refresh succeeds, the user opts out, or the refresh token expires, the callback function is invoked and the UI elements are updated with the current state of the UID2 identity. For details, see [Workflow States and Transitions](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md#workflow-states-and-transitions) and [Background Token Auto-Refresh](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md#background-token-auto-refresh). |
+| 6 | To exit the application, click **Log Out**. | This calls the [UID2 SDK `disconnect()` function](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md#disconnect-void), which clears the UID2 session and the first-party cookie. This call also makes the [UID2 SDK `isLoginRequired()` function](https://github.com/UnifiedID2/uid2docs/blob/main/api/v1/sdks/client-side-identity-v1.md#isloginrequired-boolean) return `true`, which presents the user with the login form again.<br/> NOTE: The page displays the **Log Out** button as long as the user identity is valid and refreshable.  |
 
-While the user identity is valid (refreshable), the page will display a logout button. User clicking the button
-would lead to UID2 SDK `disconnect()` function being called which would clear the UID2 session and the first party
-cookie. User will be presented with the login form again.