Merge pull request #14 from IABTechLab/ian-UID2-1270-align-python-with-java

Ian UI d2 1270 align python with java

Author: Ian-Nara

Makefile

@@ -6,7 +6,7 @@ test:
 shell:
 	docker run -it -w $(PWD) -v $(PWD):$(PWD) -u `id -u`:`id -g` $(DOCKERIMAGE) /bin/bash
 
-examples: example_client example_auto_refresh
+examples: example_client example_auto_refresh example_sharing
 
 example_client:
 	docker run -w $(PWD) -v $(PWD):$(PWD) -u `id -u`:`id -g` -e PYTHONPATH=$(PWD) $(DOCKERIMAGE) python3 examples/sample_client.py "$(BASE_URL)" "$(AUTH_KEY)" "$(SECRET_KEY)" "$(AD_TOKEN)"
@@ -17,6 +17,10 @@ example_auto_refresh:
 example_encryption:
 	docker run -w $(PWD) -v $(PWD):$(PWD) -u `id -u`:`id -g` -e PYTHONPATH=$(PWD) $(DOCKERIMAGE) python3 examples/sample_encryption.py "$(BASE_URL)" "$(AUTH_KEY)" "$(SECRET_KEY)" "$(AD_TOKEN)" "Hello World!"
 
+example_sharing:
+	docker run -w $(PWD) -v $(PWD):$(PWD) -u `id -u`:`id -g` -e PYTHONPATH=$(PWD) $(DOCKERIMAGE) python3 examples/sample_sharing.py "$(BASE_URL)" "$(AUTH_KEY)" "$(SECRET_KEY)" "$(RAW_UID)"
+
+
 docker:
 	docker build -t $(DOCKERIMAGE) -f Dockerfile.dev .
 

README.md

