Skip to content

Latest commit

 

History

History
294 lines (206 loc) · 14.2 KB

uid2-sdk-ref-python.md

File metadata and controls

294 lines (206 loc) · 14.2 KB
Raw
title description hide_table_of_contents sidebar_position
UID2 SDK for Python
Reference information about the Python server-side SDK.
false
6

import Link from '@docusaurus/Link';

UID2 SDK for Python Reference Guide

You can use the UID2 SDK for Python on the server side to facilitate the following:

  • Generating UID2 advertising tokens
  • Refreshing UID2 advertising tokens
  • Encrypting raw UID2s to create UID2 tokens for sharing
  • Decrypting UID2 tokens to access the raw UID2s

Functionality

This SDK simplifies integration with UID2 for any DSPs or UID2 sharers who are using Python for their server-side coding. The following table shows the functions it supports.

Encrypt Raw UID2 to UID2 Token Decrypt UID2 Token Generate UID2 Token from DII Refresh UID2 Token
Supported Supported Supported Supported

API Permissions

To use this SDK, you'll need to complete the UID2 account setup by following the steps described in the Account Setup page.

You'll be granted permission to use specific functions offered by the SDK, and given credentials for that access. Bear in mind that there might be functions in the SDK that you don't have permission to use. For example, publishers get a specific API permission to generate and refresh tokens, but the SDK might support other activities, such as sharing, which require a different API permission.

For details, see API Permissions.

Version

The SDK supports Python 3.6 and above.

GitHub Repository/Package

This SDK is in the following open-source GitHub repository:

The package is published in this location:

Initialization

The initialization step depends on the role, as shown in the following table.

Role Create Instance of Class Link to Instructions
Publisher Uid2PublisherClient Usage for Publishers
DSP BidstreamClient Usage for DSPs
Sharer SharingClient Usage for Sharers

You will need to provide the values necessary for the SDK to authenticate with the UID2 service.

Parameter Description
base_url The endpoint for the UID2 service. See Environments.
auth_key The API key. See UID2 Credentials.
secret_key The client secret. See UID2 Credentials.

Interface

The BidstreamClient class allows you to decrypt UID2 tokens into raw UID2s. For details on the bidding logic for handling user opt-outs, see DSP Integration Guide.

The SharingClient class allows you to encrypt raw UID2s into UID2 tokens and decrypt UID2 tokens into raw UID2s.

NOTE: When you use an SDK, you do not need to store or manage decryption keys.

Encryption Response Content

When encrypting with the SharingClient, the SDK returns the information shown in the following table.

Property Description
status The encryption result status. For a list of possible values and definitions, see Encryption Response Statuses.
encrypted_data The encrypted UID2 token.

Encryption Response Statuses

Encryption response codes, and their meanings, are shown in the following table.

Value Description
SUCCESS The raw UID2 was successfully encrypted and a UID2 token was returned.
NOT_AUTHORIZED_FOR_KEY The requester does not have authorization to use the encryption key.
NOT_AUTHORIZED_FOR_MASTER_KEY The requester does not have authorization to use the master key.
NOT_INITIALIZED The client library is waiting to be initialized.
KEYS_NOT_SYNCED The client has failed to synchronize keys from the UID2 service.
ENCRYPTION_FAILURE A generic encryption failure occurred.

Decryption Response Content

Whether decrypting with the BidstreamClient or the SharingClient, the SDK returns the information shown in the following table.

Property Description
status The decryption result status. For a list of possible values and definitions, see Decryption Response Statuses.
uid The raw UID2 for the corresponding UID2 token.
established The timestamp indicating when a user first established the UID2 with the publisher.

Decryption Response Statuses

Decryption response codes, and their meanings, are shown in the following table.

