copy edit on readme + update doc URLs (#21)

* copy edit on readme + update doc URLs

* typo fix

Author: genwhittTTD

README.md

@@ -1,27 +1,28 @@
-# UID2 Java SDK
+# UID2 SDK for Java
 
 The UID 2 Project is subject to the IAB Tech Lab Intellectual Property Rights (IPR) Policy, and is managed by the IAB Tech Lab Addressability Working Group and [Privacy & Rearc Commit Group](https://iabtechlab.com/working-groups/privacy-rearc-commit-group/). Please review the [governance rules](https://github.com/IABTechLab/uid2-core/blob/master/Software%20Development%20and%20Release%20Procedures.md).
 
 This document includes:
-* [Who is this SDK for?](#who-is-this-sdk-for)
+* [Who Is this SDK for?](#who-is-this-sdk-for)
 * [Requirements](#requirements)
-* [Installation](#installation)
+* [Install](#install)
 * [Usage for DSPs](#usage-for-dsps)
 * [Usage for Publishers](#usage-for-publishers)
    - [Basic Usage](#basic-usage)
    - [Advanced Usage](#advanced-usage)
-* [## Usage for UID Sharers](#usage-for-uid-sharers)
+* [## Usage for UID2 Sharers](#usage-for-uid2-sharers)
 
-## Who is this SDK for?
-This SDK simplifies integration with UID2 for Publishers, DSPs, and UID Sharers, as described in the [UID2 Integration Guides](https://github.com/IABTechLab/uid2docs/blob/main/api/v2/guides/summary-guides.md). 
+## Who Is this SDK for?
+
+This SDK simplifies integration with UID2 for Publishers, DSPs, and UID Sharers, as described in [UID2 Integration Guides](https://unifiedid.com/docs/category/integration-guides). 
 
 ## Requirements
 
-* This SDK requires Java version 1.8 or later.
+This SDK requires Java version 1.8 or later.
 
-## Installation
+## Install
 
-Add this dependency to your project's POM:
+To install the SDK, add this dependency to your project's `pom.xml` file:
 
 ```
         <dependency>
@@ -38,10 +39,10 @@ For an example of usage for DSPs, see [com.uid2.client.test.IntegrationExamples]
 ## Usage for Publishers
 
 As a publisher, there are two ways to use this SDK: 
-1. [**Basic Usage**](#basic-usage) is for publishers who are happy to use this SDK's HTTP implementation (synchronous [OkHttp](https://square.github.io/okhttp/)).
+1. [**Basic Usage**](#basic-usage) is for publishers who want to use this SDK's HTTP implementation (synchronous [OkHttp](https://square.github.io/okhttp/)).
 2. [**Advanced Usage**](#advanced-usage) is for publishers who prefer to use their own HTTP library. 
 
-For an example application that demonstrates both Basic and Advanced usage, see [uid2-examples](https://github.com/UnifiedID2/uid2-examples/tree/main/publisher/uid2-java-test-site).
+For an example application that demonstrates both Basic and Advanced usage, see [Java UID2 Integration Example](https://github.com/UnifiedID2/uid2-examples/tree/main/publisher/uid2-java-test-site#readme).
 
 ### Basic Usage
 
@@ -57,13 +58,15 @@ If you're using the SDK's HTTP implementation, follow these steps.
 
 #### Standard Integration
 
-If you're using [standard (client and server) integration](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/publisher-client-side.md), follow this step:
+If you're using standard integration (client and server) (see [Client-Side JavaScript SDK Integration Guide](https://unifiedid.com/docs/guides/publisher-client-side)), follow this step:
+
+* Send this identity as a JSON string back to the client (to use in the [identity field](https://unifiedid.com/docs/sdks/client-side-identity#initopts-object-void)) using the following:
 
-* Send this identity as a JSON string back to the client (to use in the [identity field](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/sdks/client-side-identity.md#initopts-object-void)) using: `identity.getJsonString()`
+    `identity.getJsonString()`
 
 #### Server-Only Integration
 
-If you're using [server-only integration](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/custom-publisher-integration.md):
+If you're using server-only integration (see [Publisher Integration Guide, Server-Only (Without SDK)](https://unifiedid.com/docs/guides/custom-publisher-integration)):
 
 1. Store this identity as a JSON string in the user's session, using the `identity.getJsonString()` function.
 2. To use the user's UID2 token, use the `identity.getAdvertisingToken()` function.
@@ -81,37 +84,39 @@ If you're using [server-only integration](https://github.com/UnifiedID2/uid2docs
 
    `TokenRefreshResponse tokenRefreshResponse = publisherUid2Client.refreshToken(identity);`
 
-5. You should then store `tokenRefreshResponse.getIdentityJsonString()` in the user's session. If the user has opted out, this method returns null, indicating that the user's identity should be removed from their session. (Optout can be confirmed via `tokenRefreshResponse.isOptout()`.)
+5. Store `tokenRefreshResponse.getIdentityJsonString()` in the user's session. If the user has opted out, this method returns null, indicating that the user's identity should be removed from the session. To confirm optout, you can use the `tokenRefreshResponse.isOptout()` function.
 
 ### Advanced Usage
 
 1. Create an instance of PublisherUid2Helper as an instance variable:
 
     `private final PublisherUid2Helper publisherUid2Helper = new PublisherUid2Helper(UID2_SECRET_KEY);`
-2. When the user has authenticated, and has authorized the creation of a UID2, call a function that takes the user's email address or phone number as input and creates a secure request data envelope. See [Encrypting requests](https://github.com/IABTechLab/uid2docs/blob/main/api/v2/getting-started/gs-encryption-decryption.md#encrypting-requests). The following example uses an email address:
+2. When the user has authenticated, and has authorized the creation of a UID2, call a function that takes the user's email address or phone number as input and creates a secure request data envelope. See [Encrypting requests](https://unifiedid.com/docs/getting-started/gs-encryption-decryption#encrypting-requests). The following example uses an email address:
 
     `EnvelopeV2 envelope = publisherUid2Helper.createEnvelopeForTokenGenerateRequest(TokenGenerateInput.fromEmail(emailAddress));`
-3. Using an HTTP client library of your choice, post this envelope to the [/v2/token/generate](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-generate.md) endpoint, including headers and body:
+3. Using an HTTP client library of your choice, post this envelope to the [POST token/generate](https://unifiedid.com/docs/endpoints/post-token-generate) endpoint, including headers and body:
    1. Headers: Depending on your HTTP library, this might look something like the following:  
 
       `.putHeader("Authorization", "Bearer " + UID2_API_KEY)`  
       `.putHeader("X-UID2-Client-Version", PublisherUid2Helper.getVersionHeader())`
    2. Body: `envelope.getEnvelope()`
-4. If the HTTP response status code is _not_ 200, see [Response Status Codes](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-generate.md#response-status-codes) to determine next steps. Otherwise, convert the UID2 identity response content into an `IdentityTokens` object:
+4. If the HTTP response status code is _not_ 200, see [Response Status Codes](https://unifiedid.com/docs/endpoints/post-token-generate#response-status-codes) to determine next steps. Otherwise, convert the UID2 identity response content into an `IdentityTokens` object:
 
    `IdentityTokens identity = publisherUid2Helper.createIdentityfromTokenGenerateResponse({response body}, envelope);`
 
 #### Standard Integration
 
-If you're using [standard (client and server) integration](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/publisher-client-side.md):
+If you're using standard integration (client and server) (see [Client-Side JavaScript SDK Integration Guide](https://unifiedid.com/docs/guides/publisher-client-side)):
+
+* Send this identity as a JSON string back to the client (to use in the [identity field](https://unifiedid.com/docs/sdks/client-side-identity#initopts-object-void)) using the following:
 
-1. Send this identity as a JSON string back to the client (to use in the [identity field](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/sdks/client-side-identity.md#initopts-object-void)) using: `identity.getJsonString()`
+    `identity.getJsonString()`
 
 #### Server-Only Integration
+If you're using server-only integration (see [Publisher Integration Guide, Server-Only (Without SDK)](https://unifiedid.com/docs/guides/custom-publisher-integration)):
 
-If you're using [server-only integration](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/custom-publisher-integration.md):
-1. Store this identity as a JSON string in the user's session, using: `identity.getJsonString()`
-2. To use the user's UID2 token, use `identity.getAdvertisingToken()`
+1. Store this identity as a JSON string in the user's session, using: `identity.getJsonString()`.
+2. To use the user's UID2 token, use `identity.getAdvertisingToken()`.
 
 3. When the user accesses another page, or on a timer, determine whether a refresh is needed:
    1. Retrieve the identity JSON string from the user's session, and then call the following function that generates an `IdentityTokens` object:
@@ -123,7 +128,7 @@ If you're using [server-only integration](https://github.com/UnifiedID2/uid2docs
    3. Determine if a refresh is needed:
 
       `if (identity.isDueForRefresh()) {..}`
-4. If a refresh is needed, call the [POST token/refresh](https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-refresh.md) endpoint, with:
+4. If a refresh is needed, call the [POST token/refresh](https://unifiedid.com/docs/endpoints/post-token-refresh) endpoint, with:
    1. Headers (depending on your HTTP library, this might look something like):
 
       `.putHeader("Authorization", "Bearer " + UID2_API_KEY)`  
@@ -132,11 +137,11 @@ If you're using [server-only integration](https://github.com/UnifiedID2/uid2docs
 5. If the refresh HTTP response status code is 200:
 
    `TokenRefreshResponse tokenRefreshResponse = PublisherUid2Helper.createTokenRefreshResponse({response body}, identity);`
-6. You should then store `tokenRefreshResponse.getIdentityJsonString()` in the user's session. If the user has opted out, this method returns null, indicating that the user's identity should be removed from their session (you can confirm user opt-out with the `tokenRefreshResponse.isOptout()` function).
+6. Store `tokenRefreshResponse.getIdentityJsonString()` in the user's session. If the user has opted out, this method returns null, indicating that the user's identity should be removed from the session. To confirm optout, you can use the `tokenRefreshResponse.isOptout()` function.
 
-## Usage for UID Sharers
+## Usage for UID2 Sharers
 
-A UID2 Sharer is a participant that wants to share UID2s or EUIDs with another participant. Raw UIDs must be encrypted into UID tokens before sending them to another participant. For an example of usage, see [com.uid2.client.test.IntegrationExamples](https://github.com/IABTechLab/uid2-client-java/blob/master/src/test/java/com/uid2/client/test/IntegrationExamples.java) (runSharingExample method).
+A UID2 sharer is a participant that wants to share UID2s or EUIDs with another participant. Raw UID2s must be encrypted into UID2 tokens before sending them to another participant. For an example of usage, see [com.uid2.client.test.IntegrationExamples](https://github.com/IABTechLab/uid2-client-java/blob/master/src/test/java/com/uid2/client/test/IntegrationExamples.java) (runSharingExample method).
 
 1. Use UID2ClientFactory.create() to create an IUID2Client reference:
 
@@ -148,13 +153,13 @@ A UID2 Sharer is a participant that wants to share UID2s or EUIDs with another p
    1. Call the following:
 
       `EncryptionDataResponse encrypted = client.encrypt(rawUid);`
-   2. If encryption succeeded, send the UID token to the receiver:   
+   2. If encryption succeeded, send the UID2 token to the receiver:   
 
       `if (encrypted.isSuccess()) {` send `encrypted.getEncryptedData()` to receiver`} else {`check `encrypted.getStatus()` for the failure reason} 
 4. Receivers: 
    1. Call the following:
 
       `DecryptionResponse decrypted = client.decrypt(uidToken);`
-   2. If decryption succeeded, use the raw UID:
+   2. If decryption succeeded, use the raw UID2:
 
       `if (decrypted.isSuccess()) {`use `decrypted.getUid() } else {`check `decrypted.getStatus()` for the failure reason `}`

src/main/java/com/uid2/client/EnvelopeV2.java

@@ -8,8 +8,8 @@ public class EnvelopeV2 {
   }
 
   /**
-   * @return an encrypted request envelope which can be used in the POST body of a <a href="https://github.com/UnifiedID2/uid2docs/tree/main/api/v2/endpoints">UID2 endpoint</a>.
-   * See <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/encryption-decryption.md#encrypted-request-envelope">Encrypted Request Envelope</a>
+   * @return an encrypted request envelope which can be used in the POST body of a <a href="https://unifiedid.com/docs/endpoints/summary-endpoints">UID2 endpoint</a>.
+   * See <a href="https://unifiedid.com/docs/getting-started/gs-encryption-decryption#encrypted-request-envelope">Encrypted Request Envelope</a>
    */
   public String getEnvelope() { return envelope; }
   byte[] getNonce() { return nonce;}

src/main/java/com/uid2/client/IdentityTokens.java

@@ -27,7 +27,7 @@ static public IdentityTokens fromJsonString(String jsonString) {
   }
 
   /**
-   * @return whether this identity is due to be refreshed. If true, a call to <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-refresh.md">/token/refresh</a> is due.
+   * @return whether this identity is due to be refreshed. If true, a call to <a href="https://unifiedid.com/docs/endpoints/post-token-refresh">/token/refresh</a> is due.
    */
   public boolean isDueForRefresh() {
     return isDueForRefreshImpl(Instant.now());
@@ -39,13 +39,13 @@ public boolean isDueForRefresh() {
   public String getAdvertisingToken() { return advertisingToken; }
 
   /**
-   * @return the refresh token. This is used as the POST body in <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-refresh.md">/token/refresh</a>
+   * @return the refresh token. This is used as the POST body in <a href="https://unifiedid.com/docs/endpoints/post-token-refresh">/token/refresh</a>
    */
   public String getRefreshToken() { return refreshToken; }
 
   /**
-   * @return the identity as represented by a JSON string. This should be sent back to the client if using <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/publisher-client-side.md">standard integration</a>,
-   * or stored in the user's session if using <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/guides/custom-publisher-integration.md">Server-Only integration.</a>
+   * @return the identity as represented by a JSON string. This should be sent back to the client if using <a href="https://unifiedid.com/docs/guides/publisher-client-side">standard integration</a>,
+   * or stored in the user's session if using <a href="https://unifiedid.com/docs/guides/custom-publisher-integration">Server-Only integration.</a>
    */
   public String getJsonString() {return jsonString;} //this ensures we make newly added fields available, even before this class is updated.
 

src/main/java/com/uid2/client/PublisherUid2Client.java

@@ -7,7 +7,7 @@
 
 public class PublisherUid2Client {
     /**
-     * @param uid2BaseUrl     The <a href="https://github.com/UnifiedID2/uid2docs/tree/main/api/v2#environments">UID2 Base URL</a>
+     * @param uid2BaseUrl     The <a href="https://unifiedid.com/docs/getting-started/gs-environments">UID2 Base URL</a>
      * @param clientApiKey    Your client API key
      * @param base64SecretKey Your client secret key
      */
@@ -18,7 +18,7 @@ public PublisherUid2Client(String uid2BaseUrl, String clientApiKey, String base6
     }
 
     /**
-     * @param tokenGenerateInput represents the input required for <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-generate.md#unencrypted-json-body-parameters">/token/generate</a>
+     * @param tokenGenerateInput represents the input required for <a href="https://unifiedid.com/docs/endpoints/post-token-generate#unencrypted-json-body-parameters">/token/generate</a>
      * @return an IdentityTokens instance
      * @throws Uid2Exception if the response did not contain a "success" status, or the response code was not 200, or there was an error communicating with the provided UID2 Base URL
      */

src/main/java/com/uid2/client/PublisherUid2Helper.java

@@ -23,8 +23,8 @@ public PublisherUid2Helper(String base64SecretKey) {
     }
 
     /**
-     * @param tokenGenerateInput represents the input required for <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-generate.md#unencrypted-json-body-parameters">/token/generate</a>
-     * @return an EnvelopeV2 instance to use in the POST body of <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-generate.md">/token/generate</a>
+     * @param tokenGenerateInput represents the input required for <a href="https://unifiedid.com/docs/endpoints/post-token-generate#unencrypted-json-body-parameters">/token/generate</a>
+     * @return an EnvelopeV2 instance to use in the POST body of <a href="https://unifiedid.com/docs/endpoints/post-token-generate">/token/generate</a>
      */
     public EnvelopeV2 createEnvelopeForTokenGenerateRequest(TokenGenerateInput tokenGenerateInput) {
         final int nonceLength = 8;
@@ -34,7 +34,7 @@ public EnvelopeV2 createEnvelopeForTokenGenerateRequest(TokenGenerateInput token
     }
 
     /**
-     * @param response the response body returned by a call to <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-generate.md">/token/generate</a>
+     * @param response the response body returned by a call to <a href="https://unifiedid.com/docs/endpoints/post-token-generate">/token/generate</a>
      * @param envelope the EnvelopeV2 instance returned by {@link #createEnvelopeForTokenGenerateRequest}
      * @return an IdentityTokens instance
      * @throws Uid2Exception if the response did not contain a "success" status
@@ -51,7 +51,7 @@ public IdentityTokens createIdentityfromTokenGenerateResponse(String response, E
     }
 
     /**
-     * @param encryptedResponse the response body returned by a call to <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-refresh.md">/token/refresh</a>
+     * @param encryptedResponse the response body returned by a call to <a href="https://unifiedid.com/docs/endpoints/post-token-refresh">/token/refresh</a>
      * @param currentIdentity the current IdentityTokens instance, typically retrieved from a user's session
      * @return the refreshed IdentityTokens instance (with a new advertising token and updated expiry times). Typically, this will be used to replace the current identity in the user's session
      */

src/main/java/com/uid2/client/TokenGenerateInput.java

@@ -14,7 +14,7 @@ public static TokenGenerateInput fromEmail(String email) {
     }
 
     /**
-     * @param phone a <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/README.md#phone-number-normalization">normalized</a> phone number
+     * @param phone a <a href="https://unifiedid.com/docs/getting-started/gs-normalization-encoding#phone-number-normalization">normalized</a> phone number
      * @return a TokenGenerateInput instance, to be used in {@link PublisherUid2Helper#createEnvelopeForTokenGenerateRequest}
      */
     public static TokenGenerateInput fromPhone(String phone) {

src/main/java/com/uid2/client/TokenRefreshResponse.java

@@ -21,7 +21,7 @@ public boolean isSuccess() {
     }
 
     /**
-     * @return whether the user has opted out. See <a href="https://github.com/UnifiedID2/uid2docs/blob/main/api/v2/endpoints/post-token-refresh.md#optout">Optout</a>
+     * @return whether the user has opted out. See <a href="https://unifiedid.com/docs/endpoints/post-token-refresh#optout">Optout</a>
      */
     public boolean isOptout() {
         return "optout".equals(status);