Getting started with the Python SDK for the Audience Builder Media DCR

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

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

Creating a `Client`

A Client object must be constructed with user credentials to create a DCR. The Client object handles communication 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

An Audience Builder Media DCR is constructed using the AbMediaDcrBuilder. Mandatory fields are passed as arguments to the constructor, whilst optional configuration settings are enabled using builder functions. The optional settings include:

Configuring agency/observer/data partner email addresses.
Enabling collaboration types (Insights/Lookalike/Remarketing/Rule-Based).
Allowing advertiser audience downloads.
Hiding absolute values.

An example of building an Audience Builder Media DCR is shown below:

import decentriq_platform as dq
from decentriq_platform.ab_media import (
    AbMediaDcrBuilder,
    MatchingId,
)

advertiser_email = "@@ YOUR EMAIL HERE @@"
advertiser_api_token = "@@ YOUR TOKEN HERE @@"
advertiser_client = dq.create_client(advertiser_email, advertiser_api_token)
publisher_email = "@@ EMAIL OF PUBLISHER PARTICIPANT @@"

# Pass mandatory fields to the constructor.
builder = AbMediaDcrBuilder(
    name="audience-builder-dcr",
    publisher_emails=[publisher_email],
    advertiser_emails=[advertiser_email],
    matching_id_format=MatchingId.STRING,
    client=advertiser_client
)
# Configure optional settings.
dcr_definition = builder.\
    with_insights().\
    with_lookalike().\
    with_remarketing().\
    with_rule_based().\
    with_agency_emails(["test@agency.com"]).\
    with_observer_emails(["test@observer.com"]).\
    build()

Calling the build function returns an AbMediaDcrDefinition. This object completely describes the Audience Builder Media DCR.

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

Publishing the DCR

publisher You can publish an AbMediaDcrDefinition with a Client. This function returns an AbMediaDcr object which you can use to interact with the live DCR.

media_dcr = advertiser_client.publish_ab_media_dcr(dcr_definition=dcr_definition)

The DCR id uniquely identifies the DCR and is consistent across the UI and SDK. This is the same id that can be seen in the address bar of the Decentriq UI.

dcr_id = media_dcr.id

Provisioning data to an Audience Builder Media DCR

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

key = dq.Key()
with open("/path/to/advertiser_data.csv", "rb") as file:
    media_dcr.advertiser.upload_and_publish_audiences_dataset(file, key, "advertiser.csv")

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 @@"
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()
file_encryption_key = dq.Key()