Value Description
SUCCESS The UID2 token was decrypted successfully and a raw UID2 was returned.
NOT_AUTHORIZED_FOR_KEY The requester does not have authorization to decrypt this UID2 token.
NOT_INITIALIZED The client library is waiting to be initialized.
INVALID_PAYLOAD The incoming UID2 token is not a valid payload.
EXPIRED_TOKEN The incoming UID2 token has expired.
KEYS_NOT_SYNCED The client has failed to synchronize keys from the UID2 service.
VERSION_NOT_SUPPORTED The client library does not support the version of the encrypted token.
DOMAIN_NAME_CHECK_FAILED The domain name doesn't match the domain of the encrypted token.
INVALID_TOKEN_LIFETIME The token has an invalid timestamp.

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) to UID2 tokens for targeted advertising. :::

do_not_generate_tokens_for_opted_out() applies optout_check=1 in the POST /token/generate call. Without this, optout_check is omitted to maintain backwards compatibility.

Client-Server Integration

If you're using client-server integration (see Server-Side Integration Guide for JavaScript), follow this step:

  • Send this identity as a JSON string back to the client (to use in the identity field) using the following:

    token_generate_response.get_identity_json_string()

    :::note If the user has opted out, this method returns None, so be sure to handle that case. :::

Server-Only Integration

If you're using server-only integration (see Publisher Integration Guide, Server-Only):

  1. Store this identity as a JSON string in the user's session, using the token_generate_response.get_identity_json_string() function.

    If the user has opted out, this method returns None, so be sure to handle that case.

  2. To retrieve the user's UID2 token, use the following:

    identity = token_generate_response.get_identity()
if identity:
   advertising_token = identity.get_advertising_token()

  3. Periodically check if the user's UID2 token should be refreshed. This can be done at fixed intervals using a timer, or can be done whenever the user accesses another page:

    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()):

  4. If needed, refresh the token and associated values:

    token_refresh_response = client.refresh_token(identity)`

  5. 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.

Usage for DSPs

The following instructions provide an example of how you can decode bid stream tokens using the UID2 SDK for Python as a DSP.

  1. Create a BidstreamClient:
client = BidstreamClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY)
  1. Refresh once at startup, and then periodically (recommended refresh interval is hourly):
client.refresh()
  1. Decrypt a token into a raw UID2. Pass the token, and then do one of the following:
  • If the bid request originated from a publisher's website, pass the domain name. The domain name must be all lower case, without spaces and without subdomain. For example, for Subdomain.DOMAIN.com, pass domain.com instead.
  • If the bid request originated from a mobile app, pass the app name.
  • Otherwise, pass null.
decrypted = client.decrypt_token_into_raw_uid(uid_token, domainOrAppName)
# If decryption succeeded, use the raw UID2.
if decrypted.success:
    #  Use decrypted.uid
else:
   # Check decrypted.status for the failure reason.

For a full example, see the sample_bidstream_client.py in examples/sample_bidstream_client.py.

Usage for UID2 Sharers

In UID2, sharing is a process for distributing either raw UID2s or UID2 tokens securely between UID2 participants. Raw UID2s must be encrypted into UID2 tokens before sending them to another participant.

IMPORTANT: The UID2 token generated during this process is for sharing only—you cannot use it in the bid stream. There is a different workflow for generating tokens for the bid stream: see Tokenized Sharing in the Bid Stream.

The following instructions provide an example of how you can implement sharing using the UID2 SDK for Python, either as a sender or a receiver.

  1. Create a SharingClient:
client = SharingClient(UID2_BASE_URL, UID2_API_KEY, UID2_SECRET_KEY)
  1. Refresh once at startup, and then periodically (recommended refresh interval is hourly):
client.refresh()
  1. If you are a sender, call encrypt_raw_uid_into_token():
encrypted = client.encrypt_raw_uid_into_token(raw_uid)
# If encryption succeeded, send the UID2 token to the receiver.
if encrypted.success:
    # Send encrypted.encrypted_data to receiver
else:
    # Check encrypted.status for the failure reason.

If you are a receiver, call decrypt_token_into_raw_uid():

decrypted = client.decrypt_token_into_raw_uid(uid_token)
# If decryption succeeded, use the raw UID2.
if decrypted.success:
    #  Use decrypted.uid
else:
    # Check decrypted.status for the failure reason.

For a full example, see the sample_sharing_client.py in examples/sample_sharing_client.py.

FAQs

For a list of frequently asked questions for DSPs, see FAQs for DSPs.