Migrating to Media DCR v3
This guide outlines the steps required to migrate from the Audience Builder Media DCR (AB Media DCR) to the new Media DCR. We'll cover all major changes and provide code examples for updating your existing implementations.
Overview of Changes
- Package and class name changes
- New participant permission model
- Simplified DCR creation process
- Updated audience management
- Changes to data provisioning methods
- Changes to computation methods
Detailed Migration Steps
1. Package and Import Changes
The ab_media
module is replaced with the media
module.
Previous Version
from decentriq_platform.ab_media import (
AbMediaDcrBuilder,
MatchingId,
)
New Version
from decentriq_platform.media import (
MediaDcr,
Participant,
CollaborationType,
Permission,
MatchingId,
)
2. Creating a Media DCR
Media DCR creation no longer requires a builder. Instead, a MediaDcr
instance can be created directly.
Participants are added through the Participant
class and require permissions to be explicitly given.
CollaborationType
must be provided to determine the capabilities of the Media DCR being constructed. By default the Overlap
CollaborationType
is enabled and does not need to be explicitly set.
Previous Version
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().\
with_agency_emails(["test@agency.com"]).\
with_observer_emails(["test@observer.com"]).\
build()
media_dcr = advertiser_client.publish_ab_media_dcr(dcr_definition=dcr_definition)
New Version
media_dcr = MediaDcr(
client=advertiser_client,
name="my_media_dcr",
participants=[
Participant(
role="Publisher",
emails=[publisher_email],
permissions=[
Permission.VIEW_OVERLAP,
Permission.VIEW_INSIGHTS,
Permission.PROVIDE_BASE_AUDIENCE,
Permission.EXPORT_AUDIENCE,
],
),
Participant(
role="Advertiser",
emails=[advertiser_email],
permissions=[
Permission.VIEW_OVERLAP,
Permission.VIEW_INSIGHTS,
Permission.PROVIDE_SEED_AUDIENCE,
Permission.EXPORT_AUDIENCE,
Permission.CREATE_CUSTOM_AUDIENCE,
],
),
],
collaboration_types=[
CollaborationType.INSIGHTS,
CollaborationType.LOOKALIKE,
CollaborationType.REMARKETING,
CollaborationType.RULE_BASED,
],
matching_ids=[MatchingId.STRING],
)
3. Provisioning Advertiser Data
Previous Version
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")
New Version
key = dq.Key()
with open("/path/to/advertiser_data.csv", "rb") as file:
advertiser_dataset_manifest_hash = advertiser_client.upload_dataset(
file,
key,
"advertiser.csv",
)
media_dcr.provision_seed_audiences(advertiser_dataset_manifest_hash)
4. Publisher Data Provisioning
Publisher data is still provisioned via a data lab using the provision_base_audience
function call.
Previous Version
publisher_dcr = publisher_client.retrieve_ab_media_dcr(dcr_id)
publisher_dcr.publisher.provision_from_data_lab(data_lab.data_lab_id)
New Version
publisher_dcr = MediaDcr.from_existing(media_dcr.id, publisher_client)
publisher_dcr.provision_base_audience(data_lab.data_lab_id)
5. Audience Management
Creating Rule Based Audiences
Previous Version
from decentriq_platform.ab_media import RuleBasedAudienceBuilder
# Retrieving audiences
audiences = media_dcr.advertiser.get_audiences()
# Creating rule-based audience
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(
AudienceFilters(
filters=[
Filter(
attribute="gender",
values=["M"],
operator=FilterOperator.CONTAINS_ALL,
)
],
operator=MatchOperator.MATCH_ALL,
)
)
.build()
)
media_dcr.advertiser.add_audiences(audiences=[rule_based_audience_definition])
New Version
from decentriq_platform.media import RuleBasedAudienceBuilder
# Retrieving audiences
# The computations can also be chained together i.e.
# `audiences = (
# media_dcr.get_audiences()
# .wait_for_completion()
# .result()
# )`
audiences_job = media_dcr.get_audiences()
audiences_job.wait_for_completion()
audiences = audiences_job.result()
# Creating rule-based audience
participants = media_dcr.get_participants()
# Filter by participant role. These are the same roles that are displayed in the UI.
publisher_participant = [participant for participant in participants if participant.role == "Publisher"][0]
# Here the `shoes` audience type is retrieved.
# In the UI this audience will appear as "All publisher users in shoes".
source_audience = audiences.get_seed_audience("shoes")
rule_based_audience_definition = (
RuleBasedAudienceBuilder(
name="rule-based-audience",
source_audience=source_audience,
)
.with_share_with_participants([publisher_participant])
.with_filters(
AudienceFilters(
filters=[
Filter(
attribute="gender",
values=["M"],
operator=FilterOperator.CONTAINS_ALL,
)
],
operator=MatchOperator.MATCH_ALL,
)
)
.build()
)
rb_audience = media_dcr.create_rule_based_audience(rule_based_audience_definition)
Creating Lookalike Audiences
Previous Version
from decentriq_platform.ab_media 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])
New Version
from decentriq_platform.media import LookalikeAudienceBuilder
participants = media_dcr.get_participants()
publisher_participant = [participant for participant in participants if participant.role == "Publisher"][0]
source_audience = audiences.get_seed_audience("shoes")
lookalike_audience_definition = (
LookalikeAudienceBuilder(
name="shoes-lal",
reach=22,
source_audience=source_audience,
)
.with_share_with_participants([publisher_participant])
.build()
)
# Create the lookalike audience in the DCR
lal_audience = media_dcr.create_lookalike_audience(lookalike_audience_definition)
6. Running Computations and Retrieving Results
Media DCR v3 introduces asynchronous job-based operations for most computations. All computation methods now return job objects that must be waited on to retrieve results.
Note: Computations can be written in 2 ways, the verbose way or the concise/chained way. The decision is left up to user preference. An example of this is shown below.
# The verbose way
stats_job = media_dcr.get_overlap_statistics()
stats_job.wait_for_completion()
stats = stats_job.result().model_dump()
#The concise way
stats = (
media_dcr.get_overlap_statistics()
.wait_for_completion()
.result()
.model_dump()
)
Getting Overlap Statistics
Previous Version
# Get overlap statistics
stats = media_dcr.advertiser.get_overlap_statistics()
New Version
# Get overlap statistics
stats = (
media_dcr.get_overlap_statistics()
.wait_for_completion()
.result()
.model_dump()
)
Estimating Audience Size
Previous Version
# Estimate advertiser audience size
estimate_audience_size = media_dcr.advertiser.estimate_audience_size(
audience_name="All publisher users in shoes"
)
New Version
# Get audiences first
audiences = (
media_dcr.get_audiences()
.wait_for_completion()
.result()
)
# Get the source audience object
source_audience = audiences.get_seed_audience("shoes")
# Estimate audience size
estimate_audience_size = (
media_dcr.get_audience_size(source_audience)
.wait_for_completion()
.result()
)
Getting Lookalike Audience Statistics
Previous Version
# Get lookalike audience statistics
lal_statistics = media_dcr.advertiser.get_lookalike_audience_statistics(
audience_name="All publisher users in shoes"
)
New Version
# Get audiences first
audiences = (
media_dcr.get_audiences()
.wait_for_completion()
.result()
)
# Get the source audience object
lal_audience = audiences.get_custom_audience("shoes-lal")
# Get lookalike audience statistics
lal_statistics = (
media_dcr.get_lookalike_audience_statistics(lal_audience)
.wait_for_completion()
.result()
.model_dump()
)
Getting Attributes
Previous Version
# Get audience attributes
attributes = media_dcr.advertiser.get_audience_attributes()
New Version
# Get data attributes
attributes = (
media_dcr.get_data_attributes()
.wait_for_completion()
.result()
.model_dump()
)
Getting Insights
Previous Version
# Get insights
insights = media_dcr.publisher.get_insights()
New Version
# Get insights
insights = (
media_dcr.get_insights()
.wait_for_completion()
.result()
.model_dump()
)
Retrieving and Working with Audiences
Previous Version
# Call functions for a LAL audience
estimate_audience_size = media_dcr.advertiser.estimate_audience_size(
audience_name="shoes-lal"
)
audience_user_list = media_dcr.publisher.get_audience_user_list(audience_name="shoes-lal")
# Call functions for a rule-based audience
estimate_audience_size = media_dcr.publisher.estimate_audience_size(
audience_name="rule-based-audience"
)
audience_user_list = media_dcr.publisher.get_audience_user_list(audience_name="rule-based-audience")
New Version
# Get all audiences
audiences = (
media_dcr.get_audiences()
.wait_for_completion()
.result()
)
# Get specific audiences by name
lal_audience = audiences.get_custom_audience("shoes-lal")
# Call functions for LAL audience
estimate_audience_size = (
media_dcr.get_audience_size(lal_audience)
.wait_for_completion()
.result()
)
audience_user_list = (
media_dcr.get_audience_user_list(lal_audience)
.wait_for_completion()
.result()
)
# Call functions for rule-based audience
rb_audience = audiences.get_custom_audience("rule-based-audience")
estimate_audience_size = (
media_dcr.get_audience_size(rb_audience)
.wait_for_completion()
.result()
)
audience_user_list = (
media_dcr.get_audience_user_list(rb_audience)
.wait_for_completion()
.result()
)
If you encounter any issues during migration, please contact our customer support team for assistance at support@decentriq.com.