data_lab.provision_local_datasets(
    file_encryption_key,
    "/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()

publisher_dcr = publisher_client.retrieve_ab_media_dcr(dcr_id)
publisher_dcr.publisher.provision_from_data_lab(data_lab.data_lab_id)

Managing audiences

Retrieving audiences

audiences = media_dcr.advertiser.get_audiences()

Creating audiences

Creating a rule-based audience

A RuleBasedAudienceBuilder is used to create rule-based audiences from an existing "source" audience. AudienceFilters and AudienceCombinator's may be specified, allowing the rule-based audience to be constructed as required. As a convenience, the audience can be made immediately available to the publisher using the with_make_available_to_publisher method.

AudienceFilters allow users within an audience to be selected based on the desired attributes.

AudienceCombinator's are created using the AudienceCombinatorBuilder. They allow multiple audiences to be combined and also allow AudienceFilters to be applied to the combining audience.

from decentriq_platform.ab_media import (
    RuleBasedAudienceBuilder,
    AudienceFilters,
    Filter,
    FilterOperator,
    AudienceCombinatorBuilder,
    CombineOperator,
    MatchOperator
)

audience_filters = AudienceFilters(
    filters=[
        Filter(
            attribute="gender",
            values=["M"],
            operator=FilterOperator.CONTAINS_ALL,
        ),
        Filter(
            attribute="age",
            values=["21-30", "31-40"],
            operator=FilterOperator.CONTAINS_ANY,
        ),
    ],
    operator=MatchOperator.MATCH_ALL,
)

audience_combinator = AudienceCombinatorBuilder(
    operator=CombineOperator.UNION,
    source_audience_name="All publisher users in insurance",
    audiences=audiences,
).with_filters(
    AudienceFilters(
        filters=[
            Filter(
                attribute="gender",
                values=["M"],
                operator=FilterOperator.CONTAINS_ALL,
            )
        ],
        operator=MatchOperator.MATCH_ALL,
    )
).build()

rule_based_audience_definition = (
    RuleBasedAudienceBuilder(
        name="rule-based-audience",
        source_audience_name="All publisher users in shoes",
        audiences=audiences,
    )
    .with_make_available_to_publisher()
    .with_filters(audience_filters)
    .with_combinator([audience_combinator])
    .build()
)
# Add the rule-based audience to the dcr.
media_dcr.advertiser.add_audiences(audiences=[rule_based_audience_definition])

Creating a lookalike audience

A LookalikeAudienceBuilder is used to create lookalike audiences from an existing "source" audience. It allows the reach to be specified as a percentage between 1-30 with the option of making the audience immediately available to the publisher throught the use of the with_make_available_to_publisher method.

from decentriq_platform.ab_media import (
    LookalikeAudienceBuilder
)

lookalike_audience_definiton = (
    LookalikeAudienceBuilder(
        name="shoes-lal",
        reach=22,
        source_audience_name="All publisher users in shoes",
        audiences=media_dcr.advertiser.get_audiences(),
    )
    .with_make_available_to_publisher()
    .build()
)
# Add the lookalike audience to the dcr.
media_dcr.advertiser.add_audiences(audiences=[lookalike_audience_definiton])

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 AbMediaDcr can be used as usual to interact with the DCR.

media_dcr = client.retrieve_ab_media_dcr(dcr_id)

Quickstart Script

You can use the following script to get started quickly:

import decentriq_platform as dq
from decentriq_platform.ab_media import (
    AbMediaDcrBuilder,
    MatchingId,
)

# establish connection
advertiser_email = "@@ YOUR EMAIL HERE @@"
advertiser_api_token = "@@ YOUR TOKEN HERE @@"
advertiser_client = dq.create_client(advertiser_email, advertiser_api_token)
publisher_email = "@@ EMAIL OF PUBLISHER PARTICIPANT @@"

"""
Create an Audience Builder Media DCR as an advertiser.
"""
builder = AbMediaDcrBuilder(
    name="audience-builder-dcr",
    publisher_emails=[publisher_email],
    advertiser_emails=[advertiser_email],
    matching_id_format=MatchingId.STRING,
    client=advertiser_client
)
dcr_definition = builder.\
    with_insights().\
    with_lookalike().\
    with_remarketing().\
    with_rule_based().\
    build()

media_dcr = advertiser_client.publish_ab_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:
    media_dcr.advertiser.upload_and_publish_audiences_dataset(file, key, "advertiser.csv")

"""
Continue initialising the Audience Builder Media DCR as a publisher.
The publisher must provision a data lab to the DCR before any further
advertiser interactions are permitted.
"""

publisher_api_token = "@@ PUBLISHER TOKEN 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()
file_encryption_key = dq.Key()

data_lab.provision_local_datasets(
    file_encryption_key,
    os.path.join(fixtures_dir, "pub_match.csv"),
    os.path.join(fixtures_dir, "pub_segment.csv"),
    demographics_data_path=os.path.join(fixtures_dir, "pub_demo.csv"),
    embeddings_data_path=os.path.join(fixtures_dir, "pub_attribute.csv"),
)
data_lab.run()
validation_report = data_lab.get_validation_report()
statistics_report = data_lab.get_statistics_report()

publisher_dcr = publisher_client.retrieve_media_dcr(media_dcr.id, enclave_specs=enclave_specs.values())
publisher_dcr.provision_from_data_lab(data_lab.data_lab_id)

"""
DCR fully initialised. Continue interacting with the DCR as an advertiser.
"""

# Retrieve the list of audiences
audiences = media_dcr.advertiser.get_audiences()

# make audiences with the given names available to the publisher
media_dcr.advertiser.make_audiences_available_to_publisher(
    audience_names=[
        "All publisher users in shoes",
        "All publisher users in insurance",
    ]
)

Creating a Client​

Creating a New Clean Room​

Publishing the DCR​

Provisioning data to an Audience Builder Media DCR​

Managing audiences​

Retrieving audiences​

Creating audiences​

Creating a rule-based audience​

Creating a lookalike audience​

Interacting with an existing DCR​

Quickstart Script​