Implement Custom Bidding

You can use the Display & Video 360 API to manage custom bidding implementations. You can create custom bidding algorithms, upload and verify individual scripts, and assign a specific algorithm to a resource as its bidding strategy.

This page describes how to create, update, and assign custom bidding algorithms with the Display & Video 360 API. Each section provides a code sample.

Create a Custom Bidding Algorithm

A CustomBiddingAlgorithm object represents an individual algorithm that you can assign to a line item for use in its bid strategy. This object has details on the algorithm such as its customBiddingAlgorithmType, entityStatus and customBiddingAlgorithmState. You can create CustomBiddingScript objects as child resources for the algorithm to use.

Note: This guide focuses on script-based custom bidding algorithms. Algorithms created in Ads Data Hub or through the Display & Video 360 UI Goal Builder tool can be retrieved and assigned, but not fully managed.

Here's an example of how to create a script-based custom bidding algorithm:

Python

# Create a custom bidding algorithm object.
custom_bidding_algorithm_obj = {
    'advertiserId': advertiser-id,
    'displayName': display-name,
    'entityStatus': 'ENTITY_STATUS_ACTIVE',
    'customBiddingAlgorithmType': 'SCRIPT_BASED'
}

# Create the custom bidding algorithm.
response = service.customBiddingAlgorithms().create(
    body=algorithm_obj
).execute()

# Display the new custom bidding algorithm.
print(f'The following Custom Bidding Algorithm was created: {response}')

Manage algorithm access

Custom bidding algorithms can be owned by a partner or an advertiser. Algorithms owned by a partner can be accessed and modified by that partner and any child advertisers listed in the sharedAdvertiserIds field. Algorithms owned by an advertiser can be accessed and modified by that advertiser and its parent partner, but cannot be shared with other advertisers.

Note: When creating a custom bidding algorithm, you must have read/write access to the partner or advertiser which you assign as the owner.

If you’re only using the algorithm for a single advertiser, assign the advertiser as the owner with the advertiserId field. Otherwise, assign the parent partner of the advertisers as the owner with the partnerId field, and give the advertisers access with the sharedAdvertiserIds field.

Upload a script

Once you’ve created a custom bidding algorithm, create a script for that algorithm to use. Script-based custom bidding algorithms employ user-provided scripts to evaluate the worth of an impression. Samples of simple scripts and a list of advanced fields are available through the Display & Video 360 Help Center.

The following sections teach you how to add a new or updated script to a custom bidding algorithm.

Retrieve a script resource location

First, retrieve an available resource location under the custom bidding algorithm resource with the customBiddingAlgorithms.uploadScript method. This request returns a CustomBiddingScriptRef object with a resource name. You can upload your script file to the location dictated by the resource name. Then use the custom bidding script reference object to create your script resource.

Here's an example of how to retrieve an available resource location:

Python

# Retrieve a usable custom bidding script reference
# object.
custom_bidding_script_ref = service.customBiddingAlgorithms().uploadScript(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

# Display the new custom bidding script reference object.
print('The following custom bidding script reference object was retrieved:'
      f'{custom_bidding_script_ref}')

Upload a script file

After retrieving an available resource location, upload your script file to that location in the Display & Video 360 system with the media.upload method. This method supports a simple upload that requires the query parameter uploadType=media.

Warning: Custom bidding scripts have a maximum file size of 7MB.

Here's an example of how to upload a script file given a retrieved custom bidding script reference object:

Python

# Create a media upload object.
media = MediaFileUpload(script-path)

# Create upload request.
upload_request = service.media().upload(
    resourceName=resource-name, media_body=media)

# Override response handler to expect null response.
upload_request.postproc = HttpRequest.null_postproc

# Upload script to resource location given in retrieved custom bidding
# script reference object.
upload_request.execute()

Create a script object

Once the script file is uploaded, create a custom bidding script resource with the customBiddingAlgorithms.scripts.create method. The CustomBiddingScript object passed in the request should only include the CustomBiddingScriptRef object as the assigned value of the script field. This associates the uploaded script file with the new script resource.

Warning: If your uploaded script file has a syntax error, your customBiddingAlgorithms.scripts.create request will fail and return details on the syntax error found. To upload a fixed script file, you must restart this process by retrieving a new script resource location.

Here's an example of how to create a script file:

Python

# Create a custom bidding script object.
script_obj = {
    'script': custom-bidding-script-ref
}

# Create the custom bidding script.
response = service.customBiddingAlgorithms().scripts().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=script_obj).execute()

# Display the new custom bidding script object.
print(f'The following custom bidding script was created: {response}')

Once you create a custom bidding script resource, Display & Video 360 processes the script to make sure that it can be successfully used to score impressions. Retrieve the state of this processing through the script object’s state field. Once the new script is accepted, the custom bidding algorithm begins using the script to score impression values. This happens immediately, so be sure that you want to update the algorithm before creating a new script resource.

Assign a Custom Bidding Algorithm

After you create a custom bidding algorithm, upload an accepted script, and meet the necessary requirements, you can assign your custom bidding algorithm to the bidding strategy of a line item or insertion order.

You can use custom bidding algorithms in maximize spend and performance goal bid strategies by assigning BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO and the custom bidding algorithm ID to the performanceGoalType and customBiddingAlgorithmId fields, respectively. Depending on the bid strategy, other bid parameters may be available or required.

Here's an example of how to update a line item to use a maximize spend bid strategy with a given custom bidding algorithm:

Python

# Create the new bid strategy object.
bidding_strategy = {
    'maximizeSpendAutoBid': {
        'performanceGoalType':
            'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO',
        'customBiddingAlgorithmId': custom-bidding-algorithm-id
    }
}

# Create a line item object assigning the new bid strategy.
line_item_obj = {'bidStrategy': bidding_strategy}

# Update the line item with a new bid strategy.
response = service.advertisers().lineItems().patch(
    advertiserId=advertiser-id,
    lineItemId=line-item-id,
    updateMask='bidStrategy',
    body=line_item_obj).execute()

# Display the line item's new bid strategy
print(f'Line Item {response["name"]} is now using the following bid'
     f' strategy: {response["bidStrategy"]}.')