How to activate and pause line items in Google DV360 using Python

Use (real-time) triggers like (sports) events or weather conditions to automate your display and/or video campaigns in Google Display & Video 360 (DV360). This tutorial will show you how to automate these operations using Python and the DV360 API.

• Activate and pause DV360 line items, making use of the DV360 API and Python
• Activate manual triggers to quickly activate a line item, that will automatically pause after a configurable amount of time.
• The script can be scheduled using a serverless function like AWS Lamba / Google Cloud Functions or a tool like Apache Airflow.
• Go directly to the code

Practical use cases & business value

The new DV360 API (mid-2020) unlocked some interesting new features and actions became much more simpler to automate.

To give a few practical examples, using this functionality;

• (De)activate line items based on weather conditions
• (De)activate line items based on events like company / national events or sports matches (e.g. campaigns based on match outcomes)
• (De)activate line items based on sales or stock levels

Another interesting, related, feature are the "manual triggers"; a line-item can be activated quickly and it will automatically deactivate after a desired amount of time has passed (so no need to deactivate the line item trough the API or interface).

Think of;

• Activate line items when an event has started (and automatically deactivate after X time)
• Activate line items when a commercial has aired (and automatically deactivate after X time)

Line items with manual triggers will also work using our code example (two use cases provided), but you have to attach a manual trigger on the line item within the DV360 interface first.

Preparation & configuration

Before running the script, a few things need to be configured:

• Create a Google Cloud project when you don't have one already
• Activate the Google Display & Video 360 API within the Google Cloud Console

• Create a service account in the Google Cloud console to programmatically authenticate with the different Google services (without using a user account)
• Add the service account to your Google DV360 account and grant access rights to the correct advertiser accounts (I've used the "Standard" role but probably can be configured more accurate).

Changing the line item status

The Python script below will;

• Authenticate using a service account (change GOOGLE_JSON_KEYFILE to the location of your keyfile.json)
• Update a line-item based on advertiser-id, line-item-id and desired line-item status.
• Or activate a manual trigger based on advertiser-id and trigger-id (can be obtained in the DV360 interface when a trigger is created)

Keep your JSON key file secure!

View code on GitHub

1###################################################
2# Author    Krisjan Oldekamp / Stacktonic.com
3# Email     krisjan@stacktonic.com
4# Article   https://stacktonic.com/article/how-to-activate-and-pause-line-items-in-google-dv-360-using-python
5####################################################
6
7import os
8from urllib.error import HTTPError
9from googleapiclient import discovery
10from oauth2client.service_account import ServiceAccountCredentials
11
12####################################################
13# Settings
14####################################################
15
16GOOGLE_JSON_KEYFILE = "<your-keyfile>.json" # Google Cloud Platform Service Account JSON keyfile
17GOOGLE_DV360_API_VERSION = "v1"
18GOOGLE_DV360_API_SCOPES = ["https://www.googleapis.com/auth/display-video"]
19
20DV360_ADVERTISER_ID = "<your-dv360-advertiser-id>"
21
22####################################################
23
24# Google D&V360 API service
25def get_dv360_service():
26    credentials = ServiceAccountCredentials.from_json_keyfile_name(
27        GOOGLE_JSON_KEYFILE,
28        scopes=GOOGLE_DV360_API_SCOPES)
29
30    return discovery.build('displayvideo', GOOGLE_DV360_API_VERSION, credentials=credentials, cache_discovery=False)
31
32# Change DV360 Line Item status
33def update_lineitem_status(advertiser_id, line_item_id, status_new):
34
35    service = get_dv360_service()
36
37    status_dv360 = 'ENTITY_STATUS_ACTIVE' if status_new == 'ACTIVE' else 'ENTITY_STATUS_PAUSED'
38
39    line_item_obj = {
40        'entityStatus': status_dv360,
41    }
42
43    # Update the line item.
44    update_line_item = service.advertisers().lineItems().patch(
45        advertiserId=advertiser_id,
46        lineItemId=line_item_id,
47        updateMask="entityStatus",
48        body=line_item_obj
49    ).execute()
50
51    print("Lineitem " + line_item_id + " updated to " + status_dv360)
52
53# Activate a manual trigger
54def manual_trigger(advertiser_id, trigger_id):
55
56    service = get_dv360_service()
57
58    # Activate the trigger
59    update_line_item = service.advertisers().manualTriggers().activate(
60        advertiserId=advertiser_id,
61        triggerId=trigger_id
62    ).execute()
63
64    print("TriggerId " + trigger_id + " activated.")
65
66
67# Usecase 1: Update lineitem status
68
69line_item_id = "123" # DV360 Line-Item-ID
70line_item_status_new = "ACTIVE" # New status -> ACTIVE or PAUSED
71
72update_lineitem_status(DV360_ADVERTISER_ID, line_item_id, line_item_status_new)
73
74# Usecase 2: Activate a manual trigger (create and attach a manual trigger in the DV360 interface first)
75
76trigger_id = "123"
77
78manual_trigger(DV360_ADVERTISER_ID, trigger_id)

How to automate

There are endless ways to automate the script. The methods I've used;

• Wrapping the script in an Apache Airflow DAG
• Using a serverless function, like AWS Lambda or Google Cloud Functions. In our case, the Cloud function was triggered using Cloud Scheduler and the function fetched line-items and activation status from a Google Sheet.