@@ -2,30 +2,72 @@
 
 The UID 2 Project is subject to Tech Lab IPR’s Policy and is managed by the IAB Tech Lab Addressability Working Group and Privacy & Rearc Commit Group. Please review [the governance rules](https://github.com/IABTechLab/uid2-core/blob/master/Software%20Development%20and%20Release%20Procedures.md).
 
-This SDK simplifies integration with UID2 for those using Python.
+This document includes:
+* [Who Is this SDK for?](#who-is-this-sdk-for)
+* [Requirements](#requirements)
+* [Install](#install)
+* [Usage for DSPs](#usage-for-dsps)
+* [Usage for UID2 Sharers](#usage-for-uid2-sharers)
+* [Development](#development)
+  * [Example Usage](#example-usage)
 
-## Dependencies
+## Who Is this SDK for?
+
+This SDK simplifies integration with UID2 for DSPs and UID Sharers, as described in [UID2 Integration Guides](https://unifiedid.com/docs/category/integration-guides).
+
+## Requirements
 
 This SDK supports Python 3.6 and above.
 
-## Quick Start
+## Install
 
-Connect to the UID2 service, refresh the encryption keys, and then use the keys to decrypt an advertising token, to arrive at the corresponding advertising ID:
+The SDK can be installed using pip.
+```
+pip install uid2-client
+```
 
+## Usage for DSPs
+
+Connect to the UID2 service, refresh the encryption keys, and then use the keys to decrypt an advertising token, to arrive at the corresponding advertising ID:
+For examples of usage for DSPs, see [sample_client.py](examples/sample_client.py) and [sample_auto_refresh.py](examples/sample_auto_refresh.py)
 ```
-from uid2_client import Uid2Client, decrypt
+from uid2_client import Uid2ClientFactory
 
-client = Uid2Client('https://prod.uidapi.com', 'my-auth-token', 'my-secret-key')
-keys = client.refresh_keys()
+# for UID2 (for EUID use EuidClientFactory)
+client = Uid2ClientFactory.create('https://prod.uidapi.com', 'my-auth-token', 'my-secret-key')
+client.refresh_keys()
 advertising_token = 'AgAAAANRdREk+IWqqnQkZ2rZdK0TgSUP/owLryysSkUGZJT+Gy551L1WJMAZA/G2B1UMDQ20WAqwwTu6o9TexWyux0lg0HHIbmJjN6IYwo+42KC8ugaR+PX0y18qQ+3yzkxmJ/ee//4IGu/1Yq4AmO4ArXN6CeszPTxByTkysVqyQVNY2A=='
-decrypted_token = decrypt(advertising_token, keys)
+decrypted_token = client.decrypt(advertising_token)
 print(decrypted_token.uid2)
 ```
 
-Additional examples are in the [examples] directory:
-* [sample_auto_refresh.py](examples/sample_auto_refresh.py)
-* [sample_client.py](examples/sample_client.py)
-  * Includes an example to encrypt a raw UID2 into an advertising token for UID2 sharing.
+## Usage for Sharers
+
+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 examples of usage, see [sample_sharing.py](examples/sample_sharing.py) and [sample_auto_refresh.py](examples/sample_auto_refresh.py)
+
+```
+from uid2_client import Uid2ClientFactory
+
+# for UID2 (for EUID use EuidClientFactory)
+client = Uid2ClientFactory.create('https://prod.uidapi.com', 'my-auth-token', 'my-secret-key')
+client.refresh_keys()
+```
+Senders:
+
+1. Call the following:
+```
+encrypted = client.encrypt(raw_uid)
+ ```
+2. If encryption was successful, send the token `encrypted.uid2` to the receiver.
+
+Receivers:
+
+1. Call the following:
+```
+decrypted = client.decrypt(uid_token)
+```
+2. If decryption was successful, use the token `decrypted.uid2`.
 
 ## Development
 
@@ -53,13 +95,14 @@ Get access to an interactive shell within the Python 3.6 Docker image:
 make shell
 ```
 
-## Example Usage
+### Example Usage
 
 To run all the example applications:
 
 ```
 make examples BASE_URL=https://prod.uidapi.com AUTH_KEY=my-auth-key SECRET_KEY=my-secret-key \
-	AD_TOKEN=AgAAAANRdREk+IWqqnQkZ2rZdK0TgSUP/owLryysSkUGZJT+Gy551L1WJMAZA/G2B1UMDQ20WAqwwTu6o9TexWyux0lg0HHIbmJjN6IYwo+42KC8ugaR+PX0y18qQ+3yzkxmJ/ee//4IGu/1Yq4AmO4ArXN6CeszPTxByTkysVqyQVNY2A==
+	AD_TOKEN=AgAAAANRdREk+IWqqnQkZ2rZdK0TgSUP/owLryysSkUGZJT+Gy551L1WJMAZA/G2B1UMDQ20WAqwwTu6o9TexWyux0lg0HHIbmJjN6IYwo+42KC8ugaR+PX0y18qQ+3yzkxmJ/ee//4IGu/1Yq4AmO4ArXN6CeszPTxByTkysVqyQVNY2A== \
+	RAW_UID=JCqmlLXpbbu/jTdpB2a1cNAVs8O72eMXPaQzC9Ic9mE=
 ```
 
 Alternatively, you can run specific examples:

examples/sample_auto_refresh.py

@@ -3,8 +3,8 @@
 import time
 
 from uid2_client import EncryptionKeysAutoRefresher
-from uid2_client import Uid2Client
-from uid2_client import decrypt
+from uid2_client import EuidClientFactory
+from uid2_client import Uid2ClientFactory
 
 
 def _usage():
@@ -20,13 +20,16 @@ def _usage():
 secret_key = sys.argv[3]
 ad_token = sys.argv[4]
 
-client = Uid2Client(base_url, auth_key, secret_key)
+# for EUID use:
+# client = EuidClientFactory.create(base_url, auth_key, secret_key)
+# for UID2 use:
+client = Uid2ClientFactory.create(base_url, auth_key, secret_key)
 with EncryptionKeysAutoRefresher(client, dt.timedelta(seconds=4), dt.timedelta(seconds=7)) as refresher:
     for i in range(0, 20):
         refresh_result = refresher.current_result()
         if refresh_result.ready:
             print('Keys are ready, last refreshed (UTC):', refresh_result.last_success_time, flush=True)
-            result = decrypt(ad_token, refresh_result.keys)
+            result = client.decrypt(ad_token)
             print('UID2 =', result.uid2, flush=True)
         else:
             print('Keys are not ready yet, last error:', refresh_result.last_error[1], flush=True)

examples/sample_client.py

@@ -1,13 +1,11 @@
 import sys
 
-from uid2_client import Uid2Client
-from uid2_client import decrypt
-from uid2_client import encrypt
-from uid2_client.identity_scope import IdentityScope
+from uid2_client.euid_client_factory import EuidClientFactory
+from uid2_client.uid2_client_factory import Uid2ClientFactory
+
 
 # this sample client decrypts an advertising token into a raw UID2
-# and then encrypts it into a new advertising token
-# to demonstrate decryption (for DSPs and sharers) and encryption (sharers only).
+# to demonstrate decryption for DSPs
 
 def _usage():
     print('Usage: python3 sample_client.py <base_url> <auth_key> <secret_key> <ad_token>', file=sys.stderr)
@@ -22,17 +20,14 @@ def _usage():
 secret_key = sys.argv[3]
 ad_token = sys.argv[4]
 
-client = Uid2Client(base_url, auth_key, secret_key)
-keys = client.refresh_keys()
-decrypt_result = decrypt(ad_token, keys)
+# for EUID use:
+# client = EuidClientFactory.create(base_url, auth_key, secret_key)
+# for UID2 use:
+client = Uid2ClientFactory.create(base_url, auth_key, secret_key)
+client.refresh_keys()
+decrypt_result = client.decrypt(ad_token)
 
 print('UID2 =', decrypt_result.uid2)
 print('Established =', decrypt_result.established)
 print('Site ID =', decrypt_result.site_id)
 print('Site Key Site ID =', decrypt_result.site_key_site_id)
-
-# Not required for DSPs, but for those using UID2 sharing functionality this shows how to encrypt a raw UID2 into
-# a new advertising token.
-# IdentityScope could be UID2 or EUID
-new_ad_token = encrypt(decrypt_result.uid2, IdentityScope.UID2, keys)
-print('New Ad Token =', new_ad_token)

examples/sample_sharing.py

@@ -0,0 +1,37 @@
+import sys
+
+from uid2_client import EuidClientFactory
+from uid2_client import Uid2ClientFactory
+
+
+# this sample client encrypts and decrypts a uid2 to a sharing token
+# to demonstrate encryption and decryption for sharers
+
+def _usage():
+    print('Usage: python3 sample_encryption.py <base_url> <auth_key> <secret_key> <raw_uid>', file=sys.stderr)
+    sys.exit(1)
+
+
+if len(sys.argv) <= 4:
+    _usage()
+
+base_url = sys.argv[1]
+auth_key = sys.argv[2]
+secret_key = sys.argv[3]
+raw_uid = sys.argv[4]
+
+# for EUID use:
+# client = EuidClientFactory.create(base_url, auth_key, secret_key)
+# for UID2 use:
+client = Uid2ClientFactory.create(base_url, auth_key, secret_key)
+client.refresh_keys()
+new_ad_token = client.encrypt(raw_uid)
+
+print('New Ad Token =', new_ad_token)
+
+decrypt_result = client.decrypt(new_ad_token)
+
+print('Decrypted UID2 =', decrypt_result.uid2)
+print('Established =', decrypt_result.established)
+print('Site ID =', decrypt_result.site_id)
+print('Site Key Site ID =', decrypt_result.site_key_site_id)