Package: uid2-client
UID2 SDK for PythonThe 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 reviewthe governance rules.This document includes:Who Is this SDK for?RequirementsInstallUsage for DSPsUsage for PublishersStandard IntegrationServer-Only IntegrationUsage for UID2 SharersDevelopmentExample UsageHistoryWho Is this SDK for?This SDK simplifies integration with UID2 for Publishers, DSPs and UID Sharers, as described inUID2 Integration Guides.RequirementsThis SDK supports Python 3.6 and above.InstallThe SDK can be installed using pip.pip install uid2-clientUsage for DSPsConnect 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, seesample_client.pyandsample_auto_refresh.pyfrom 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()
advertising_token = 'AgAAAANRdREk+IWqqnQkZ2rZdK0TgSUP/owLryysSkUGZJT+Gy551L1WJMAZA/G2B1UMDQ20WAqwwTu6o9TexWyux0lg0HHIbmJjN6IYwo+42KC8ugaR+PX0y18qQ+3yzkxmJ/ee//4IGu/1Yq4AmO4ArXN6CeszPTxByTkysVqyQVNY2A=='
decrypted_token = client.decrypt(advertising_token)
print(decrypted_token.uid2)Usage for PublishersCreate an instance of Uid2PublisherClientclient = Uid2PublisherClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY)Call a function that takes the user's email address or phone number as input and generates aTokenGenerateResponseobject. 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’sdirectly identifying information (DII)to UID2 tokens for targeted advertising.IMPORTANT: Always applydo_not_generate_tokens_for_opted_out(). This appliespolicy=1in the/token/generatecall. Support forpolicy=0will be removed soon.Standard IntegrationIf you're using standard integration (client and server) (seeUID2 SDK for JavaScript Integration Guide), follow this step:Send this identity as a JSON string back to the client (to use in theidentity field) using the following:token_generate_response.get_identity_json_string()//Note: this method returnsNoneif the user has opted out, so be sure to handle that case.Server-Only IntegrationIf you're using server-only integration (seePublisher Integration Guide, Server-Only):Store this identity as a JSON string in the user's session, using thetoken_generate_response.get_identity_json_string()function. This method returnsNoneif the user has opted out, so be sure to handle that case.To retrieve the user's UID2 token, use:identity = token_generate_response.get_identity()
if identity:
   advertising_token = identity.get_advertising_token()When the user accesses another page, or on a timer, determine whether a refresh is needed: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 anIdentityTokensobject:identity = IdentityTokens.from_json_string(identityJsonString)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)Determine if a refresh is needed:if identity.is_due_for_refresh()):If needed, refresh the token and associated values:token_refresh_response = client.refresh_token(identity)Storetoken_refresh_response.get_identity_json_string()in the user's session. If the user has opted out, this method returnsNone, indicating that the user's identity should be removed from the session. To confirm optout, you can use thetoken_refresh_response.is_optout()function.Usage for SharersA 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, seesample_sharing.pyandsample_auto_refresh.pyfrom 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:Call the following:encrypted = client.encrypt(raw_uid)If encryption was successful, send the tokenencrypted.uid2to the receiver.Receivers:Call the following:decrypted = client.decrypt(uid_token)If decryption was successful, use the tokendecrypted.uid2.DevelopmentFirst, build the Docker image with Python 3.6 and all dev dependencies. This is required for all subsequent commands. Run the following:make dockerRun unit tests:make testBuild a bdist wheel:make wheelGet access to an interactive shell within the Python 3.6 Docker image:make shellExample UsageTo 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== \
	RAW_UID=JCqmlLXpbbu/jTdpB2a1cNAVs8O72eMXPaQzC9Ic9mE=Alternatively, you can run specific examples:make example_client 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==
make example_auto_refresh 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==History2.2.0 (07/26/2023)Added support for /token/generateAdded support for /token/refresh2.2.1 (12/05/2023)Support for policy=0 will be removed soon