stop mentioning sample_encryption.py (#12)

* - stop mentioning sample_encryption.py as data encryption/decryption should be unused these days
- removed sample_encryption app from "make examples" building
- add encrypt() function example into sample_client.py.
- more comments in general
* fixed mentioning of old decrypt method in readme
* fixed missing IdentityScope param and typos

Author: sunnywu

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 example_encryption
+examples: example_client example_auto_refresh
 
 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)"

README.md

@@ -13,19 +13,19 @@ This SDK supports Python 3.6 and above.
 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:
 
 ```
-from uid2_client import Uid2Client, decrypt_token
+from uid2_client import Uid2Client, decrypt
 
 client = Uid2Client('https://prod.uidapi.com', 'my-auth-token', 'my-secret-key')
 keys = client.refresh_keys()
 advertising_token = 'AgAAAANRdREk+IWqqnQkZ2rZdK0TgSUP/owLryysSkUGZJT+Gy551L1WJMAZA/G2B1UMDQ20WAqwwTu6o9TexWyux0lg0HHIbmJjN6IYwo+42KC8ugaR+PX0y18qQ+3yzkxmJ/ee//4IGu/1Yq4AmO4ArXN6CeszPTxByTkysVqyQVNY2A=='
-decrypted_token = decrypt_token(advertising_token, keys)
+decrypted_token = decrypt(advertising_token, keys)
 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)
-* [sample_encryption.py](examples/sample_encryption.py)
+  * Includes an example to encrypt a raw UID2 into an advertising token for UID2 sharing.
 
 ## Development
 

examples/sample_client.py

@@ -2,7 +2,12 @@
 
 from uid2_client import Uid2Client
 from uid2_client import decrypt
+from uid2_client import encrypt
+from uid2_client.identity_scope import IdentityScope
 
+# 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).
 
 def _usage():
     print('Usage: python3 sample_client.py <base_url> <auth_key> <secret_key> <ad_token>', file=sys.stderr)
@@ -19,9 +24,15 @@ def _usage():
 
 client = Uid2Client(base_url, auth_key, secret_key)
 keys = client.refresh_keys()
-result = decrypt(ad_token, keys)
-
-print('UID2 =', result.uid2)
-print('Established =', result.established)
-print('Site ID =', result.site_id)
-print('Site Key Site ID =', result.site_key_site_id)
+decrypt_result = decrypt(ad_token, keys)
+
+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(ad_token, IdentityScope.UID2, decrypt_result.uid2)
+print('New Ad Token =', new_ad_token)

examples/sample_encryption.py

@@ -4,6 +4,8 @@
 from uid2_client import Uid2Client, IdentityScope
 from uid2_client import encrypt_data, decrypt_data
 
+# THIS FILE IS DEPRECATED!
+# To learn how to encrypt and decrypt a UID2 advertising token, see sample_client.py.
 
 def _usage():
     print('Usage: python3 sample_encryption.py <base_url> <auth_key> <secret_key> <ad_token> <data>', file=sys.stderr)

uid2_client/encryption.py

@@ -191,12 +191,12 @@ def _encrypt_token(uid2, identity_scope, master_key, site_key, site_id, now, tok
 
 
 
-def encrypt(uid2, indentity_scope, keys, keyset_id=None, **kwargs):
+def encrypt(uid2, identity_scope, keys, keyset_id=None, **kwargs):
     """ Encrypt an UID2 into a sharing token
 
     Args:
         uid2: the UID2 or EUID to be encrypted
-        indentity_scope (IdentityScope): indicates whether the output will be for UID2 or EUID
+        identity_scope (IdentityScope): indicates whether the output will be for UID2 or EUID
         keys (EncryptionKeysCollection): collection of keys to choose from for encryption
         keyset_id (int) : An optional keyset id to use for the encryption. Will use default keyset if left blank
 
@@ -229,7 +229,7 @@ def encrypt(uid2, indentity_scope, keys, keyset_id=None, **kwargs):
     if key is None:
         raise EncryptionError("No Keyset Key Found")
 
-    return _encrypt_token(uid2, indentity_scope, master_key, key, site_id, now, token_expiry, ad_token_version)
+    return _encrypt_token(uid2, identity_scope, master_key, key, site_id, now, token_expiry, ad_token_version)
 
 
 def encrypt_data(data, identity_scope, **kwargs):