Merge remote-tracking branch 'origin/ian-UID2-970-publisher-sdk' into ian-UID2-970-publisher-sdk

# Conflicts:
#	examples/sample_token_generate_refresh.py

Author: Ian-Nara

README.md

@@ -69,6 +69,57 @@ decrypted = client.decrypt(uid_token)
 ```
 2. If decryption was successful, use the token `decrypted.uid2`.
 
+## Usage for Publishers
+
+1. Create an instance of Uid2PublisherClient
+ 
+   `client = Uid2PublisherClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY)`
+
+2. Call a function that takes the user's email address or phone number as input and generates a `TokenGenerateResponse` object. The following example uses an email address:
+ 
+   `token_generate_response = client.generate_token(TokenGenerateInput.from_email(emailAddress).do_not_generate_tokens_for_opted_out())`
+
+   >IMPORTANT: Be sure to call this function only when you have obtained legal basis to convert the user’s [directly identifying information (DII)](https://unifiedid.com/docs/ref-info/glossary-uid#gl-dii) to UID2 tokens for targeted advertising.
+   
+   >`do_not_generate_tokens_for_opted_out()` applies `policy=1` in the [/token/generate](https://unifiedid.com/docs/endpoints/post-token-generate#token-generation-policy) call. Without this, `policy` is omitted to maintain backwards compatibility.
+
+### Standard Integration
+
+If you're using standard integration (client and server) (see [UID2 SDK for JavaScript 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:
+
+    `token_generate_response.get_identity_json_string()` //Note: this method returns `None` if the user has opted out, so be sure to handle that case.
+
+### Server-Only Integration
+
+If you're using server-only integration (see [Publisher Integration Guide, Server-Only](https://unifiedid.com/docs/guides/custom-publisher-integration)):
+
+1. Store this identity as a JSON string in the user's session, using the `token_generate_response.get_identity_json_string()` function. This method returns `None` if the user has opted out, so be sure to handle that case.
+2. To retrieve the user's UID2 token, use:
+
+   ```
+   identity = token_generate_response.get_identity()
+   if identity:
+      advertising_token = identity.get_advertising_token()
+   ```
+4. 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 takes the identity information as input and generates an `IdentityTokens` object:
+
+      `identity = IdentityTokens.from_json_string(identityJsonString)`
+   2. Determine if the identity can be refreshed (that is, the refresh token hasn't expired):
+
+      ` if not identity or not identity.is_refreshable(): # we must no longer use this identity (for example, remove this identity from the user's session) `
+   3. Determine if a refresh is needed:
+
+      `if identity.is_due_for_refresh()):`
+5. If needed, refresh the token and associated values:
+ 
+   `token_refresh_response = client.refresh_token(identity)`
+ 
+6. Store `token_refresh_response.get_identity_json_string()` in the user's session. If the user has opted out, this method returns `None`, indicating that the user's identity should be removed from the session. To confirm optout, you can use the `token_refresh_response.is_optout()` function.
+
+
 ## Development
 
 First, build the Docker image with Python 3.6 and all dev dependencies. This is required for all subsequent commands. Run the following:

examples/sample_token_generate_refresh.py

@@ -0,0 +1,64 @@
+import sys
+
+from uid2_client import Uid2PublisherClient
+from uid2_client import TokenGenerateResponse
+from uid2_client import TokenGenerateInput
+
+
+def _usage():
+    print('Usage: python3 sample_token_generate_refresh.py <base_url> <auth_key> <secret_key>', file=sys.stderr)
+    sys.exit(1)
+
+
+if len(sys.argv) <= 3:
+    _usage()
+
+base_url = sys.argv[1]
+auth_key = sys.argv[2]
+secret_key = sys.argv[3]
+
+
+publisher_client = Uid2PublisherClient(base_url, auth_key, secret_key)
+print("Generating Token")
+token_generate_response = publisher_client.generate_token(TokenGenerateInput.from_email("[email protected]").do_not_generate_tokens_for_opted_out())
+
+status = token_generate_response.status
+tokens = token_generate_response.get_identity()
+
+advertising_token = tokens.get_advertising_token()
+refresh_token = tokens.get_refresh_token()
+refresh_response_key = tokens.get_refresh_response_key()
+refresh_from = tokens.get_refresh_from()
+refresh_expires = tokens.get_refresh_expires()
+identity_expires = tokens.get_identity_expires()
+json_string = tokens.get_json_string()
+
+print('Status =', status)
+print('Advertising Token =', advertising_token)
+print('Refresh Token =', refresh_token)
+print('Refresh Response Key =', refresh_response_key)
+print('Refresh From =', refresh_from)
+print('Refresh Expires =', refresh_expires)
+print('Identity Expires =', identity_expires)
+print('As Json String =', json_string, "\n")
+
+print("Refreshing Token")
+token_refresh_response = publisher_client.refresh_token(tokens)
+status = token_refresh_response.status
+tokens = token_refresh_response.get_identity()
+advertising_token = tokens.get_advertising_token()
+refresh_token = tokens.get_refresh_token()
+refresh_response_key = tokens.get_refresh_response_key()
+refresh_from = tokens.get_refresh_from()
+refresh_expires = tokens.get_refresh_expires()
+identity_expires = tokens.get_identity_expires()
+json_string = tokens.get_json_string()
+
+print('Status =', status)
+print('Advertising Token =', advertising_token)
+print('Refresh Token =', refresh_token)
+print('Refresh Response Key =', refresh_response_key)
+print('Refresh From =', refresh_from)
+print('Refresh Expires =', refresh_expires)
+print('Identity Expires =', identity_expires)
+print('As Json String =', json_string)

uid2_client/encryption.py

@@ -267,7 +267,7 @@ def encrypt_data(data, identity_scope, **kwargs):
 
     The keyword arguments key, keys, site_id and advertising_token can only be used in
     the following combinations:
-        - key: use the specied key
+        - key: use the specified key
         - keys and site_id: find the key for the specified site_id
         - keys and advertising_token: extract site_id from the token and find a key for it
     """