4.4 Campaign Management

Introduction

---

It is important to give merchants the ability to make changes to their campaign after it's been created. The most critical aspects they should be able to change are as follows:

• Budget
• Status (pausing, enabling, removing)
• Geo-targeting (recommended but optional)
• Any other field that you included in the campaign creation interface

Note: if you opted for the redirect option, no API integration is required for campaign management.

UX Guidance

---

Show the campaigns list on the overview page and on a separate page as part of campaign performance reporting. Allow users to pause, delete and edit campaigns.

Editing a campaign should allow the merchant to modify the same fields that they provided input on during the creation of a campaign. An example for how this may look is shown below:

Tech Guidance

---

Once you have created a Performance Max for Retail campaign, you can mutate the following campaign settings:

• Campaign name
• Campaign budget
• Campaign status
• Campaign targeting criteria

You can find a detailed overview of how to mutate resources in the Developer's Guide. You can mutate a specific resource using the exposed service endpoint for mutating that resource (for example, CampaignService.MutateCampaigns) or mutate across multiple different resources using the bulk mutate functionality available using the GoogleAdsService.Mutate endpoint.

Where possible we recommend mutating in bulk to reduce the number of operations required to update a campaign. With this in mind you should design your architecture around using the GoogleAdsService.Mutate endpoint instead of individual resource endpoints. This also enables easier extension of functionality in the future.

The later examples assume you have the relevant ids already stored in your local database.

Campaign name

To update the name of a campaign, you need to mutate the Campaign.name field.

It must not contain any null (code point 0x0), NL line feed (code point 0xA) or carriage return (code point 0xD) characters.

Campaign budget

It is considered best practice to update an existing budget instead of replacing it with a new budget. This ensures that your campaign spends as expected and does not lead to over delivery.

You should only update the value of the budget and not mutate any other fields, increasing the value of the DAILY spend.

Python
budget_resource_name = client.get_service(
        "CampaignBudgetService"
    ).campaign_budget_path(customer_id, budget_id)

mutate_operation = client.get_type("MutateOperation")
campaign_budget = mutate_operation.campaign_budget_operation.update

campaign_budget.resource_name = budget_resource_name

# update the budget amount to the new value

campaign_budget.amount_micros = 50000000

client.copy_from(
    mutate_operation.campaign_budget_operation.update_mask,
    protobuf_helpers.field_mask(None, campaign_budget._pb),
)
return mutate_operation

Campaign status

To update the status (enable/pause/remove) of a campaign you need to mutate the Campaign.status field and assign the relevant status from the CampaignStatus enum.

You can find an example of mutating the campaign status in the sample code for update campaign.

Campaign criteria

When updating the campaign criteria you only need to provide the capability to update criteria that is exposed to the user, this is at minimum Geo-targeting and potentially Language targeting. You can find an example of updating a campaign criterion in the sample code for update campaign criterion bid modifier.

To update geo-targeting criteria you update the CampaignCriterion.location to the value of the new geo target constant.

Python
criterion_rname = client.get_service(
    "CampaignCriterionService"
    ).campaign_criterion_path(
    customer_id, campaign_id, criterion_id
)

mutate_operation = client.get_type("MutateOperation")
campaign_criterion = mutate_operation.campaign_criterion_operation.update

campaign_criterion.resource_name = criterion_rname

# Set the geo to the update geo targeting

campaign_criterion.location.geo_target_constant = (
   geo_target_constant_service.geo_target_constant_path("1022762")
) # Brooklyn

client.copy_from(
    mutate_operation.campaign_criterion_operation.update_mask,
    protobuf_helpers.field_mask(None, campaign_criterion._pb),
)
return mutate_operation

To update language targeting criteria you need to update the value of the CampaignCriterion.language value with the new language constant.

Python
campaign_criterion_service = client.get_service("CampaignCriterionService")

criterion_rname = campaign_criterion_service.campaign_criterion_path(
   customer_id, campaign_id, criterion_id
)

mutate_operation = client.get_type("MutateOperation")
campaign_criterion = mutate_operation.campaign_criterion_operation.update

campaign_criterion.resource_name = criterion_rname

# Set the language to the updated language
# For a list of all language codes, see:
# https://developers.google.com/google-ads/api/data/codes-formats#languages
campaign_criterion.language.language_constant = (
    googleads_service.language_constant_path("1000")
)  # English

client.copy_from(
    mutate_operation.campaign_criterion_operation.update_mask,
    protobuf_helpers.field_mask(None, campaign_criterion._pb),
)
return mutate_operation