Getting started with the Python SDK for Media DCR

This tutorial will show the steps required to build and run a Media Data Clean Room (DCR) from scratch. You will learn how to:

• create a Client for interacting with the Decentriq Platform,
• Create a new Media DCR
• provision data to a Media DCR
• download audiences from a Media DCR
• find and interact with an existing Media DCR

Quickstart Script

import decentriq_platform as dq

# establish connection
advertiser_email = "@@ YOUR EMAIL HERE @@"
advertiser_api_token = "@@ YOUR TOKEN HERE @@"
client = dq.create_client(advertiser_email, advertiser_api_token)
enclave_specs = dq.enclave_specifications.latest()

You can use the following script to get started quickly:

import decentriq_platform as dq
from decentriq_platform.legacy.types import MatchingId

# establish connection
advertiser_email = "@@ YOUR EMAIL HERE @@"
advertiser_api_token = "@@ YOUR TOKEN HERE @@"
publisher_email = "@@ EMAIL OF PUBLISHER PARTICIPANT @@"
advertiser_client = dq.create_client(advertiser_email, advertiser_api_token)
auth, _ = advertiser_client.create_auth_using_decentriq_pki(enclave_specs)
advertiser_session = advertiser_client.create_session(auth, enclave_specs)

# create new Media DCR
builder = dq.media.MediaDcrBuilder(client=advertiser_client)
dcr_definition = builder.\
    with_name("My DCR").\
    with_insights().\
    with_lookalike().\
    with_retargeting().\
    with_matching_id_format(MatchingId.STRING).\
    with_publisher_emails(publisher_email).\
    with_advertiser_emails(advertiser_email).\
    build()
media_dcr = advertiser_client.publish_media_dcr(dcr_definition)
dcr_id = media_dcr.id

# upload and publish data
key = dq.Key()
with open("/path/to/advertiser_data.csv", "rb") as file:
    dataset_id = advertiser_client.upload_dataset(file, key, "advertiser.csv")
advertiser_session.publish_dataset(dcr_id, dataset_id, "audiences", key)

# must wait for publisher upload and audience selection here ...

# download activated audiences
activate_audience_list = [
    dq.media.Audience(
        audience_type="shoes",
        activation_type=dq.media.ActivationType.RETARGET,
        is_published=True,
    ),
]
media_dcr.activate_audience(
    audiences=activate_audience_list
)

Creating a Client

A Client object must be constructed with user credentials to create a DCR. The Client object handles communicating with the Decentriq platform. It can retrieve information about existing DCRs, provision data, and run computations.

import decentriq_platform as dq

advertiser_email = "@@ YOUR EMAIL HERE @@"
advertiser_api_token = "@@ YOUR TOKEN HERE @@"

advertiser_client = dq.create_client(advertiser_email, advertiser_api_token)

NOTE

Create and manage your API tokens via the Decentriq UI - API tokens page.

Creating a New Clean Room

The MediaDcrBuilder provides a convenient way of constructing a Media DCR. The MediaDcrBuilder has functions you can use to create a new DCR. Examples parameters include:

• Setting the DCR name
• Enabling different feature sets (Insights/Lookalike/Remarketing)
• Setting publisher/advertiser email addresses

An example of building a Media DCR is shown below:

from decentriq_platform.media import MediaDcrBuilder

builder = MediaDcrBuilder(client=advertiser_client)
dcr_definition = builder.\
    with_name("My DCR").\
    with_insights().\
    with_lookalike().\
    with_retargeting().\
    with_matching_id_format(MatchingId.STRING).\
    with_publisher_emails(publisher_email).\
    with_advertiser_emails(advertiser_email).\
    with_agency_emails(["test@agency.com"]).\
    with_observer_emails(["test@observer.com"]).\
    build()

The MediaDcrBuilder depends on a Client to know which version of the enclave software to use.

Calling the build function returns a MediaDcrDefinition. This object completely describes the entire Media DCR.

To make the DCR available for collaboration, you must "publish" the MediaDcrDefinition.

Publishing the DCR

You can publish a MediaDcrDefinition with a Client. This function returns a MediaDcr object which you can use to interact with the live DCR.

media_dcr = advertiser_client.publish_media_dcr(dcr_definition)

The id field of the of the DCR is a unique way to identify it that is consistent across the UI and SDK. This is the same id you also see in the address bar of the Decentriq UI.

dcr_id = media_dcr.id

Provisioning data to a Media DCR

Advertisers can use their data in a Media DCR by provisioning a dataset directly.

key = dq.Key()
dataset_id = ""
with open("/path/to/advertiser_data.csv", "rb") as file:
    dataset_id = advertiser_client.upload_dataset(file, key, "advertiser.csv")
advertiser_session.publish_dataset(dcr_id, dataset_id, "audiences", key)

Publishers need to create a data lab, an intermediate step that helps them check for internal consistency in their data. Please contact customer success for more support working with data labs. This small snippet is provided to help brands test clean rooms in a "quick start" test.

publisher_email = "@@ EMAIL OF PUBLISHER PARTICIPANT @@"
publisher_api_token = "@@ PUBLISHER TOKEN HERE @@"
keychain_password = "@@ PUBLISHER KEYCHAIN PASSWORD HERE @@"
publisher_client = dq.create_client(publisher_email, publisher_api_token)
builder = dq.data_lab.DataLabBuilder(publisher_client)
builder.with_name("tutorial-data-lab")
builder.with_matching_id_format(dq.types.MatchingIdFormat.STRING)
builder.with_embeddings(50)
builder.with_demographics()
builder.with_segments()

data_lab = builder.build()
publisher_keychain = dq.Keychain.get_or_create_unlocked_keychain(
    publisher_client,
    keychain_password.encode() 
)

file_encryption_key = dq.Key()

data_lab.provision_local_datasets(
    file_encryption_key,
    publisher_keychain,
    "/path/to/matching_data.csv",
    "/path/to/segments_data.csv",
    demographics_data_path="/path/to/demographics_data.csv",
    embeddings_data_path="/path/to/embeddings_data.csv",
)
data_lab.run()
validation_report = data_lab.get_validation_report()
statistics_report = data_lab.get_statistics_report()
data_lab.provision_to_media_insights_data_room(dcr_id, publisher_keychain)

Activate and retrieve audiences

The below list summarises the computations that can be run by the advertiser.

1. Activating audiences.

from decentriq_platform.media import Audience, ActivationType

activate_audience_list = [
    Audience(
        audience_type="shoes",
        activation_type=ActivationType.RETARGET,
        is_published=True,
    ),
]
media_dcr.activate_audience(
    audiences=activate_audience_list
)

1. Advertiser audiences.

advertiser_audiences = media_dcr.get_audiences_for_advertiser()

Interacting with an existing DCR

A DCR might have been created in the Decentriq UI or as part of another script. In this case it can easily be retrieved using the Client object.

Once retrieved, the MediaDcr can be used as usual to interact with the DCR.

media_dcr = client.retrieve_media_dcr(dcr_id)