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.