Java
// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.ads.googleads.examples.shoppingads;
import static com.google.ads.googleads.examples.utils.CodeSampleHelper.getPrintableDateTime;
import com.beust.jcommander.Parameter;
import com.google.ads.googleads.examples.utils.ArgumentNames;
import com.google.ads.googleads.examples.utils.CodeSampleParams;
import com.google.ads.googleads.lib.GoogleAdsClient;
import com.google.ads.googleads.lib.utils.FieldMasks;
import com.google.ads.googleads.v11.common.ImageAsset;
import com.google.ads.googleads.v11.common.LanguageInfo;
import com.google.ads.googleads.v11.common.LocationInfo;
import com.google.ads.googleads.v11.common.MaximizeConversionValue;
import com.google.ads.googleads.v11.common.TextAsset;
import com.google.ads.googleads.v11.enums.AdvertisingChannelTypeEnum.AdvertisingChannelType;
import com.google.ads.googleads.v11.enums.AssetFieldTypeEnum.AssetFieldType;
import com.google.ads.googleads.v11.enums.AssetGroupStatusEnum.AssetGroupStatus;
import com.google.ads.googleads.v11.enums.BudgetDeliveryMethodEnum.BudgetDeliveryMethod;
import com.google.ads.googleads.v11.enums.CampaignStatusEnum.CampaignStatus;
import com.google.ads.googleads.v11.enums.ConversionActionCategoryEnum.ConversionActionCategory;
import com.google.ads.googleads.v11.enums.ConversionOriginEnum.ConversionOrigin;
import com.google.ads.googleads.v11.enums.ListingGroupFilterTypeEnum.ListingGroupFilterType;
import com.google.ads.googleads.v11.enums.ListingGroupFilterVerticalEnum.ListingGroupFilterVertical;
import com.google.ads.googleads.v11.errors.GoogleAdsError;
import com.google.ads.googleads.v11.errors.GoogleAdsException;
import com.google.ads.googleads.v11.resources.Asset;
import com.google.ads.googleads.v11.resources.AssetGroup;
import com.google.ads.googleads.v11.resources.AssetGroupAsset;
import com.google.ads.googleads.v11.resources.AssetGroupListingGroupFilter;
import com.google.ads.googleads.v11.resources.Campaign;
import com.google.ads.googleads.v11.resources.Campaign.ShoppingSetting;
import com.google.ads.googleads.v11.resources.CampaignBudget;
import com.google.ads.googleads.v11.resources.CampaignConversionGoal;
import com.google.ads.googleads.v11.resources.CampaignCriterion;
import com.google.ads.googleads.v11.resources.CustomerConversionGoal;
import com.google.ads.googleads.v11.services.AssetGroupAssetOperation;
import com.google.ads.googleads.v11.services.AssetGroupListingGroupFilterOperation;
import com.google.ads.googleads.v11.services.AssetGroupOperation;
import com.google.ads.googleads.v11.services.AssetOperation;
import com.google.ads.googleads.v11.services.CampaignBudgetOperation;
import com.google.ads.googleads.v11.services.CampaignConversionGoalOperation;
import com.google.ads.googleads.v11.services.CampaignCriterionOperation;
import com.google.ads.googleads.v11.services.CampaignOperation;
import com.google.ads.googleads.v11.services.GoogleAdsRow;
import com.google.ads.googleads.v11.services.GoogleAdsServiceClient;
import com.google.ads.googleads.v11.services.GoogleAdsServiceClient.SearchPagedResponse;
import com.google.ads.googleads.v11.services.MutateGoogleAdsResponse;
import com.google.ads.googleads.v11.services.MutateOperation;
import com.google.ads.googleads.v11.services.MutateOperationResponse;
import com.google.ads.googleads.v11.utils.ResourceNames;
import com.google.common.collect.ImmutableList;
import com.google.common.io.ByteStreams;
import com.google.protobuf.ByteString;
import com.google.protobuf.Descriptors.FieldDescriptor;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.net.URL;
import java.util.ArrayList;
import java.util.List;
import java.util.Map.Entry;
import java.util.stream.Collectors;
import org.joda.time.DateTime;
/**
* This example shows how to create a Performance Max retail campaign.
*
* <p>This will be created for "All products".
*
* <p>For more information about Performance Max retail campaigns, see
* https://developers.google.com/google-ads/api/docs/performance-max/retail
*
* <p>Prerequisites: - You need to have access to a Merchant Center account. You can find
* instructions to create a Merchant Center account here:
* https://support.google.com/merchants/answer/188924. This account must be linked to your Google
* Ads account. The integration instructions can be found at:
* https://developers.google.com/google-ads/api/docs/shopping-ads/merchant-center - You need your
* Google Ads account to track conversions. The different ways to track conversions can be found
* here: https://support.google.com/google-ads/answer/1722054. - You must have at least one
* conversion action in the account. For more about conversion actions, see
* https://developers.google.com/google-ads/api/docs/conversions/overview#conversion_actions
*/
public class AddPerformanceMaxRetailCampaign {
// We specify temporary IDs that are specific to a single mutate request. Temporary IDs are always
// negative and unique within one mutate request.
//
// <p>See https://developers.google.com/google-ads/api/docs/mutating/best-practices for further
// details.
//
// <p>These temporary IDs are fixed because they are used in multiple places.
private static final int BUDGET_TEMPORARY_ID = -1;
private static final int PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID = -2;
private static final int ASSET_GROUP_TEMPORARY_ID = -3;
// There are also entities that will be created in the same request but do not
// need to be fixed temporary IDs because they are referenced only once.
private static long temporaryId = ASSET_GROUP_TEMPORARY_ID - 1;
private static class AddPerformanceMaxRetailCampaignParams extends CodeSampleParams {
@Parameter(names = ArgumentNames.CUSTOMER_ID, required = true)
private Long customerId;
@Parameter(
names = ArgumentNames.MERCHANT_CENTER_ACCOUNT_ID,
required = true,
description = "The Merchant Center account ID.")
private long merchantCenterAccountId;
@Parameter(
names = ArgumentNames.SALES_COUNTRY,
description = "The sales country of products to include in the campaign.")
private String salesCountry = "US";
@Parameter(
names = ArgumentNames.FINAL_URL,
required = true,
description =
"The final url for the generated ads. Must have the same domain as the Merchant Center"
+ " account.")
private String finalUrl;
}
public static void main(String[] args) throws IOException {
AddPerformanceMaxRetailCampaignParams params = new AddPerformanceMaxRetailCampaignParams();
if (!params.parseArguments(args)) {
// Either pass the required parameters for this example on the command line, or insert them
// into the code here. See the parameter class definition above for descriptions.
params.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
params.merchantCenterAccountId = Long.parseLong("INSERT_MERCHANT_CENTER_ACCOUNT_ID_HERE");
params.finalUrl = "INSERT_FINAL_URL_HERE";
// Optionally set the sales country.
// params.salesCountry = "INSERT_SALES_COUNTRY_HERE";
}
GoogleAdsClient googleAdsClient = null;
try {
googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
System.err.printf(
"Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
System.exit(1);
} catch (IOException ioe) {
System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
System.exit(1);
}
try {
new AddPerformanceMaxRetailCampaign()
.runExample(
googleAdsClient,
params.customerId,
params.merchantCenterAccountId,
params.salesCountry,
params.finalUrl);
} catch (GoogleAdsException gae) {
// GoogleAdsException is the base class for most exceptions thrown by an API request.
// Instances of this exception have a message and a GoogleAdsFailure that contains a
// collection of GoogleAdsErrors that indicate the underlying causes of the
// GoogleAdsException.
System.err.printf(
"Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
gae.getRequestId());
int i = 0;
for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
System.err.printf(" Error %d: %s%n", i++, googleAdsError);
}
System.exit(1);
}
}
/**
* Runs the example.
*
* @param googleAdsClient the Google Ads API client.
* @param customerId the client customer ID.
* @param merchantCenterAccountId the Merchant Center account ID.
* @param salesCountry sales country of products to include in the campaign.
* @param finalUrl final URL for the asset group of the campaign.
*/
private void runExample(
GoogleAdsClient googleAdsClient,
long customerId,
long merchantCenterAccountId,
String salesCountry,
String finalUrl)
throws IOException {
// This campaign will override the customer conversion goals. For more information see
// https://developers.google.com/google-ads/api/docs/conversions/goals/campaign-goals.
// Retrieve the current list of customer conversion goals.
List<CustomerConversionGoal> customerConversionGoals =
getCustomerConversionGoals(googleAdsClient, customerId);
// Performance Max campaigns require that repeated assets such as headlines
// and descriptions be created before the campaign.
// For the list of required assets for a Performance Max campaign, see
// https://developers.google.com/google-ads/api/docs/performance-max/assets
//
// Creates the headlines.
List<String> headlines = ImmutableList.of("Travel", "Travel Reviews", "Book travel");
List<String> headlineAssetResourceNames =
createMultipleTextAssets(googleAdsClient, customerId, headlines);
// Creates the descriptions.
List<String> descriptions = ImmutableList.of("Take to the air!", "Fly to the sky!");
List<String> descriptionAssetResourceNames =
createMultipleTextAssets(googleAdsClient, customerId, descriptions);
// The below methods create and return MutateOperations that we later
// provide to the GoogleAdsService.Mutate method in order to create the
// entities in a single request. Since the entities for a Performance Max
// campaign are closely tied to one-another, it's considered a best practice
// to create them in a single Mutate request, so they all complete
// successfully or fail entirely, leaving no orphaned entities. See:
// https://developers.google.com/google-ads/api/docs/mutating/overview
List<MutateOperation> mutateOperations = new ArrayList<>();
mutateOperations.add(createCampaignBudgetOperation(customerId));
mutateOperations.add(
createPerformanceMaxCampaignOperation(customerId, merchantCenterAccountId, salesCountry));
mutateOperations.addAll(createCampaignCriterionOperations(customerId));
String assetGroupResourceName = ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID);
mutateOperations.addAll(
createAssetGroupOperations(
customerId,
assetGroupResourceName,
headlineAssetResourceNames,
descriptionAssetResourceNames,
finalUrl));
mutateOperations.addAll(createConversionGoalOperations(customerId, customerConversionGoals));
// Retail Performance Max campaigns require listing groups, which are created via the
// AssetGroupListingGroupFilter resource.
mutateOperations.add(createAssetGroupListingGroupFilterOperation(assetGroupResourceName));
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
MutateGoogleAdsResponse response =
googleAdsServiceClient.mutate(Long.toString(customerId), mutateOperations);
printResponseDetails(response);
}
}
/** Creates a MutateOperation that creates a new CampaignBudget. */
private MutateOperation createCampaignBudgetOperation(long customerId) {
CampaignBudget campaignBudget =
CampaignBudget.newBuilder()
.setName("Performance Max retail campaign budget #" + getPrintableDateTime())
// The budget period already defaults to DAILY.
.setAmountMicros(50_000_000)
.setDeliveryMethod(BudgetDeliveryMethod.STANDARD)
// A Performance Max campaign cannot use a shared campaign budget.
.setExplicitlyShared(false)
// Set a temporary ID in the budget's resource name, so it can be referenced
// by the campaign in later steps.
.setResourceName(ResourceNames.campaignBudget(customerId, BUDGET_TEMPORARY_ID))
.build();
return MutateOperation.newBuilder()
.setCampaignBudgetOperation(
CampaignBudgetOperation.newBuilder().setCreate(campaignBudget).build())
.build();
}
/** Creates a MutateOperation that creates a new Performance Max campaign. */
private MutateOperation createPerformanceMaxCampaignOperation(
long customerId, long merchantCenterAccountId, String salesCountry) {
Campaign performanceMaxCampaign =
Campaign.newBuilder()
.setName("Performance Max retail campaign #" + getPrintableDateTime())
// Sets the campaign status as PAUSED. The campaign is the only entity in
// the mutate request that should have its status set.
.setStatus(CampaignStatus.PAUSED)
// All Performance Max campaigns have an advertising_channel_type of
// PERFORMANCE_MAX. The advertising_channel_sub_type should not be set.
.setAdvertisingChannelType(AdvertisingChannelType.PERFORMANCE_MAX)
// Bidding strategy must be set directly on the campaign.
// Setting a portfolio bidding strategy by resource name is not supported.
// Max Conversion and Maximize Conversion Value are the only strategies
// supported for Performance Max campaigns.
// An optional ROAS (Return on Advertising Spend) can be set for
// maximize_conversion_value. The ROAS value must be specified as a ratio in
// the API. It is calculated by dividing "total value" by "total spend".
// For more information on Maximize Conversion Value, see the support
// article: http://support.google.com/google-ads/answer/7684216.
// A targetRoas of 3.5 corresponds to a 350% return on ad spend.
.setMaximizeConversionValue(
MaximizeConversionValue.newBuilder().setTargetRoas(3.5).build())
// Sets the shopping settings.
.setShoppingSetting(
ShoppingSetting.newBuilder()
.setMerchantId(merchantCenterAccountId)
.setSalesCountry(salesCountry)
.build())
// Sets the Final URL expansion opt out. This flag is specific to
// Performance Max campaigns. If opted out (true), only the final URLs in
// the asset group or URLs specified in the advertiser's Google Merchant
// Center or business data feeds are targeted.
//
// If opted in (false), the entire domain will be targeted. For best
// results, set this value to false to opt in and allow URL expansions. You
// can optionally add exclusions to limit traffic to parts of your website.
//
// Sets to true for this Retail campaign so the final URLs will be limited to those
// explicitly surfaced via Google Merchant Center.
.setUrlExpansionOptOut(true)
// Assigns the resource name with a temporary ID.
.setResourceName(
ResourceNames.campaign(customerId, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID))
// Sets the budget using the given budget resource name.
.setCampaignBudget(ResourceNames.campaignBudget(customerId, BUDGET_TEMPORARY_ID))
// Optional fields.
.setStartDate(new DateTime().plusDays(1).toString("yyyyMMdd"))
.setEndDate(new DateTime().plusDays(365).toString("yyyyMMdd"))
.build();
return MutateOperation.newBuilder()
.setCampaignOperation(
CampaignOperation.newBuilder().setCreate(performanceMaxCampaign).build())
.build();
}
/** Creates a list of MutateOperations that create new campaign criteria. */
private List<MutateOperation> createCampaignCriterionOperations(long customerId) {
String campaignResourceName =
ResourceNames.campaign(customerId, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID);
List<CampaignCriterion> campaignCriteria = new ArrayList<>();
// Sets the LOCATION campaign criteria.
// Targets all of New York City except Brooklyn.
// Location IDs are listed here:
// https://developers.google.com/google-ads/api/reference/data/geotargets
// and they can also be retrieved using the GeoTargetConstantService as shown
// here: https://developers.google.com/google-ads/api/docs/targeting/location-targeting
//
// We will add one positive location target for New York City (ID=1023191)
// and one negative location target for Brooklyn (ID=1022762).
// First, adds the positive (negative = False) for New York City.
campaignCriteria.add(
CampaignCriterion.newBuilder()
.setCampaign(campaignResourceName)
.setLocation(
LocationInfo.newBuilder()
.setGeoTargetConstant(ResourceNames.geoTargetConstant(1023191))
.build())
.setNegative(false)
.build());
// Next adds the negative target for Brooklyn.
campaignCriteria.add(
CampaignCriterion.newBuilder()
.setCampaign(campaignResourceName)
.setLocation(
LocationInfo.newBuilder()
.setGeoTargetConstant(ResourceNames.geoTargetConstant(1022762))
.build())
.setNegative(true)
.build());
// Sets the LANGUAGE campaign criterion.
campaignCriteria.add(
CampaignCriterion.newBuilder()
.setCampaign(campaignResourceName)
// Sets the language.
// For a list of all language codes, see:
// https://developers.google.com/google-ads/api/reference/data/codes-formats#expandable-7
.setLanguage(
LanguageInfo.newBuilder()
.setLanguageConstant(ResourceNames.languageConstant(1000)) // English
.build())
.build());
// Returns a list of mutate operations with one operation per criterion.
return campaignCriteria.stream()
.map(
criterion ->
MutateOperation.newBuilder()
.setCampaignCriterionOperation(
CampaignCriterionOperation.newBuilder().setCreate(criterion).build())
.build())
.collect(Collectors.toList());
}
/** Creates multiple text assets and returns the list of resource names. */
private List<String> createMultipleTextAssets(
GoogleAdsClient googleAdsClient, long customerId, List<String> texts) {
List<MutateOperation> mutateOperations = new ArrayList<>();
for (String text : texts) {
Asset asset = Asset.newBuilder().setTextAsset(TextAsset.newBuilder().setText(text)).build();
AssetOperation assetOperation = AssetOperation.newBuilder().setCreate(asset).build();
mutateOperations.add(MutateOperation.newBuilder().setAssetOperation(assetOperation).build());
}
List<String> assetResourceNames = new ArrayList<>();
// Creates the service client.
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
// Sends the operations in a single Mutate request.
MutateGoogleAdsResponse response =
googleAdsServiceClient.mutate(Long.toString(customerId), mutateOperations);
for (MutateOperationResponse result : response.getMutateOperationResponsesList()) {
if (result.hasAssetResult()) {
assetResourceNames.add(result.getAssetResult().getResourceName());
}
}
printResponseDetails(response);
}
return assetResourceNames;
}
/** Creates a list of MutateOperations that create a new AssetGroup. */
private List<MutateOperation> createAssetGroupOperations(
long customerId,
String assetGroupResourceName,
List<String> headlineAssetResourceNames,
List<String> descriptionAssetResourceNames,
String finalUrl)
throws IOException {
List<MutateOperation> mutateOperations = new ArrayList<>();
String campaignResourceName =
ResourceNames.campaign(customerId, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID);
// Creates the AssetGroup.
AssetGroup assetGroup =
AssetGroup.newBuilder()
.setName("Performance Max retail asset group #" + getPrintableDateTime())
.setCampaign(campaignResourceName)
.addFinalUrls(finalUrl)
.addFinalMobileUrls(finalUrl)
.setStatus(AssetGroupStatus.PAUSED)
.setResourceName(assetGroupResourceName)
.build();
AssetGroupOperation assetGroupOperation =
AssetGroupOperation.newBuilder().setCreate(assetGroup).build();
mutateOperations.add(
MutateOperation.newBuilder().setAssetGroupOperation(assetGroupOperation).build());
// For the list of required assets for a Performance Max campaign, see
// https://developers.google.com/google-ads/api/docs/performance-max/assets
// An AssetGroup is linked to an Asset by creating a new AssetGroupAsset
// and providing:
// the resource name of the AssetGroup
// the resource name of the Asset
// the field_type of the Asset in this AssetGroup.
// To learn more about AssetGroups, see
// https://developers.google.com/google-ads/api/docs/performance-max/asset-groups
// Links the previously created multiple text assets.
// Links the headline assets.
for (String resourceName : headlineAssetResourceNames) {
AssetGroupAsset assetGroupAsset =
AssetGroupAsset.newBuilder()
.setFieldType(AssetFieldType.HEADLINE)
.setAssetGroup(assetGroupResourceName)
.setAsset(resourceName)
.build();
AssetGroupAssetOperation assetGroupAssetOperation =
AssetGroupAssetOperation.newBuilder().setCreate(assetGroupAsset).build();
mutateOperations.add(
MutateOperation.newBuilder()
.setAssetGroupAssetOperation(assetGroupAssetOperation)
.build());
}
// Links the description assets.
for (String resourceName : descriptionAssetResourceNames) {
AssetGroupAsset assetGroupAsset =
AssetGroupAsset.newBuilder()
.setFieldType(AssetFieldType.DESCRIPTION)
.setAssetGroup(assetGroupResourceName)
.setAsset(resourceName)
.build();
AssetGroupAssetOperation assetGroupAssetOperation =
AssetGroupAssetOperation.newBuilder().setCreate(assetGroupAsset).build();
mutateOperations.add(
MutateOperation.newBuilder()
.setAssetGroupAssetOperation(assetGroupAssetOperation)
.build());
}
// Creates and links the long headline text asset.
mutateOperations.addAll(
createAndLinkTextAsset(
customerId, assetGroupResourceName, "Travel the World", AssetFieldType.LONG_HEADLINE));
// Creates and links the business name text asset.
mutateOperations.addAll(
createAndLinkTextAsset(
customerId,
assetGroupResourceName,
"Interplanetary Cruises",
AssetFieldType.BUSINESS_NAME));
// Creates and links the image assets.
// Creates and links the Logo Asset.
mutateOperations.addAll(
createAndLinkImageAsset(
customerId,
assetGroupResourceName,
"https://gaagl.page.link/bjYi",
AssetFieldType.LOGO,
"Logo Image"));
// Creates and links the Marketing Image Asset.
mutateOperations.addAll(
createAndLinkImageAsset(
customerId,
assetGroupResourceName,
"https://gaagl.page.link/Eit5",
AssetFieldType.MARKETING_IMAGE,
"Marketing Image"));
// Creates and links the Square Marketing Image Asset.
mutateOperations.addAll(
createAndLinkImageAsset(
customerId,
assetGroupResourceName,
"https://gaagl.page.link/bjYi",
AssetFieldType.SQUARE_MARKETING_IMAGE,
"Square Marketing Image"));
return mutateOperations;
}
/** Creates a list of MutateOperations that create a new linked text asset. */
List<MutateOperation> createAndLinkTextAsset(
long customerId, String assetGroupResourceName, String text, AssetFieldType assetFieldType) {
List<MutateOperation> mutateOperations = new ArrayList<>();
String assetResourceName = ResourceNames.asset(customerId, getNextTemporaryId());
// Creates the Text Asset.
Asset asset =
Asset.newBuilder()
.setResourceName(assetResourceName)
.setTextAsset(TextAsset.newBuilder().setText(text).build())
.build();
AssetOperation assetOperation = AssetOperation.newBuilder().setCreate(asset).build();
mutateOperations.add(MutateOperation.newBuilder().setAssetOperation(assetOperation).build());
// Creates an AssetGroupAsset to link the Asset to the AssetGroup.
AssetGroupAsset assetGroupAsset =
AssetGroupAsset.newBuilder()
.setFieldType(assetFieldType)
.setAssetGroup(assetGroupResourceName)
.setAsset(assetResourceName)
.build();
AssetGroupAssetOperation assetGroupAssetOperation =
AssetGroupAssetOperation.newBuilder().setCreate(assetGroupAsset).build();
mutateOperations.add(
MutateOperation.newBuilder().setAssetGroupAssetOperation(assetGroupAssetOperation).build());
return mutateOperations;
}
/** Creates a list of MutateOperations that create a new linked image asset. */
List<MutateOperation> createAndLinkImageAsset(
long customerId,
String assetGroupResourceName,
String url,
AssetFieldType assetFieldType,
String assetName)
throws IOException {
List<MutateOperation> mutateOperations = new ArrayList<>();
String assetResourceName = ResourceNames.asset(customerId, getNextTemporaryId());
// Creates a media file.
byte[] assetBytes = ByteStreams.toByteArray(new URL(url).openStream());
// Creates the Image Asset.
Asset asset =
Asset.newBuilder()
.setResourceName(assetResourceName)
.setImageAsset(ImageAsset.newBuilder().setData(ByteString.copyFrom(assetBytes)).build())
// Provides a unique friendly name to identify your asset. When there is an existing
// image asset with the same content but a different name, the new name will be dropped
// silently.
.setName(assetName)
.build();
AssetOperation assetOperation = AssetOperation.newBuilder().setCreate(asset).build();
mutateOperations.add(MutateOperation.newBuilder().setAssetOperation(assetOperation).build());
// Creates an AssetGroupAsset to link the Asset to the AssetGroup.
AssetGroupAsset assetGroupAsset =
AssetGroupAsset.newBuilder()
.setFieldType(assetFieldType)
.setAssetGroup(assetGroupResourceName)
.setAsset(assetResourceName)
.build();
AssetGroupAssetOperation assetGroupAssetOperation =
AssetGroupAssetOperation.newBuilder().setCreate(assetGroupAsset).build();
mutateOperations.add(
MutateOperation.newBuilder().setAssetGroupAssetOperation(assetGroupAssetOperation).build());
return mutateOperations;
}
/** Retrieves the list of customer conversion goals. */
private static List<CustomerConversionGoal> getCustomerConversionGoals(
GoogleAdsClient googleAdsClient, long customerId) {
String query =
"SELECT customer_conversion_goal.category, customer_conversion_goal.origin "
+ "FROM customer_conversion_goal";
List<CustomerConversionGoal> customerConversionGoals = new ArrayList<>();
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
// The number of conversion goals is typically less than 50, so we use
// GoogleAdsService.search instead of search_stream.
SearchPagedResponse response =
googleAdsServiceClient.search(Long.toString(customerId), query);
for (GoogleAdsRow googleAdsRow : response.iterateAll()) {
customerConversionGoals.add(googleAdsRow.getCustomerConversionGoal());
}
}
return customerConversionGoals;
}
/** Creates a list of MutateOperations that override customer conversion goals. */
private static List<MutateOperation> createConversionGoalOperations(
long customerId, List<CustomerConversionGoal> customerConversionGoals) {
List<MutateOperation> mutateOperations = new ArrayList<>();
// To override the customer conversion goals, we will change the
// biddability of each of the customer conversion goals so that only
// the desired conversion goal is biddable in this campaign.
for (CustomerConversionGoal customerConversionGoal : customerConversionGoals) {
ConversionActionCategory category = customerConversionGoal.getCategory();
ConversionOrigin origin = customerConversionGoal.getOrigin();
String campaignConversionGoalResourceName =
ResourceNames.campaignConversionGoal(
customerId, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID, category, origin);
CampaignConversionGoal.Builder campaignConversionGoalBuilder =
CampaignConversionGoal.newBuilder().setResourceName(campaignConversionGoalResourceName);
// Change the biddability for the campaign conversion goal.
// Set biddability to True for the desired (category, origin).
// Set biddability to False for all other conversion goals.
// Note:
// 1- It is assumed that this Conversion Action
// (category=PURCHASE, origin=WEBSITE) exists in this account.
// 2- More than one goal can be biddable if desired. This example
// shows only one.
if (category == ConversionActionCategory.PURCHASE && origin == ConversionOrigin.WEBSITE) {
campaignConversionGoalBuilder.setBiddable(true);
} else {
campaignConversionGoalBuilder.setBiddable(false);
}
CampaignConversionGoal campaignConversionGoal = campaignConversionGoalBuilder.build();
CampaignConversionGoalOperation campaignConversionGoalOperation =
CampaignConversionGoalOperation.newBuilder()
.setUpdate(campaignConversionGoal)
.setUpdateMask(FieldMasks.allSetFieldsOf(campaignConversionGoal))
.build();
mutateOperations.add(
MutateOperation.newBuilder()
.setCampaignConversionGoalOperation(campaignConversionGoalOperation)
.build());
}
return mutateOperations;
}
/** Creates a MutateOperation that creates a new asset group listing group filter. */
private MutateOperation createAssetGroupListingGroupFilterOperation(
String assetGroupResourceName) {
// Creates a new asset group listing group filter containing the "default" listing group (All
// products).
AssetGroupListingGroupFilter listingGroupFilter =
AssetGroupListingGroupFilter.newBuilder()
.setAssetGroup(assetGroupResourceName)
// Does not set the parentListingGroupFilter since this is the root node. For all other
// nodes, this would refer to the parent listing group filter resource name.
// .setParentListingGroupFilter("<PARENT FILTER RESOURCE NAME>")
// Sets the type to UNIT_INCLUDED since this node has no children.
.setType(ListingGroupFilterType.UNIT_INCLUDED)
// Specifies that this is in the SHOPPING vertical, as required for a Performance Max
// retail campaign.
.setVertical(ListingGroupFilterVertical.SHOPPING)
.build();
// Returns an operation to the list to create the listing group filter.
return MutateOperation.newBuilder()
.setAssetGroupListingGroupFilterOperation(
AssetGroupListingGroupFilterOperation.newBuilder().setCreate(listingGroupFilter))
.build();
}
/**
* Prints the details of a MutateGoogleAdsResponse.
*
* <p>Parses the "response" oneof field name and uses it to extract the new entity's name and
* resource name.
*/
private void printResponseDetails(MutateGoogleAdsResponse response) {
// Parses the Mutate response to print details about the entities that were created by the
// request.
String suffix = "_result";
for (MutateOperationResponse result : response.getMutateOperationResponsesList()) {
for (Entry<FieldDescriptor, Object> responseFields : result.getAllFields().entrySet()) {
String fieldName = responseFields.getKey().getName();
String value = responseFields.getValue().toString().trim();
if (fieldName.endsWith(suffix)) {
fieldName = fieldName.substring(0, fieldName.length() - suffix.length());
}
System.out.printf("Created a(n) %s with %s.%n", fieldName, value);
}
}
}
/** Returns the next temporary ID and decreases it by one. */
private long getNextTemporaryId() {
return temporaryId--;
}
}
C#
// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
using CommandLine;
using Google.Ads.Gax.Examples;
using Google.Ads.Gax.Util;
using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.Util;
using Google.Ads.GoogleAds.V11.Common;
using Google.Ads.GoogleAds.V11.Errors;
using Google.Ads.GoogleAds.V11.Resources;
using Google.Ads.GoogleAds.V11.Services;
using Google.Api.Gax;
using Google.Protobuf;
using System.Collections.Generic;
using System;
using System.Threading;
using static Google.Ads.GoogleAds.V11.Enums.ConversionActionCategoryEnum.Types;
using static Google.Ads.GoogleAds.V11.Enums.ConversionOriginEnum.Types;
using static Google.Ads.GoogleAds.V11.Enums.AdvertisingChannelTypeEnum.Types;
using static Google.Ads.GoogleAds.V11.Enums.AssetFieldTypeEnum.Types;
using static Google.Ads.GoogleAds.V11.Enums.AssetGroupStatusEnum.Types;
using static Google.Ads.GoogleAds.V11.Enums.BudgetDeliveryMethodEnum.Types;
using static Google.Ads.GoogleAds.V11.Enums.CampaignStatusEnum.Types;
using static Google.Ads.GoogleAds.V11.Enums.ListingGroupFilterTypeEnum.Types;
using static Google.Ads.GoogleAds.V11.Enums.ListingGroupFilterVerticalEnum.Types;
using static Google.Ads.GoogleAds.V11.Resources.Campaign.Types;
using Google.Ads.GoogleAds.Config;
namespace Google.Ads.GoogleAds.Examples.V11
{
/// <summary>
/// This example shows how to create a Performance Max retail campaign.
///
/// This will be created for "All products".
///
/// For more information about Performance Max retail campaigns, see
/// https://developers.google.com/google-ads/api/docs/performance-max/retail
///
/// Prerequisites:
/// - You need to have access to a Merchant Center account. You can find
/// instructions to create a Merchant Center account here:
/// https://support.google.com/merchants/answer/188924.
/// This account must be linked to your Google Ads account. The integration
/// instructions can be found at:
/// https://developers.google.com/google-ads/api/docs/shopping-ads/merchant-center
/// - You need your Google Ads account to track conversions. The different ways
/// to track conversions can be found here:
/// https://support.google.com/google-ads/answer/1722054.
/// - You must have at least one conversion action in the account. For
/// more about conversion actions, see
/// https://developers.google.com/google-ads/api/docs/conversions/overview#conversion_actions
/// </summary>
public class AddPerformanceMaxRetailCampaign : ExampleBase
{
/// <summary>
/// Command line options for running the <see cref="AddPerformanceMaxRetailCampaign"/>
/// example.
/// </summary>
public class Options : OptionsBase
{
/// <summary>
/// The Google Ads customer ID.
/// </summary>
[Option("customerId", Required = true, HelpText =
"The Google Ads customer ID.")]
public long CustomerId { get; set; }
/// <summary>
/// The Merchant Center account ID.
/// </summary>
[Option("merchantCenterAccountId", Required = true, HelpText =
"The Merchant Center account ID.")]
public long MerchantCenterAccountId { get; set; }
/// <summary>
/// The sales country of products to include in the campaign.
/// </summary>
[Option("salesCountry", Required = true, HelpText =
"The sales country.")]
public string SalesCountry { get; set; }
/// <summary>
/// The final url for the generated ads. Must have the same domain as the Merchant
/// Center account.
/// </summary>
[Option("finalUrl", Required = true, HelpText =
"The final url for the generated ads." +
"Must have the same domain as the Merchant Center account.")]
public string FinalUrl { get; set; }
}
/// <summary>
/// Main method, to run this code example as a standalone application.
/// </summary>
/// <param name="args">The command line arguments.</param>
public static void Main(string[] args)
{
Options options = ExampleUtilities.ParseCommandLine<Options>(args);
AddPerformanceMaxRetailCampaign codeExample = new AddPerformanceMaxRetailCampaign();
Console.WriteLine(codeExample.Description);
codeExample.Run(
new GoogleAdsClient(),
options.CustomerId,
options.MerchantCenterAccountId,
options.SalesCountry,
options.FinalUrl
);
}
// We specify temporary IDs that are specific to a single mutate request. Temporary IDs are
// always negative and unique within one mutate request.
//
// See https://developers.google.com/google-ads/api/docs/mutating/best-practices for further
// details.
//
// These temporary IDs are fixed because they are used in multiple places.
private const int TEMPORARY_ID_BUDGET = -1;
private const int TEMPORARY_ID_CAMPAIGN = -2;
private const int TEMPORARY_ID_ASSET_GROUP = -3;
// There are also entities that will be created in the same request but do not need to be
// fixed temporary IDs because they are referenced only once.
private class AssetGroupAssetTemporaryResourceNameGenerator
{
private long customerId;
private long next;
public AssetGroupAssetTemporaryResourceNameGenerator(long customerId, long assetGroupId)
{
this.customerId = customerId;
this.next = assetGroupId - 1;
}
public string Next()
{
long i = next;
Interlocked.Decrement(ref next);
return ResourceNames.Asset(customerId, i);
}
}
/// <summary>
/// Returns a description about the code example.
/// </summary>
public override string Description =>
"This example shows how to create a Performance Max retail campaign.";
/// <summary>
/// Runs the code example.
/// </summary>
/// <param name="client">The Google Ads client.</param>
/// <param name="customerId">The Google Ads customer ID.</param>
/// <param name="merchantCenterAccountId">The Merchant Center account ID.</param>
/// <param name="salesCountry">The sales country.</param>
/// <param name="finalUrl">The final URL.</param>
public void Run(
GoogleAdsClient client,
long customerId,
long merchantCenterAccountId,
string salesCountry,
string finalUrl)
{
try
{
GoogleAdsServiceClient googleAdsServiceClient =
client.GetService(Services.V11.GoogleAdsService);
// This campaign will override the customer conversion goals.
// Retrieve the current list of customer conversion goals.
List<CustomerConversionGoal> customerConversionGoals =
GetCustomerConversionGoals(client, customerId);
// Performance Max campaigns require that repeated assets such as headlines and
// descriptions be created before the campaign.
//
// For the list of required assets for a Performance Max campaign, see
// https://developers.google.com/google-ads/api/docs/performance-max/assets
//
// Create the headlines.
List<string> headlineAssetResourceNames = CreateMultipleTextAssets(
client,
customerId,
new[] {
"Travel",
"Travel Reviews",
"Book travel"
}
);
// Create the descriptions.
List<string> descriptionAssetResourceNames = CreateMultipleTextAssets(
client,
customerId,
new[] {
"Take to the air!",
"Fly to the sky!"
}
);
string tempResourceNameCampaignBudget = ResourceNames.CampaignBudget(
customerId,
TEMPORARY_ID_BUDGET
);
string assetGroupResourceName = ResourceNames.AssetGroup(
customerId,
TEMPORARY_ID_ASSET_GROUP
);
// The below methods create and return MutateOperations that we later provide to the
// GoogleAdsService.Mutate method in order to create the entities in a single request.
// Since the entities for a Performance Max campaign are closely tied to one-another,
// it's considered a best practice to create them in a single Mutate request so they all
// complete successfully or fail entirely, leaving no orphaned entities.
//
// See: https://developers.google.com/google-ads/api/docs/mutating/overview
MutateOperation campaignBudgetOperation = CreateCampaignBudgetOperation(
tempResourceNameCampaignBudget
);
string tempResourceNameCampaign = ResourceNames.Campaign(
customerId,
TEMPORARY_ID_CAMPAIGN
);
MutateOperation performanceMaxCampaignOperation =
CreatePerformanceMaxCampaignOperation(
tempResourceNameCampaign,
tempResourceNameCampaignBudget,
merchantCenterAccountId,
salesCountry
);
List<MutateOperation> campaignCriterionOperations =
CreateCampaignCriterionOperations(tempResourceNameCampaign);
List<MutateOperation> assetGroupOperations =
CreateAssetGroupOperations(
tempResourceNameCampaign,
assetGroupResourceName,
finalUrl,
headlineAssetResourceNames,
descriptionAssetResourceNames,
new AssetGroupAssetTemporaryResourceNameGenerator(
customerId,
TEMPORARY_ID_ASSET_GROUP
),
client.Config
);
List<MutateOperation> conversionGoalOperations =
CreateCustomerConversionGoalOperations(
customerId,
customerConversionGoals
);
// Retail Performance Max campaigns require listing groups, which are created via the
// AssetGroupListingGroupFilter resource.
List<MutateOperation> assetGroupListingGroupOperations =
CreateAssetGroupListingGroupOperations(
assetGroupResourceName
);
MutateGoogleAdsRequest request = new MutateGoogleAdsRequest
{
CustomerId = customerId.ToString()
};
// It's important to create these entities in this order because they depend on
// each other.
//
// Additionally, we take several lists of operations and flatten them into one
// large list.
request.MutateOperations.Add(campaignBudgetOperation);
request.MutateOperations.Add(performanceMaxCampaignOperation);
request.MutateOperations.AddRange(campaignCriterionOperations);
request.MutateOperations.AddRange(assetGroupOperations);
request.MutateOperations.AddRange(conversionGoalOperations);
request.MutateOperations.AddRange(assetGroupListingGroupOperations);
MutateGoogleAdsResponse response = googleAdsServiceClient.Mutate(request);
PrintResponseDetails(response);
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
/// <summary>
/// Creates a MutateOperation that creates a new CampaignBudget.
///
/// A temporary ID will be assigned to this campaign budget so that it can be
/// referenced by other objects being created in the same Mutate request.
/// </summary>
/// <param name="budgetResourceName">The temporary resource name of the budget to
/// create.</param>
/// <returns>A MutateOperation that creates a CampaignBudget.</returns>
private MutateOperation CreateCampaignBudgetOperation(
string budgetResourceName)
{
MutateOperation operation = new MutateOperation
{
CampaignBudgetOperation = new CampaignBudgetOperation
{
Create = new CampaignBudget
{
Name = "Performance Max campaign budget #"
+ ExampleUtilities.GetRandomString(),
// The budget period already defaults to Daily.
AmountMicros = 50000000,
DeliveryMethod = BudgetDeliveryMethod.Standard,
// A Performance Max campaign cannot use a shared campaign budget.
ExplicitlyShared = false,
// Set a temporary ID in the budget's resource name so it can be referenced
// by the campaign in later steps.
ResourceName = budgetResourceName
}
}
};
return operation;
}
/// Creates a MutateOperation that creates a new Performance Max campaign.
/// <param name="campaignResourceName">The campaign resource name.</param>
/// <param name="campaignBudgetResourceName">The campaign budget resource name.</param>
/// <param name="merchantCenterAccountId">The Merchant Center account ID.</param>
/// <param name="salesCountry">The sales country.</param>
/// <returns>A MutateOperations that will create this new campaign.</returns>
private MutateOperation CreatePerformanceMaxCampaignOperation(
string campaignResourceName,
string campaignBudgetResourceName,
long merchantCenterAccountId,
string salesCountry)
{
MutateOperation operation = new MutateOperation()
{
CampaignOperation = new CampaignOperation()
{
Create = new Campaign()
{
Name = "Performance Max campaign #" + ExampleUtilities.GetRandomString(),
// Set the campaign status as PAUSED. The campaign is the only entity in
// the mutate request that should have its status set.
Status = CampaignStatus.Paused,
// All Performance Max campaigns have an advertising_channel_type of
// PERFORMANCE_MAX. The advertising_channel_sub_type should not be set.
AdvertisingChannelType = AdvertisingChannelType.PerformanceMax,
// Bidding strategy must be set directly on the campaign. Setting a
// portfolio bidding strategy by resource name is not supported. Max
// Conversion and Maximize Conversion Value are the only strategies
// supported for Performance Max campaigns. BiddingStrategyTYpe is
// read-only and cannot be set by the API. An optional ROAS (Return on
// Advertising Spend) can be set to enable the MaximizeConversionValue
// bidding strategy. The ROAS value must be specified as a ratio in the API.
// It is calculated by dividing "total value" by "total spend".
//
// For more information on Maximize Conversion Value, see the support
// article:
// http://support.google.com/google-ads/answer/7684216.
//
// A target_roas of 3.5 corresponds to a 350% return on ad spend.
MaximizeConversionValue = new MaximizeConversionValue()
{
TargetRoas = 3.5
},
ShoppingSetting = new ShoppingSetting()
{
MerchantId = merchantCenterAccountId,
SalesCountry = salesCountry
},
// Set the Final URL expansion opt out. This flag is specific to
// Performance Max campaigns. If opted out (True), only the final URLs in
// the asset group or URLs specified in the advertiser's Google Merchant
// Center or business data feeds are targeted.
//
// If opted in (False), the entire domain will be targeted. For best
// results, set this value to false to opt in and allow URL expansions. You
// can optionally add exclusions to limit traffic to parts of your website.
//
// For a Retail campaign, we want the final URL's to be limited to those
// explicitly surfaced via GMC.
UrlExpansionOptOut = true,
// Use the temporary resource name created earlier
ResourceName = campaignResourceName,
// Set the budget using the given budget resource name.
CampaignBudget = campaignBudgetResourceName,
// Optional fields
StartDate = DateTime.Now.AddDays(1).ToString("yyyyMMdd"),
EndDate = DateTime.Now.AddDays(365).ToString("yyyyMMdd")
}
}
};
return operation;
}
/// <summary>
/// Creates a list of MutateOperations that create new campaign criteria.
/// </summary>
/// <param name="campaignResourceName">The campaign resource name.</param>
/// <returns>A list of MutateOperations that create new campaign criteria.</returns>
private List<MutateOperation> CreateCampaignCriterionOperations(
string campaignResourceName)
{
List<MutateOperation> operations = new List<MutateOperation>();
// Set the LOCATION campaign criteria.
// Target all of New York City except Brooklyn.
// Location IDs are listed here:
// https://developers.google.com/google-ads/api/reference/data/geotargets
// and they can also be retrieved using the GeoTargetConstantService as shown
// here: https://developers.google.com/google-ads/api/docs/targeting/location-targeting
//
// We will add one positive location target for New York City (ID=1023191)
// and one negative location target for Brooklyn (ID=1022762).
// First, add the positive (negative = False) for New York City.
MutateOperation operation1 = new MutateOperation()
{
CampaignCriterionOperation = new CampaignCriterionOperation()
{
Create = new CampaignCriterion()
{
Campaign = campaignResourceName,
Location = new LocationInfo()
{
GeoTargetConstant = ResourceNames.GeoTargetConstant(1023191)
},
Negative = false
}
}
};
operations.Add(operation1);
// Next add the negative target for Brooklyn.
MutateOperation operation2 = new MutateOperation()
{
CampaignCriterionOperation = new CampaignCriterionOperation()
{
Create = new CampaignCriterion()
{
Campaign = campaignResourceName,
Location = new LocationInfo()
{
GeoTargetConstant = ResourceNames.GeoTargetConstant(1022762)
},
Negative = true
}
}
};
operations.Add(operation2);
// Set the LANGUAGE campaign criterion.
MutateOperation operation3 = new MutateOperation()
{
CampaignCriterionOperation = new CampaignCriterionOperation()
{
Create = new CampaignCriterion()
{
Campaign = campaignResourceName,
// Set the language.
// For a list of all language codes, see:
// https://developers.google.com/google-ads/api/reference/data/codes-formats#expandable-7
Language = new LanguageInfo()
{
LanguageConstant = ResourceNames.LanguageConstant(1000) // English
},
}
}
};
operations.Add(operation3);
return operations;
}
/// <summary>
/// Creates multiple text assets and returns the list of resource names.
/// </summary>
/// <param name="client">The Google Ads Client.</param>
/// <param name="customerId">The customer's ID.</param>
/// <param name="texts">The texts to add.</param>
/// <returns>A list of asset resource names.</returns>
private List<string> CreateMultipleTextAssets(
GoogleAdsClient client,
long customerId,
string[] texts)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsServiceClient =
client.GetService(Services.V11.GoogleAdsService);
MutateGoogleAdsRequest request = new MutateGoogleAdsRequest()
{
CustomerId = customerId.ToString()
};
foreach (string text in texts)
{
request.MutateOperations.Add(
new MutateOperation()
{
AssetOperation = new AssetOperation()
{
Create = new Asset()
{
TextAsset = new TextAsset()
{
Text = text
}
}
}
}
);
}
// Send the operations in a single Mutate request.
MutateGoogleAdsResponse response = googleAdsServiceClient.Mutate(request);
List<string> assetResourceNames = new List<string>();
foreach (MutateOperationResponse operationResponse in response.MutateOperationResponses)
{
MutateAssetResult assetResult = operationResponse.AssetResult;
assetResourceNames.Add(assetResult.ResourceName);
}
PrintResponseDetails(response);
return assetResourceNames;
}
/// <summary>
/// Creates a list of MutateOperations that create a new asset_group.
/// </summary>
/// <param name="campaignResourceName">The campaign resource name.</param>
/// <param name="assetGroupResourceName">The asset group resource name.</param>
/// <param name="finalUrl">The final url.</param>
/// <param name="headlineAssetResourceNames">The headline asset resource names.</param>
/// <param name="descriptionAssetResourceNames">The description asset resource
/// names.</param>
/// <param name="resourceNameGenerator">A generator for unique temporary ID's.</param>
/// <param name="config">The Google Ads config.</param>
/// <returns>A list of MutateOperations that create the new asset group.</returns>
private List<MutateOperation> CreateAssetGroupOperations(
string campaignResourceName,
string assetGroupResourceName,
string finalUrl,
List<string> headlineAssetResourceNames,
List<string> descriptionAssetResourceNames,
AssetGroupAssetTemporaryResourceNameGenerator resourceNameGenerator,
GoogleAdsConfig config)
{
List<MutateOperation> operations = new List<MutateOperation>();
// Create the AssetGroup
operations.Add(
new MutateOperation()
{
AssetGroupOperation = new AssetGroupOperation()
{
Create = new AssetGroup()
{
Name = "Performance Max asset group #" +
ExampleUtilities.GetRandomString(),
Campaign = campaignResourceName,
FinalUrls = { finalUrl },
FinalMobileUrls = { finalUrl },
Status = AssetGroupStatus.Paused,
ResourceName = assetGroupResourceName
}
}
}
);
// For the list of required assets for a Performance Max campaign, see
// https://developers.google.com/google-ads/api/docs/performance-max/assets
// An AssetGroup is linked to an Asset by creating a new AssetGroupAsset
// and providing:
// the resource name of the AssetGroup
// the resource name of the Asset
// the field_type of the Asset in this AssetGroup.
//
// To learn more about AssetGroups, see
// https://developers.google.com/google-ads/api/docs/performance-max/asset-groups
// Link the previously created multiple text assets.
// Link the headline assets.
foreach (string resourceName in headlineAssetResourceNames)
{
operations.Add(
new MutateOperation()
{
AssetGroupAssetOperation = new AssetGroupAssetOperation()
{
Create = new AssetGroupAsset()
{
FieldType = AssetFieldType.Headline,
AssetGroup = assetGroupResourceName,
Asset = resourceName
}
}
}
);
}
// Link the description assets.
foreach (string resourceName in descriptionAssetResourceNames)
{
operations.Add(
new MutateOperation()
{
AssetGroupAssetOperation = new AssetGroupAssetOperation()
{
Create = new AssetGroupAsset()
{
FieldType = AssetFieldType.Description,
AssetGroup = assetGroupResourceName,
Asset = resourceName
}
}
}
);
}
// Create and link the long headline text asset.
operations.AddRange(
CreateAndLinkTextAsset(
assetGroupResourceName,
resourceNameGenerator.Next(),
"Travel the World",
AssetFieldType.LongHeadline
)
);
// Create and link the business name text asset.
operations.AddRange(
CreateAndLinkTextAsset(
assetGroupResourceName,
resourceNameGenerator.Next(),
"Interplanetary Cruises",
AssetFieldType.BusinessName
)
);
// Create and link the image assets.
// Create and link the Logo Asset.
operations.AddRange(
CreateAndLinkImageAsset(
assetGroupResourceName,
resourceNameGenerator.Next(),
"https://gaagl.page.link/bjYi",
AssetFieldType.Logo,
"Logo Image",
config
)
);
// Create and link the Marketing Image Asset.
operations.AddRange(
CreateAndLinkImageAsset(
assetGroupResourceName,
resourceNameGenerator.Next(),
"https://gaagl.page.link/Eit5",
AssetFieldType.MarketingImage,
"Marketing Image",
config
)
);
// Create and link the Square Marketing Image Asset.
operations.AddRange(
CreateAndLinkImageAsset(
assetGroupResourceName,
resourceNameGenerator.Next(),
"https://gaagl.page.link/bjYi",
AssetFieldType.SquareMarketingImage,
"Square Marketing Image",
config
)
);
return operations;
}
/// <summary>
/// Creates a list of MutateOperations that create a new linked text asset.
/// </summary>
/// <param name="assetGroupResourceName">The resource name of the asset group to be
/// created.</param>
/// <param name="assetResourceName">The resource name of the text asset to be
/// created.</param>
/// <param name="text">The text of the asset to be created.</param>
/// <param name="fieldType">The field type of the asset to be created.</param>
/// <returns>A list of MutateOperations that create the new linked text asset.</returns>
private List<MutateOperation> CreateAndLinkTextAsset(
string assetGroupResourceName,
string assetResourceName,
string text,
AssetFieldType fieldType)
{
List<MutateOperation> operations = new List<MutateOperation>();
// Create the Text Asset.
operations.Add(
new MutateOperation()
{
AssetOperation = new AssetOperation()
{
Create = new Asset()
{
ResourceName = assetResourceName,
TextAsset = new TextAsset()
{
Text = text
}
}
}
}
);
// Create an AssetGroupAsset to link the Asset to the AssetGroup.
operations.Add(
new MutateOperation()
{
AssetGroupAssetOperation = new AssetGroupAssetOperation()
{
Create = new AssetGroupAsset()
{
FieldType = fieldType,
AssetGroup = assetGroupResourceName,
Asset = assetResourceName
}
}
}
);
return operations;
}
/// <summary>
/// Creates a list of MutateOperations that create a new linked image asset.
/// </summary>
/// <param name="assetGroupResourceName">The resource name of the asset group to be
/// created.</param>
/// <param name="assetResourceName">The resource name of the text asset to be
/// created.</param>
/// <param name="url">The url of the image to be retrieved and put into an asset.</param>
/// <param name="fieldType">The field type of the asset to be created.</param>
/// <param name="assetName">The asset name.</param>
/// <param name="config">The Google Ads config.</param>
/// <returns>A list of MutateOperations that create a new linked image asset.</returns>
private List<MutateOperation> CreateAndLinkImageAsset(
string assetGroupResourceName,
string assetResourceName,
string url,
AssetFieldType fieldType,
string assetName,
GoogleAdsConfig config)
{
List<MutateOperation> operations = new List<MutateOperation>();
// Create the Image Asset.
operations.Add(
new MutateOperation()
{
AssetOperation = new AssetOperation()
{
Create = new Asset()
{
ResourceName = assetResourceName,
ImageAsset = new ImageAsset()
{
Data =
ByteString.CopyFrom(
MediaUtilities.GetAssetDataFromUrl(url, config)
)
},
// Provide a unique friendly name to identify your asset.
// When there is an existing image asset with the same content but a
// different name, the new name will be dropped silently.
Name = assetName
}
}
}
);
// Create an AssetGroupAsset to link the Asset to the AssetGroup.
operations.Add(
new MutateOperation()
{
AssetGroupAssetOperation = new AssetGroupAssetOperation()
{
Create = new AssetGroupAsset()
{
FieldType = fieldType,
AssetGroup = assetGroupResourceName,
Asset = assetResourceName
}
}
}
);
return operations;
}
/// <summary>
/// Retrieves the list of customer conversion goals.
/// </summary>
/// <param name="client">The Google Ads Client.</param>
/// <param name="customerId">The customer's id.</param>
/// <returns>A list customer conversion goals.</returns>
private List<CustomerConversionGoal> GetCustomerConversionGoals(
GoogleAdsClient client,
long customerId)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsServiceClient =
client.GetService(Services.V11.GoogleAdsService);
List<CustomerConversionGoal> conversionGoals = new List<CustomerConversionGoal>();
SearchGoogleAdsRequest request = new SearchGoogleAdsRequest()
{
CustomerId = customerId.ToString(),
PageSize = 10000,
Query =
@"SELECT
customer_conversion_goal.category,
customer_conversion_goal.origin
FROM
customer_conversion_goal"
};
// The number of conversion goals is typically less than 50 so we use
// GoogleAdsService.search instead of search_stream.
PagedEnumerable<SearchGoogleAdsResponse, GoogleAdsRow> searchPagedResponse =
googleAdsServiceClient.Search(request);
// Iterate over the results and build the list of conversion goals.
foreach (GoogleAdsRow row in searchPagedResponse)
{
conversionGoals.Add(row.CustomerConversionGoal);
}
return conversionGoals;
}
/// <summary>
/// Creates a list of MutateOperations that override customer conversion goals.
/// </summary>
/// <param name="customerId">The customer's id.</param>
/// <param name="conversionGoals">A list customer conversion goals.</param>
/// <returns>A list customer conversion goal operations.</returns>
private List<MutateOperation> CreateCustomerConversionGoalOperations(
long customerId,
List<CustomerConversionGoal> conversionGoals)
{
List<MutateOperation> operations =
new List<MutateOperation>();
foreach (CustomerConversionGoal conversionGoal in conversionGoals)
{
CustomerConversionGoal newConversionGoal = new CustomerConversionGoal()
{
ResourceName = ResourceNames.CustomerConversionGoal(
customerId,
conversionGoal.Category,
conversionGoal.Origin
),
};
// Change the biddability for the campaign conversion goal.
// Set biddability to True for the desired (category, origin).
// Set biddability to False for all other conversion goals.
// Note:
// 1- It is assumed that this Conversion Action
// (category=PURCHASE, origin=WEBSITE) exists in this account.
// 2- More than one goal can be biddable if desired. This example
// shows only one.
newConversionGoal.Biddable =
conversionGoal.Category == ConversionActionCategory.Purchase &&
conversionGoal.Origin == ConversionOrigin.Website;
operations.Add(
new MutateOperation()
{
CustomerConversionGoalOperation = new CustomerConversionGoalOperation()
{
Update = newConversionGoal,
UpdateMask = FieldMasks.AllSetFieldsOf(newConversionGoal)
}
}
);
}
return operations;
}
/// <summary>
/// Creates a list of MutateOperations that create a new asset group
/// listing group filter.
/// </summary>
/// <param name="assetGroupResourceName">The resource name of the asset group.</param>
/// <returns>A list of mutate operations.</returns>
private List<MutateOperation> CreateAssetGroupListingGroupOperations(
string assetGroupResourceName)
{
List<MutateOperation> operations = new List<MutateOperation>();
// Creates a new ad group criterion containing the "default" listing group (All
// products).
AssetGroupListingGroupFilter listingGroupFilter = new AssetGroupListingGroupFilter()
{
AssetGroup = assetGroupResourceName,
// Since this is the root node, do not set the ParentListingGroupFilter. For all
// other nodes, this would refer to the parent listing group filter resource name.
// ParentListingGroupFilter = "<PARENT FILTER NAME>"
// The UnitIncluded means this node has no children.
Type = ListingGroupFilterType.UnitIncluded,
// Because this is a Performance Max campaign for retail, we need to specify that
// this is in the shopping vertical.
Vertical = ListingGroupFilterVertical.Shopping
};
AssetGroupListingGroupFilterOperation operation =
new AssetGroupListingGroupFilterOperation()
{
Create = listingGroupFilter
};
operations.Add(
new MutateOperation() {
AssetGroupListingGroupFilterOperation = operation
}
);
return operations;
}
/// <summary>
/// Prints the details of a MutateGoogleAdsResponse. Parses the "response" oneof field name
/// and uses it to extract the new entity's name and resource name.
/// </summary>
/// <param name="response">A MutateGoogleAdsResponse instance.</param>
private void PrintResponseDetails(MutateGoogleAdsResponse response)
{
// Parse the Mutate response to print details about the entities that were created
// in the request.
foreach (MutateOperationResponse operationResponse in response.MutateOperationResponses)
{
string resourceName;
string entityName = operationResponse.ResponseCase.ToString();
// Trim the substring "Result" from the end of the entity name.
entityName = entityName.Remove(entityName.Length - 6);
switch (operationResponse.ResponseCase)
{
case MutateOperationResponse.ResponseOneofCase.AdGroupResult:
resourceName = operationResponse.AdGroupResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.AdGroupAdResult:
resourceName = operationResponse.AdGroupAdResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.CampaignResult:
resourceName = operationResponse.CampaignResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.CampaignBudgetResult:
resourceName = operationResponse.CampaignBudgetResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.CampaignCriterionResult:
resourceName = operationResponse.CampaignCriterionResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.SmartCampaignSettingResult:
resourceName = operationResponse.SmartCampaignSettingResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.AssetResult:
resourceName = operationResponse.AssetResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.AssetGroupAssetResult:
resourceName = operationResponse.AssetGroupAssetResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.AssetGroupResult:
resourceName = operationResponse.AssetGroupResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.AssetGroupListingGroupFilterResult:
resourceName = operationResponse.AssetGroupListingGroupFilterResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.CampaignConversionGoalResult:
resourceName = operationResponse.CampaignConversionGoalResult.ResourceName;
break;
case MutateOperationResponse.ResponseOneofCase.CustomerConversionGoalResult:
resourceName = operationResponse.CustomerConversionGoalResult.ResourceName;
break;
default:
resourceName = "<not found>";
break;
}
Console.WriteLine(
$"Created a(n) {entityName} with resource name: '{resourceName}'.");
}
}
}
}
PHP
<?php
/**
* Copyright 2021 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
namespace Google\Ads\GoogleAds\Examples\ShoppingAds;
require __DIR__ . '/../../vendor/autoload.php';
use GetOpt\GetOpt;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentNames;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentParser;
use Google\Ads\GoogleAds\Examples\Utils\Helper;
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V11\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V11\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V11\GoogleAdsException;
use Google\Ads\GoogleAds\Util\FieldMasks;
use Google\Ads\GoogleAds\Util\V11\ResourceNames;
use Google\Ads\GoogleAds\V11\Common\ImageAsset;
use Google\Ads\GoogleAds\V11\Common\LanguageInfo;
use Google\Ads\GoogleAds\V11\Common\LocationInfo;
use Google\Ads\GoogleAds\V11\Common\MaximizeConversionValue;
use Google\Ads\GoogleAds\V11\Common\TextAsset;
use Google\Ads\GoogleAds\V11\Enums\AdvertisingChannelTypeEnum\AdvertisingChannelType;
use Google\Ads\GoogleAds\V11\Enums\AssetFieldTypeEnum\AssetFieldType;
use Google\Ads\GoogleAds\V11\Enums\AssetGroupStatusEnum\AssetGroupStatus;
use Google\Ads\GoogleAds\V11\Enums\BudgetDeliveryMethodEnum\BudgetDeliveryMethod;
use Google\Ads\GoogleAds\V11\Enums\CampaignStatusEnum\CampaignStatus;
use Google\Ads\GoogleAds\V11\Enums\ConversionActionCategoryEnum\ConversionActionCategory;
use Google\Ads\GoogleAds\V11\Enums\ConversionOriginEnum\ConversionOrigin;
use Google\Ads\GoogleAds\V11\Enums\ListingGroupFilterTypeEnum\ListingGroupFilterType;
use Google\Ads\GoogleAds\V11\Enums\ListingGroupFilterVerticalEnum\ListingGroupFilterVertical;
use Google\Ads\GoogleAds\V11\Errors\GoogleAdsError;
use Google\Ads\GoogleAds\V11\Resources\Asset;
use Google\Ads\GoogleAds\V11\Resources\AssetGroup;
use Google\Ads\GoogleAds\V11\Resources\AssetGroupAsset;
use Google\Ads\GoogleAds\V11\Resources\AssetGroupListingGroupFilter;
use Google\Ads\GoogleAds\V11\Resources\Campaign;
use Google\Ads\GoogleAds\V11\Resources\Campaign\ShoppingSetting;
use Google\Ads\GoogleAds\V11\Resources\CampaignBudget;
use Google\Ads\GoogleAds\V11\Resources\CampaignConversionGoal;
use Google\Ads\GoogleAds\V11\Resources\CampaignCriterion;
use Google\Ads\GoogleAds\V11\Services\AssetGroupAssetOperation;
use Google\Ads\GoogleAds\V11\Services\AssetGroupListingGroupFilterOperation;
use Google\Ads\GoogleAds\V11\Services\AssetGroupOperation;
use Google\Ads\GoogleAds\V11\Services\AssetOperation;
use Google\Ads\GoogleAds\V11\Services\CampaignBudgetOperation;
use Google\Ads\GoogleAds\V11\Services\CampaignConversionGoalOperation;
use Google\Ads\GoogleAds\V11\Services\CampaignCriterionOperation;
use Google\Ads\GoogleAds\V11\Services\CampaignOperation;
use Google\Ads\GoogleAds\V11\Services\GoogleAdsRow;
use Google\Ads\GoogleAds\V11\Services\MutateGoogleAdsResponse;
use Google\Ads\GoogleAds\V11\Services\MutateOperation;
use Google\Ads\GoogleAds\V11\Services\MutateOperationResponse;
use Google\ApiCore\ApiException;
use Google\ApiCore\Serializer;
/**
* This example shows how to create a Performance Max retail campaign.
*
* This will be created for "All products".
*
* For more information about Performance Max retail campaigns, see
* https://developers.google.com/google-ads/api/docs/performance-max/retail.
*
* Prerequisites:
* - You need to have access to a Merchant Center account. You can find
* instructions to create a Merchant Center account here:
* https://support.google.com/merchants/answer/188924.
* This account must be linked to your Google Ads account. The integration
* instructions can be found at:
* https://developers.google.com/google-ads/api/docs/shopping-ads/merchant-center
* - You need your Google Ads account to track conversions. The different ways
* to track conversions can be found here:
* https://support.google.com/google-ads/answer/1722054.
* - You must have at least one conversion action in the account. For more about conversion
* actions, see
* https://developers.google.com/google-ads/api/docs/conversions/overview#conversion_actions.
*/
class AddPerformanceMaxRetailCampaign
{
private const CUSTOMER_ID = 'INSERT_CUSTOMER_ID_HERE';
private const MERCHANT_CENTER_ACCOUNT_ID = 'INSERT_MERCHANT_CENTER_ACCOUNT_ID_HERE';
private const SALES_COUNTRY = 'US';
// The final URL for the generated ads. Must have the same domain as the Merchant Center
// account.
private const FINAL_URL = 'INSERT_FINAL_URL_HERE';
// We specify temporary IDs that are specific to a single mutate request.
// Temporary IDs are always negative and unique within one mutate request.
//
// See https://developers.google.com/google-ads/api/docs/mutating/best-practices
// for further details.
//
// These temporary IDs are fixed because they are used in multiple places.
private const BUDGET_TEMPORARY_ID = -1;
private const PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID = -2;
private const ASSET_GROUP_TEMPORARY_ID = -3;
// There are also entities that will be created in the same request but do not need to be fixed
// temporary IDs because they are referenced only once.
/** @var int the negative temporary ID used in bulk mutates. */
private static $nextTempId = self::ASSET_GROUP_TEMPORARY_ID - 1;
private const PAGE_SIZE = 10000;
public static function main()
{
// Either pass the required parameters for this example on the command line, or insert them
// into the constants above.
$options = (new ArgumentParser())->parseCommandArguments([
ArgumentNames::CUSTOMER_ID => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::MERCHANT_CENTER_ACCOUNT_ID => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::FINAL_URL => GetOpt::REQUIRED_ARGUMENT,
ArgumentNames::SALES_COUNTRY => GetOpt::OPTIONAL_ARGUMENT
]);
// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();
// Construct a Google Ads client configured from a properties file and the
// OAuth2 credentials above.
$googleAdsClient = (new GoogleAdsClientBuilder())
->fromFile()
->withOAuth2Credential($oAuth2Credential)
->build();
try {
self::runExample(
$googleAdsClient,
$options[ArgumentNames::CUSTOMER_ID] ?: self::CUSTOMER_ID,
$options[ArgumentNames::MERCHANT_CENTER_ACCOUNT_ID]
?: self::MERCHANT_CENTER_ACCOUNT_ID,
$options[ArgumentNames::SALES_COUNTRY] ?: self::SALES_COUNTRY,
$options[ArgumentNames::FINAL_URL] ?: self::FINAL_URL
);
} catch (GoogleAdsException $googleAdsException) {
printf(
"Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
$googleAdsException->getRequestId(),
PHP_EOL,
PHP_EOL
);
foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
/** @var GoogleAdsError $error */
printf(
"\t%s: %s%s",
$error->getErrorCode()->getErrorCode(),
$error->getMessage(),
PHP_EOL
);
}
exit(1);
} catch (ApiException $apiException) {
printf(
"ApiException was thrown with message '%s'.%s",
$apiException->getMessage(),
PHP_EOL
);
exit(1);
}
}
/**
* Runs the example.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @param int $merchantCenterAccountId the Merchant Center account ID
* @param string $salesCountry the sales country of products to include in the campaign
* @param string $finalUrl the final URL for the asset group of the campaign
*/
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId,
int $merchantCenterAccountId,
string $salesCountry,
string $finalUrl
) {
// This campaign will override the customer conversion goals.
// Retrieves the current list of customer conversion goals.
$customerConversionGoals = self::getCustomerConversionGoals(
$googleAdsClient,
$customerId
);
// Performance Max campaigns require that repeated assets such as headlines
// and descriptions be created before the campaign.
// For the list of required assets for a Performance Max campaign, see
// https://developers.google.com/google-ads/api/docs/performance-max/assets.
//
// Creates the headlines.
$headlineAssetResourceNames = self::createMultipleTextAssets(
$googleAdsClient,
$customerId,
["Travel", "Travel Reviews", "Book travel"]
);
// Creates the descriptions.
$descriptionAssetResourceNames = self::createMultipleTextAssets(
$googleAdsClient,
$customerId,
["Take to the air!", "Fly to the sky!"]
);
// It's important to create the below entities in this order because they depend on
// each other.
$operations = [];
// The below methods create and return MutateOperations that we later
// provide to the GoogleAdsService.Mutate method in order to create the
// entities in a single request. Since the entities for a Performance Max
// campaign are closely tied to one-another, it's considered a best practice
// to create them in a single Mutate request so they all complete
// successfully or fail entirely, leaving no orphaned entities. See:
// https://developers.google.com/google-ads/api/docs/mutating/overview.
$operations[] = self::createCampaignBudgetOperation($customerId);
$operations[] = self::createPerformanceMaxCampaignOperation(
$customerId,
$merchantCenterAccountId,
$salesCountry
);
$operations =
array_merge($operations, self::createCampaignCriterionOperations($customerId));
$operations = array_merge($operations, self::createAssetGroupOperations(
$customerId,
$finalUrl,
$headlineAssetResourceNames,
$descriptionAssetResourceNames
));
$operations = array_merge($operations, self::createConversionGoalOperations(
$customerId,
$customerConversionGoals
));
$operations = array_merge($operations, self::createAssetGroupListingGroupFilterOperations(
ResourceNames::forAssetGroup($customerId, self::ASSET_GROUP_TEMPORARY_ID)
));
// Issues a mutate request to create everything and prints its information.
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$response = $googleAdsServiceClient->mutate(
$customerId,
$operations
);
self::printResponseDetails($response);
}
/**
* Creates a MutateOperation that creates a new CampaignBudget.
*
* A temporary ID will be assigned to this campaign budget so that it can be
* referenced by other objects being created in the same Mutate request.
*
* @param int $customerId the customer ID
* @return MutateOperation the mutate operation that creates a campaign budget
*/
private static function createCampaignBudgetOperation(int $customerId): MutateOperation
{
// Creates a mutate operation that creates a campaign budget operation.
return new MutateOperation([
'campaign_budget_operation' => new CampaignBudgetOperation([
'create' => new CampaignBudget([
// Sets a temporary ID in the budget's resource name so it can be referenced
// by the campaign in later steps.
'resource_name' => ResourceNames::forCampaignBudget(
$customerId,
self::BUDGET_TEMPORARY_ID
),
'name' => 'Performance Max retail campaign budget #' .
Helper::getPrintableDatetime(),
// The budget period already defaults to DAILY.
'amount_micros' => 50000000,
'delivery_method' => BudgetDeliveryMethod::STANDARD,
// A Performance Max campaign cannot use a shared campaign budget.
'explicitly_shared' => false
])
])
]);
}
/**
* Creates a MutateOperation that creates a new Performance Max campaign.
*
* A temporary ID will be assigned to this campaign so that it can
* be referenced by other objects being created in the same Mutate request.
*
* @param int $customerId the customer ID
* @param int $merchantCenterAccountId the Merchant Center account ID
* @param string $salesCountry the sales country of products to include in the campaign
* @return MutateOperation the mutate operation that creates the campaign
*/
private static function createPerformanceMaxCampaignOperation(
int $customerId,
int $merchantCenterAccountId,
string $salesCountry
): MutateOperation {
// Creates a mutate operation that creates a campaign operation.
return new MutateOperation([
'campaign_operation' => new CampaignOperation([
'create' => new Campaign([
'name' => 'Performance Max retail campaign #' . Helper::getPrintableDatetime(),
// Assigns the resource name with a temporary ID.
'resource_name' => ResourceNames::forCampaign(
$customerId,
self::PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
// Sets the budget using the given budget resource name.
'campaign_budget' => ResourceNames::forCampaignBudget(
$customerId,
self::BUDGET_TEMPORARY_ID
),
// The campaign is the only entity in the mutate request that should have its
// status set.
// Recommendation: Set the campaign to PAUSED when creating it to prevent
// the ads from immediately serving.
'status' => CampaignStatus::PAUSED,
// All Performance Max campaigns have an advertising_channel_type of
// PERFORMANCE_MAX. The advertising_channel_sub_type should not be set.
'advertising_channel_type' => AdvertisingChannelType::PERFORMANCE_MAX,
// Bidding strategy must be set directly on the campaign.
// Setting a portfolio bidding strategy by resource name is not supported.
// Max Conversion and Max Conversion Value are the only strategies supported
// for Performance Max campaigns.
// An optional ROAS (Return on Advertising Spend) can be set for
// maximize_conversion_value. The ROAS value must be specified as a ratio in
// the API. It is calculated by dividing "total value" by "total spend".
// For more information on Max Conversion Value, see the support article:
// http://support.google.com/google-ads/answer/7684216.
// A target_roas of 3.5 corresponds to a 350% return on ad spend.
'maximize_conversion_value' => new MaximizeConversionValue([
'target_roas' => 3.5
]),
// Sets the Final URL expansion opt out. This flag is specific to
// Performance Max campaigns. If opted out (true), only the final URLs in
// the asset group or URLs specified in the advertiser's Google Merchant
// Center or business data feeds are targeted.
//
// If opted in (false), the entire domain will be targeted. For best
// results, set this value to false to opt in and allow URL expansions. You
// can optionally add exclusions to limit traffic to parts of your website.
//
// For a Retail campaign, we want the final URL's to be limited to those
// explicitly surfaced via GMC.
'url_expansion_opt_out' => true,
// Sets the shopping settings.
'shopping_setting' => new ShoppingSetting([
'merchant_id' => $merchantCenterAccountId,
'sales_country' => $salesCountry
]),
// Optional fields.
'start_date' => date('Ymd', strtotime('+1 day')),
'end_date' => date('Ymd', strtotime('+365 days'))
])
])
]);
}
/**
* Creates a list of MutateOperations that create new campaign criteria.
*
* @param int $customerId the customer ID
* @return MutateOperation[] a list of MutateOperations that create the new campaign criteria
*/
private static function createCampaignCriterionOperations(int $customerId): array
{
$operations = [];
// Sets the LOCATION campaign criteria.
// Target all of New York City except Brooklyn.
// Location IDs are listed here:
// https://developers.google.com/google-ads/api/reference/data/geotargets
// and they can also be retrieved using the GeoTargetConstantService as shown
// here: https://developers.google.com/google-ads/api/docs/targeting/location-targeting
//
// We will add one positive location target for New York City (ID=1023191)
// and one negative location target for Brooklyn (ID=1022762).
// First, adds the positive (negative = false) for New York City.
$operations[] = new MutateOperation([
'campaign_criterion_operation' => new CampaignCriterionOperation([
'create' => new CampaignCriterion([
'campaign' => ResourceNames::forCampaign(
$customerId,
self::PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
'location' => new LocationInfo([
'geo_target_constant' => ResourceNames::forGeoTargetConstant(1023191)
]),
'negative' => false
])
])
]);
// Next adds the negative target for Brooklyn.
$operations[] = new MutateOperation([
'campaign_criterion_operation' => new CampaignCriterionOperation([
'create' => new CampaignCriterion([
'campaign' => ResourceNames::forCampaign(
$customerId,
self::PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
'location' => new LocationInfo([
'geo_target_constant' => ResourceNames::forGeoTargetConstant(1022762)
]),
'negative' => true
])
])
]);
// Sets the LANGUAGE campaign criterion.
$operations[] = new MutateOperation([
'campaign_criterion_operation' => new CampaignCriterionOperation([
'create' => new CampaignCriterion([
'campaign' => ResourceNames::forCampaign(
$customerId,
self::PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
// Sets the language.
// For a list of all language codes, see:
// https://developers.google.com/google-ads/api/reference/data/codes-formats#expandable-7
'language' => new LanguageInfo([
'language_constant' => ResourceNames::forLanguageConstant(1000) // English
])
])
])
]);
return $operations;
}
/**
* Creates multiple text assets and returns the list of resource names.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @param string[] $texts a list of strings, each of which will be used to create a text asset
* @return string[] a list of asset resource names
*/
private static function createMultipleTextAssets(
GoogleAdsClient $googleAdsClient,
int $customerId,
array $texts
): array {
// Here again, we use the GoogleAdService to create multiple text assets in a single
// request.
$operations = [];
foreach ($texts as $text) {
// Creates a mutate operation for a text asset.
$operations[] = new MutateOperation([
'asset_operation' => new AssetOperation([
'create' => new Asset(['text_asset' => new TextAsset(['text' => $text])])
])
]);
}
// Issues a mutate request to add all assets.
$googleAdsService = $googleAdsClient->getGoogleAdsServiceClient();
/** @var MutateGoogleAdsResponse $mutateGoogleAdsResponse */
$mutateGoogleAdsResponse = $googleAdsService->mutate($customerId, $operations);
$assetResourceNames = [];
foreach ($mutateGoogleAdsResponse->getMutateOperationResponses() as $response) {
/** @var MutateOperationResponse $response */
$assetResourceNames[] = $response->getAssetResult()->getResourceName();
}
self::printResponseDetails($mutateGoogleAdsResponse);
return $assetResourceNames;
}
/**
* Creates a list of MutateOperations that create a new asset group.
*
* A temporary ID will be assigned to this asset group so that it can
* be referenced by other objects being created in the same Mutate request.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @param string $finalUrl the final URL for the asset group of the campaign
* @param string[] $headlineAssetResourceNames a list of headline resource names
* @param string[] $descriptionAssetResourceNames a list of description resource names
* @return MutateOperation[] a list of MutateOperations that create new asset group
*/
private static function createAssetGroupOperations(
int $customerId,
string $finalUrl,
array $headlineAssetResourceNames,
array $descriptionAssetResourceNames
): array {
$operations = [];
// Creates a new mutate operation that creates an asset group operation.
$operations[] = new MutateOperation([
'asset_group_operation' => new AssetGroupOperation([
'create' => new AssetGroup([
'resource_name' => ResourceNames::forAssetGroup(
$customerId,
self::ASSET_GROUP_TEMPORARY_ID
),
'name' => 'Performance Max retail asset group #' .
Helper::getPrintableDatetime(),
'campaign' => ResourceNames::forCampaign(
$customerId,
self::PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
'final_urls' => [$finalUrl],
'final_mobile_urls' => [$finalUrl],
'status' => AssetGroupStatus::PAUSED
])
])
]);
// For the list of required assets for a Performance Max campaign, see
// https://developers.google.com/google-ads/api/docs/performance-max/assets
// An AssetGroup is linked to an Asset by creating a new AssetGroupAsset
// and providing:
// - the resource name of the AssetGroup
// - the resource name of the Asset
// - the field_type of the Asset in this AssetGroup.
//
// To learn more about AssetGroups, see
// https://developers.google.com/google-ads/api/docs/performance-max/asset-groups.
// Links the previously created multiple text assets.
// Links the headline assets.
foreach ($headlineAssetResourceNames as $resourceName) {
$operations[] = new MutateOperation([
'asset_group_asset_operation' => new AssetGroupAssetOperation([
'create' => new AssetGroupAsset([
'asset' => $resourceName,
'asset_group' => ResourceNames::forAssetGroup(
$customerId,
self::ASSET_GROUP_TEMPORARY_ID
),
'field_type' => AssetFieldType::HEADLINE
])
])
]);
}
// Links the description assets.
foreach ($descriptionAssetResourceNames as $resourceName) {
$operations[] = new MutateOperation([
'asset_group_asset_operation' => new AssetGroupAssetOperation([
'create' => new AssetGroupAsset([
'asset' => $resourceName,
'asset_group' => ResourceNames::forAssetGroup(
$customerId,
self::ASSET_GROUP_TEMPORARY_ID
),
'field_type' => AssetFieldType::DESCRIPTION
])
])
]);
}
// Creates and links the long headline text asset.
$operations = array_merge($operations, self::createAndLinkTextAsset(
$customerId,
'Travel the World',
AssetFieldType::LONG_HEADLINE
));
// Creates and links the business name text asset.
$operations = array_merge($operations, self::createAndLinkTextAsset(
$customerId,
'Interplanetary Cruises',
AssetFieldType::BUSINESS_NAME
));
// Creates and links the image assets.
// Creates and links the Logo Asset.
$operations = array_merge($operations, self::createAndLinkImageAsset(
$customerId,
'https://gaagl.page.link/bjYi',
AssetFieldType::LOGO,
'Marketing Logo'
));
// Creates and links the Marketing Image Asset.
$operations = array_merge($operations, self::createAndLinkImageAsset(
$customerId,
'https://gaagl.page.link/Eit5',
AssetFieldType::MARKETING_IMAGE,
'Marketing Image'
));
// Creates and links the Square Marketing Image Asset.
$operations = array_merge($operations, self::createAndLinkImageAsset(
$customerId,
'https://gaagl.page.link/bjYi',
AssetFieldType::SQUARE_MARKETING_IMAGE,
'Square Marketing Image'
));
return $operations;
}
/**
* Creates a list of MutateOperations that create a new linked text asset.
*
* @param int $customerId the customer ID
* @param string $text the text of the asset to be created
* @param int $fieldType the field type of the new asset in the AssetGroupAsset
* @return MutateOperation[] a list of MutateOperations that create a new linked text asset
*/
private static function createAndLinkTextAsset(
int $customerId,
string $text,
int $fieldType
): array {
$operations = [];
// Creates a new mutate operation that creates a text asset.
$operations[] = new MutateOperation([
'asset_operation' => new AssetOperation([
'create' => new Asset([
'resource_name' => ResourceNames::forAsset($customerId, self::$nextTempId),
'text_asset' => new TextAsset(['text' => $text])
])
])
]);
// Creates an asset group asset to link the asset to the asset group.
$operations[] = new MutateOperation([
'asset_group_asset_operation' => new AssetGroupAssetOperation([
'create' => new AssetGroupAsset([
'asset' => ResourceNames::forAsset($customerId, self::$nextTempId),
'asset_group' => ResourceNames::forAssetGroup(
$customerId,
self::ASSET_GROUP_TEMPORARY_ID
),
'field_type' => $fieldType
])
])
]);
self::$nextTempId--;
return $operations;
}
/**
* Creates a list of MutateOperations that create a new linked image asset.
*
* @param int $customerId the customer ID
* @param string $url the URL of the image to be retrieved and put into an asset
* @param int $fieldType the field type of the new asset in the AssetGroupAsset
* @param string $assetName the asset name
* @return MutateOperation[] a list of MutateOperations that create a new linked image asset
*/
private static function createAndLinkImageAsset(
int $customerId,
string $url,
int $fieldType,
string $assetName
): array {
$operations = [];
// Creates a new mutate operation that creates an image asset.
$operations[] = new MutateOperation([
'asset_operation' => new AssetOperation([
'create' => new Asset([
'resource_name' => ResourceNames::forAsset($customerId, self::$nextTempId),
// Provide a unique friendly name to identify your asset.
// When there is an existing image asset with the same content but a different
// name, the new name will be dropped silently.
'name' => $assetName,
'image_asset' => new ImageAsset(['data' => file_get_contents($url)])
])
])
]);
// Creates an asset group asset to link the asset to the asset group.
$operations[] = new MutateOperation([
'asset_group_asset_operation' => new AssetGroupAssetOperation([
'create' => new AssetGroupAsset([
'asset' => ResourceNames::forAsset($customerId, self::$nextTempId),
'asset_group' => ResourceNames::forAssetGroup(
$customerId,
self::ASSET_GROUP_TEMPORARY_ID
),
'field_type' => $fieldType
])
])
]);
self::$nextTempId--;
return $operations;
}
/**
* Retrieves the list of customer conversion goals.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @return array list of dicts containing the category and origin of customer conversion goals
*/
private static function getCustomerConversionGoals(
GoogleAdsClient $googleAdsClient,
int $customerId
): array {
$customerConversionGoals = [];
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Creates a query that retrieves all customer conversion goals.
$query = 'SELECT customer_conversion_goal.category, customer_conversion_goal.origin ' .
'FROM customer_conversion_goal';
// The number of conversion goals is typically less than 50 so we use a search request
// instead of search stream.
$response =
$googleAdsServiceClient->search($customerId, $query, ['pageSize' => self::PAGE_SIZE]);
// Iterates over all rows in all pages and builds the list of conversion goals.
foreach ($response->iterateAllElements() as $googleAdsRow) {
/** @var GoogleAdsRow $googleAdsRow */
$customerConversionGoals[] = [
'category' => $googleAdsRow->getCustomerConversionGoal()->getCategory(),
'origin' => $googleAdsRow->getCustomerConversionGoal()->getOrigin()
];
}
return $customerConversionGoals;
}
/**
* Creates a list of MutateOperations that override customer conversion goals.
*
* @param int $customerId the customer ID
* @param array $customerConversionGoals the list of customer conversion goals that will be
* overridden
* @return MutateOperation[] a list of MutateOperations that update campaign conversion goals
*/
private static function createConversionGoalOperations(
int $customerId,
array $customerConversionGoals
): array {
$operations = [];
// To override the customer conversion goals, we will change the biddability of each of the
// customer conversion goals so that only the desired conversion goal is biddable in this
// campaign.
foreach ($customerConversionGoals as $customerConversionGoal) {
$campaignConversionGoal = new CampaignConversionGoal([
'resource_name' => ResourceNames::forCampaignConversionGoal(
$customerId,
self::PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID,
ConversionActionCategory::name($customerConversionGoal['category']),
ConversionOrigin::name($customerConversionGoal['origin'])
)
]);
// Changes the biddability for the campaign conversion goal.
// Sets biddability to true for the desired (category, origin).
// Sets biddability to false for all other conversion goals.
// Note:
// 1- It is assumed that this Conversion Action
// (category=PURCHASE, origin=WEBSITE) exists in this account.
// 2- More than one goal can be biddable if desired. This example
// shows only one.
if (
$customerConversionGoal["category"] === ConversionActionCategory::PURCHASE
&& $customerConversionGoal["origin"] === ConversionOrigin::WEBSITE
) {
$campaignConversionGoal->setBiddable(true);
} else {
$campaignConversionGoal->setBiddable(false);
}
$operations[] = new MutateOperation([
'campaign_conversion_goal_operation' => new CampaignConversionGoalOperation([
'update' => $campaignConversionGoal,
// Sets the update mask on the operation. Here the update mask will be a list
// of all the fields that were set on the update object.
'update_mask' => FieldMasks::allSetFieldsOf($campaignConversionGoal)
])
]);
}
return $operations;
}
/**
* Creates a list of MutateOperations that create a new asset group listing group filter.
*
* @param string $assetGroupResourceName the resource name of asset group
* @return MutateOperation[] a list of MutateOperations that create a new asset group listing
* group filter
*/
private static function createAssetGroupListingGroupFilterOperations(
string $assetGroupResourceName
): array {
$operations = [];
$operations[] = new MutateOperation([
'asset_group_listing_group_filter_operation'
=> new AssetGroupListingGroupFilterOperation([
// Creates a new asset group listing group filter containing the "default"
// listing group (All products).
'create' => new AssetGroupListingGroupFilter([
'asset_group' => $assetGroupResourceName,
// Since this is the root node, do not set the 'parent_listing_group_filter'
// field. For all other nodes, this would refer to the parent listing group
// filter resource name.
//
// UNIT_INCLUDED means this node has no children.
'type' => ListingGroupFilterType::UNIT_INCLUDED,
// Because this is a Performance Max campaign for retail, we need to specify
// that this is in the shopping vertical.
'vertical' => ListingGroupFilterVertical::SHOPPING
])
])
]);
return $operations;
}
/**
* Prints the details of a MutateGoogleAdsResponse. Parses the "response" oneof field name and
* uses it to extract the new entity's name and resource name.
*
* @param MutateGoogleAdsResponse $mutateGoogleAdsResponse the mutate Google Ads response
*/
private static function printResponseDetails(
MutateGoogleAdsResponse $mutateGoogleAdsResponse
): void {
foreach ($mutateGoogleAdsResponse->getMutateOperationResponses() as $response) {
/** @var MutateOperationResponse $response */
$getter = Serializer::getGetter($response->getResponse());
printf(
"Created a(n) %s with '%s'.%s",
preg_replace(
'/Result$/',
'',
ucfirst(Serializer::toCamelCase($response->getResponse()))
),
$response->$getter()->getResourceName(),
PHP_EOL
);
}
}
}
AddPerformanceMaxRetailCampaign::main();
Python
#!/usr/bin/env python
# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""This example shows how to create a Performance Max retail campaign.
This will be created for "All products".
For more information about Performance Max retail campaigns, see
https://developers.google.com/google-ads/api/docs/performance-max/retail
Prerequisites:
- You need to have access to a Merchant Center account. You can find
instructions to create a Merchant Center account here:
https://support.google.com/merchants/answer/188924.
This account must be linked to your Google Ads account. The integration
instructions can be found at:
https://developers.google.com/google-ads/api/docs/shopping-ads/merchant-center
- You need your Google Ads account to track conversions. The different ways
to track conversions can be found here:
https://support.google.com/google-ads/answer/1722054.
- You must have at least one conversion action in the account. For
more about conversion actions, see
https://developers.google.com/google-ads/api/docs/conversions/overview#conversion_actions
"""
import argparse
from datetime import datetime, timedelta
import sys
from uuid import uuid4
from google.api_core import protobuf_helpers
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
from google.ads.googleads.util import convert_snake_case_to_upper_case
import requests
# We specify temporary IDs that are specific to a single mutate request.
# Temporary IDs are always negative and unique within one mutate request.
#
# See https://developers.google.com/google-ads/api/docs/mutating/best-practices
# for further details.
#
# These temporary IDs are fixed because they are used in multiple places.
_BUDGET_TEMPORARY_ID = "-1"
_PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID = "-2"
_ASSET_GROUP_TEMPORARY_ID = "-3"
# There are also entities that will be created in the same request but do not
# need to be fixed temporary IDs because they are referenced only once.
next_temp_id = int(_ASSET_GROUP_TEMPORARY_ID) - 1
def main(
client,
customer_id,
merchant_center_account_id,
sales_country,
final_url,
):
"""The main method that creates all necessary entities for the example.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
merchant_center_account_id: The Merchant Center account ID.
sales_country: sales country of products to include in the campaign.
final_url: the final URL.
"""
googleads_service = client.get_service("GoogleAdsService")
# This campaign will override the customer conversion goals.
# Retrieve the current list of customer conversion goals.
customer_conversion_goals = _get_customer_conversion_goals(
client, customer_id
)
# Performance Max campaigns require that repeated assets such as headlines
# and descriptions be created before the campaign.
# For the list of required assets for a Performance Max campaign, see
# https://developers.google.com/google-ads/api/docs/performance-max/assets
#
# Create the headlines.
headline_asset_resource_names = _create_multiple_text_assets(
client,
customer_id,
[
"Travel",
"Travel Reviews",
"Book travel",
],
)
# Create the descriptions.
description_asset_resource_names = _create_multiple_text_assets(
client,
customer_id,
[
"Take to the air!",
"Fly to the sky!",
],
)
# The below methods create and return MutateOperations that we later
# provide to the GoogleAdsService.Mutate method in order to create the
# entities in a single request. Since the entities for a Performance Max
# campaign are closely tied to one-another, it's considered a best practice
# to create them in a single Mutate request so they all complete
# successfully or fail entirely, leaving no orphaned entities. See:
# https://developers.google.com/google-ads/api/docs/mutating/overview
campaign_budget_operation = _create_campaign_budget_operation(
client,
customer_id,
)
performance_max_campaign_operation = (
_create_performance_max_campaign_operation(
client,
customer_id,
merchant_center_account_id,
sales_country,
)
)
campaign_criterion_operations = _create_campaign_criterion_operations(
client,
customer_id,
)
asset_group_operations = _create_asset_group_operation(
client,
customer_id,
final_url,
headline_asset_resource_names,
description_asset_resource_names,
)
conversion_goal_operations = _create_conversion_goal_operations(
client,
customer_id,
customer_conversion_goals,
)
# Send the operations in a single Mutate request.
response = googleads_service.mutate(
customer_id=customer_id,
mutate_operations=[
# It's important to create these entities in this order because
# they depend on each other.
campaign_budget_operation,
performance_max_campaign_operation,
# Expand the list of multiple operations into the list of
# other mutate operations.
*campaign_criterion_operations,
*asset_group_operations,
*conversion_goal_operations,
],
)
_print_response_details(response)
def _create_campaign_budget_operation(
client,
customer_id,
):
"""Creates a MutateOperation that creates a new CampaignBudget.
A temporary ID will be assigned to this campaign budget so that it can be
referenced by other objects being created in the same Mutate request.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
Returns:
a MutateOperation that creates a CampaignBudget.
"""
mutate_operation = client.get_type("MutateOperation")
campaign_budget_operation = mutate_operation.campaign_budget_operation
campaign_budget = campaign_budget_operation.create
campaign_budget.name = f"Performance Max retail campaign budget #{uuid4()}"
# The budget period already defaults to DAILY.
campaign_budget.amount_micros = 50000000
campaign_budget.delivery_method = (
client.enums.BudgetDeliveryMethodEnum.STANDARD
)
# A Performance Max campaign cannot use a shared campaign budget.
campaign_budget.explicitly_shared = False
# Set a temporary ID in the budget's resource name so it can be referenced
# by the campaign in later steps.
campaign_budget.resource_name = client.get_service(
"CampaignBudgetService"
).campaign_budget_path(customer_id, _BUDGET_TEMPORARY_ID)
return mutate_operation
def _create_performance_max_campaign_operation(
client,
customer_id,
merchant_center_account_id,
sales_country,
):
"""Creates a MutateOperation that creates a new Performance Max campaign.
A temporary ID will be assigned to this campaign so that it can
be referenced by other objects being created in the same Mutate request.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
merchant_center_account_id: The Merchant Center account ID.
sales_country: Sales country of products to include in the campaign.
Returns:
a MutateOperation that creates a campaign.
"""
mutate_operation = client.get_type("MutateOperation")
campaign = mutate_operation.campaign_operation.create
campaign.name = f"Performance Max retail campaign #{uuid4()}"
# Set the campaign status as PAUSED. The campaign is the only entity in
# the mutate request that should have its status set.
campaign.status = client.enums.CampaignStatusEnum.PAUSED
# All Performance Max campaigns have an advertising_channel_type of
# PERFORMANCE_MAX. The advertising_channel_sub_type should not be set.
campaign.advertising_channel_type = (
client.enums.AdvertisingChannelTypeEnum.PERFORMANCE_MAX
)
# Bidding strategy must be set directly on the campaign.
# Setting a portfolio bidding strategy by resource name is not supported.
# Max Conversion and Max Conversion Value are the only strategies supported
# for Performance Max campaigns.
# An optional ROAS (Return on Advertising Spend) can be set for
# maximize_conversion_value. The ROAS value must be specified as a ratio in
# the API. It is calculated by dividing "total value" by "total spend".
# For more information on Max Conversion Value, see the support article:
# http://support.google.com/google-ads/answer/7684216.
# A target_roas of 3.5 corresponds to a 350% return on ad spend.
# campaign.maximize_conversion_value.target_roas = 3.5
# For first time users, it's recommended not to set a target ROAS.
# Although target ROAS is optional, you still need to define it
# even if you do not want to use it.
campaign.maximize_conversion_value.target_roas = None
# Below is what you would use if you want to maximize conversions
# campaign.maximize_conversions.target_cpa = None
# The target CPA is optional. This is the average amount that you would
# like to spend per conversion action.
# Set the shopping settings.
campaign.shopping_setting.merchant_id = merchant_center_account_id
campaign.shopping_setting.sales_country = sales_country
# Set the Final URL expansion opt out. This flag is specific to
# Performance Max campaigns. If opted out (True), only the final URLs in
# the asset group or URLs specified in the advertiser's Google Merchant
# If opted in (False), the entire domain will be targeted. For best
# results, set this value to false to opt in and allow URL expansions. You
# can optionally add exclusions to limit traffic to parts of your website.
# For a Retail campaign, we want the final URL's to be limited to
# those explicitly surfaced via GMC.
campaign.url_expansion_opt_out = True
# Assign the resource name with a temporary ID.
campaign_service = client.get_service("CampaignService")
campaign.resource_name = campaign_service.campaign_path(
customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
)
# Set the budget using the given budget resource name.
campaign.campaign_budget = campaign_service.campaign_budget_path(
customer_id, _BUDGET_TEMPORARY_ID
)
# Optional fields
campaign.start_date = (datetime.now() + timedelta(1)).strftime("%Y%m%d")
campaign.end_date = (datetime.now() + timedelta(365)).strftime("%Y%m%d")
return mutate_operation
def _create_campaign_criterion_operations(
client,
customer_id,
):
"""Creates a list of MutateOperations that create new campaign criteria.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
Returns:
a list of MutateOperations that create new campaign criteria.
"""
campaign_service = client.get_service("CampaignService")
geo_target_constant_service = client.get_service("GeoTargetConstantService")
googleads_service = client.get_service("GoogleAdsService")
operations = []
# Set the LOCATION campaign criteria.
# Target all of New York City except Brooklyn.
# Location IDs are listed here:
# https://developers.google.com/google-ads/api/reference/data/geotargets
# and they can also be retrieved using the GeoTargetConstantService as shown
# here: https://developers.google.com/google-ads/api/docs/targeting/location-targeting
#
# We will add one positive location target for New York City (ID=1023191)
# and one negative location target for Brooklyn (ID=1022762).
# First, add the positive (negative = False) for New York City.
mutate_operation = client.get_type("MutateOperation")
campaign_criterion = mutate_operation.campaign_criterion_operation.create
campaign_criterion.campaign = campaign_service.campaign_path(
customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
)
campaign_criterion.location.geo_target_constant = (
geo_target_constant_service.geo_target_constant_path("1023191")
)
campaign_criterion.negative = False
operations.append(mutate_operation)
# Next add the negative target for Brooklyn.
mutate_operation = client.get_type("MutateOperation")
campaign_criterion = mutate_operation.campaign_criterion_operation.create
campaign_criterion.campaign = campaign_service.campaign_path(
customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
)
campaign_criterion.location.geo_target_constant = (
geo_target_constant_service.geo_target_constant_path("1022762")
)
campaign_criterion.negative = True
operations.append(mutate_operation)
# Set the LANGUAGE campaign criterion.
mutate_operation = client.get_type("MutateOperation")
campaign_criterion = mutate_operation.campaign_criterion_operation.create
campaign_criterion.campaign = campaign_service.campaign_path(
customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
)
# Set the language.
# For a list of all language codes, see:
# https://developers.google.com/google-ads/api/reference/data/codes-formats#expandable-7
campaign_criterion.language.language_constant = (
googleads_service.language_constant_path("1000") # English
)
operations.append(mutate_operation)
return operations
def _create_multiple_text_assets(client, customer_id, texts):
"""Creates multiple text assets and returns the list of resource names.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
texts: a list of strings, each of which will be used to create a text
asset.
Returns:
asset_resource_names: a list of asset resource names.
"""
# Here again we use the GoogleAdService to create multiple text
# assets in a single request.
googleads_service = client.get_service("GoogleAdsService")
operations = []
for text in texts:
mutate_operation = client.get_type("MutateOperation")
asset = mutate_operation.asset_operation.create
asset.text_asset.text = text
operations.append(mutate_operation)
# Send the operations in a single Mutate request.
response = googleads_service.mutate(
customer_id=customer_id,
mutate_operations=operations,
)
asset_resource_names = []
for result in response.mutate_operation_responses:
if result._pb.HasField("asset_result"):
asset_resource_names.append(result.asset_result.resource_name)
_print_response_details(response)
return asset_resource_names
def _create_asset_group_operation(
client,
customer_id,
final_url,
headline_asset_resource_names,
description_asset_resource_names,
):
"""Creates a list of MutateOperations that create a new asset_group.
A temporary ID will be assigned to this asset group so that it can
be referenced by other objects being created in the same Mutate request.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
final_url: the final URL.
headline_asset_resource_names: a list of headline resource names.
description_asset_resource_names: a list of description resource names.
Returns:
MutateOperations that create a new asset group and related assets.
"""
asset_group_service = client.get_service("AssetGroupService")
campaign_service = client.get_service("CampaignService")
operations = []
# Create the AssetGroup.
mutate_operation = client.get_type("MutateOperation")
asset_group = mutate_operation.asset_group_operation.create
asset_group.name = f"Performance Max retail asset group #{uuid4()}"
asset_group.campaign = campaign_service.campaign_path(
customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
)
asset_group.final_urls.append(final_url)
asset_group.final_mobile_urls.append(final_url)
asset_group.status = client.enums.AssetGroupStatusEnum.PAUSED
asset_group.resource_name = asset_group_service.asset_group_path(
customer_id,
_ASSET_GROUP_TEMPORARY_ID,
)
operations.append(mutate_operation)
# Creates a new ad group criterion containing the "default" listing group (All products).
mutate_operation = client.get_type("MutateOperation")
asset_group_listing_group = (
mutate_operation.asset_group_listing_group_filter_operation.create
)
asset_group_listing_group.asset_group = (
asset_group_service.asset_group_path(
customer_id,
_ASSET_GROUP_TEMPORARY_ID,
)
)
asset_group_listing_group.type_ = (
client.enums.ListingGroupFilterTypeEnum.UNIT_INCLUDED
)
# Because this is a Performance Max campaign for retail, we need to specify that this is
# in the shopping vertical.
asset_group_listing_group.vertical = (
client.enums.ListingGroupFilterVerticalEnum.SHOPPING
)
operations.append(mutate_operation)
# For the list of required assets for a Performance Max campaign, see
# https://developers.google.com/google-ads/api/docs/performance-max/assets
# An AssetGroup is linked to an Asset by creating a new AssetGroupAsset
# and providing:
# the resource name of the AssetGroup
# the resource name of the Asset
# the field_type of the Asset in this AssetGroup.
#
# To learn more about AssetGroups, see
# https://developers.google.com/google-ads/api/docs/performance-max/asset-groups
# Link the previously created multiple text assets.
# Link the headline assets.
for resource_name in headline_asset_resource_names:
mutate_operation = client.get_type("MutateOperation")
asset_group_asset = mutate_operation.asset_group_asset_operation.create
asset_group_asset.field_type = client.enums.AssetFieldTypeEnum.HEADLINE
asset_group_asset.asset_group = asset_group_service.asset_group_path(
customer_id,
_ASSET_GROUP_TEMPORARY_ID,
)
asset_group_asset.asset = resource_name
operations.append(mutate_operation)
# Link the description assets.
for resource_name in description_asset_resource_names:
mutate_operation = client.get_type("MutateOperation")
asset_group_asset = mutate_operation.asset_group_asset_operation.create
asset_group_asset.field_type = (
client.enums.AssetFieldTypeEnum.DESCRIPTION
)
asset_group_asset.asset_group = asset_group_service.asset_group_path(
customer_id,
_ASSET_GROUP_TEMPORARY_ID,
)
asset_group_asset.asset = resource_name
operations.append(mutate_operation)
# Create and link the long headline text asset.
mutate_operations = _create_and_link_text_asset(
client,
customer_id,
"Travel the World",
client.enums.AssetFieldTypeEnum.LONG_HEADLINE,
)
operations.extend(mutate_operations)
# Create and link the business name text asset.
mutate_operations = _create_and_link_text_asset(
client,
customer_id,
"Interplanetary Cruises",
client.enums.AssetFieldTypeEnum.BUSINESS_NAME,
)
operations.extend(mutate_operations)
# Create and link the image assets.
# Create and link the Logo Asset.
mutate_operations = _create_and_link_image_asset(
client,
customer_id,
"https://gaagl.page.link/bjYi",
client.enums.AssetFieldTypeEnum.LOGO,
"Logo Image",
)
operations.extend(mutate_operations)
# Create and link the Marketing Image Asset.
mutate_operations = _create_and_link_image_asset(
client,
customer_id,
"https://gaagl.page.link/Eit5",
client.enums.AssetFieldTypeEnum.MARKETING_IMAGE,
"Marketing Image",
)
operations.extend(mutate_operations)
# Create and link the Square Marketing Image Asset.
mutate_operations = _create_and_link_image_asset(
client,
customer_id,
"https://gaagl.page.link/bjYi",
client.enums.AssetFieldTypeEnum.SQUARE_MARKETING_IMAGE,
"Square Marketing Image",
)
operations.extend(mutate_operations)
return operations
def _create_and_link_text_asset(client, customer_id, text, field_type):
"""Creates a list of MutateOperations that create a new linked text asset.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
text: the text of the asset to be created.
field_type: the field_type of the new asset in the AssetGroupAsset.
Returns:
MutateOperations that create a new linked text asset.
"""
global next_temp_id
operations = []
asset_service = client.get_service("AssetService")
asset_group_service = client.get_service("AssetGroupService")
# Create the Text Asset.
mutate_operation = client.get_type("MutateOperation")
asset = mutate_operation.asset_operation.create
asset.resource_name = asset_service.asset_path(customer_id, next_temp_id)
asset.text_asset.text = text
operations.append(mutate_operation)
# Create an AssetGroupAsset to link the Asset to the AssetGroup.
mutate_operation = client.get_type("MutateOperation")
asset_group_asset = mutate_operation.asset_group_asset_operation.create
asset_group_asset.field_type = field_type
asset_group_asset.asset_group = asset_group_service.asset_group_path(
customer_id,
_ASSET_GROUP_TEMPORARY_ID,
)
asset_group_asset.asset = asset_service.asset_path(
customer_id, next_temp_id
)
operations.append(mutate_operation)
next_temp_id -= 1
return operations
def _create_and_link_image_asset(
client, customer_id, url, field_type, asset_name
):
"""Creates a list of MutateOperations that create a new linked image asset.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
url: the url of the image to be retrieved and put into an asset.
field_type: the field_type of the new asset in the AssetGroupAsset.
asset_name: the asset name.
Returns:
MutateOperations that create a new linked image asset.
"""
global next_temp_id
operations = []
asset_service = client.get_service("AssetService")
asset_group_service = client.get_service("AssetGroupService")
# Create the Image Asset.
mutate_operation = client.get_type("MutateOperation")
asset = mutate_operation.asset_operation.create
asset.resource_name = asset_service.asset_path(customer_id, next_temp_id)
asset.type_ = client.enums.AssetTypeEnum.IMAGE
# Provide a unique friendly name to identify your asset.
# When there is an existing image asset with the same content but a different
# name, the new name will be dropped silently.
asset.name = asset_name
asset.image_asset.data = _get_image_bytes(url)
operations.append(mutate_operation)
# Create an AssetGroupAsset to link the Asset to the AssetGroup.
mutate_operation = client.get_type("MutateOperation")
asset_group_asset = mutate_operation.asset_group_asset_operation.create
asset_group_asset.field_type = field_type
asset_group_asset.asset_group = asset_group_service.asset_group_path(
customer_id,
_ASSET_GROUP_TEMPORARY_ID,
)
asset_group_asset.asset = asset_service.asset_path(
customer_id, next_temp_id
)
operations.append(mutate_operation)
next_temp_id -= 1
return operations
def _get_customer_conversion_goals(client, customer_id):
"""Retrieves the list of customer conversion goals.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
Returns:
a list of dicts containing the category and origin of customer
conversion goals.
"""
ga_service = client.get_service("GoogleAdsService")
customer_conversion_goals = []
query = """
SELECT
customer_conversion_goal.category,
customer_conversion_goal.origin
FROM customer_conversion_goal
"""
# The number of conversion goals is typically less than 50 so we use
# GoogleAdsService.search instead of search_stream.
search_request = client.get_type("SearchGoogleAdsRequest")
search_request.customer_id = customer_id
search_request.query = query
search_request.page_size = 10000
results = ga_service.search(request=search_request)
# Iterate over the results and build the list of conversion goals.
for row in results:
customer_conversion_goals.append(
{
"category": row.customer_conversion_goal.category,
"origin": row.customer_conversion_goal.origin,
}
)
return customer_conversion_goals
def _create_conversion_goal_operations(
client,
customer_id,
customer_conversion_goals,
):
"""Creates a list of MutateOperations that override customer conversion goals.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
customer_conversion_goals: the list of customer conversion goals that
will be overridden.
Returns:
MutateOperations that update campaign conversion goals.
"""
campaign_conversion_goal_service = client.get_service(
"CampaignConversionGoalService"
)
operations = []
# To override the customer conversion goals, we will change the
# biddability of each of the customer conversion goals so that only
# the desired conversion goal is biddable in this campaign.
for customer_conversion_goal in customer_conversion_goals:
mutate_operation = client.get_type("MutateOperation")
campaign_conversion_goal = (
mutate_operation.campaign_conversion_goal_operation.update
)
campaign_conversion_goal.resource_name = (
campaign_conversion_goal_service.campaign_conversion_goal_path(
customer_id,
_PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID,
customer_conversion_goal["category"].name,
customer_conversion_goal["origin"].name,
)
)
# Change the biddability for the campaign conversion goal.
# Set biddability to True for the desired (category, origin).
# Set biddability to False for all other conversion goals.
# Note:
# 1- It is assumed that this Conversion Action
# (category=PURCHASE, origin=WEBSITE) exists in this account.
# 2- More than one goal can be biddable if desired. This example
# shows only one.
if (
customer_conversion_goal["category"]
== client.enums.ConversionActionCategoryEnum.PURCHASE
and customer_conversion_goal["origin"]
== client.enums.ConversionOriginEnum.WEBSITE
):
biddable = True
else:
biddable = False
campaign_conversion_goal.biddable = biddable
field_mask = protobuf_helpers.field_mask(
None, campaign_conversion_goal._pb
)
client.copy_from(
mutate_operation.campaign_conversion_goal_operation.update_mask,
field_mask,
)
operations.append(mutate_operation)
return operations
def _get_image_bytes(url):
"""Loads image data from a URL.
Args:
url: a URL str.
Returns:
Images bytes loaded from the given URL.
"""
response = requests.get(url)
return response.content
def _print_response_details(response):
"""Prints the details of a MutateGoogleAdsResponse.
Parses the "response" oneof field name and uses it to extract the new
entity's name and resource name.
Args:
response: a MutateGoogleAdsResponse object.
"""
# Parse the Mutate response to print details about the entities that
# were created by the request.
suffix = "_result"
for result in response.mutate_operation_responses:
for field_descriptor, value in result._pb.ListFields():
if field_descriptor.name.endswith(suffix):
name = field_descriptor.name[: -len(suffix)]
else:
name = field_descriptor.name
print(
f"Created a(n) {convert_snake_case_to_upper_case(name)} with "
f"{str(value).strip()}."
)
if __name__ == "__main__":
# GoogleAdsClient will read the google-ads.yaml configuration file in the
# home directory if none is specified.
googleads_client = GoogleAdsClient.load_from_storage(version="v10")
parser = argparse.ArgumentParser(
description=("Creates a Performance Max retail campaign.")
)
# The following argument(s) should be provided to run the example.
parser.add_argument(
"-c",
"--customer_id",
type=str,
required=True,
help="The Google Ads customer ID.",
)
parser.add_argument(
"-m",
"--merchant_center_account_id",
type=int,
required=True,
help="The Merchant Center account ID.",
)
parser.add_argument(
"-f",
"--sales_country",
type=str,
required=False,
default="US",
help="The sales country of products to include in the campaign",
)
parser.add_argument(
"-u",
"--final_url",
type=str,
required=False,
default="http://www.example.com",
help="The final URL for the asset group of the campaign.",
)
args = parser.parse_args()
try:
main(
googleads_client,
args.customer_id,
args.merchant_center_account_id,
args.sales_country,
args.final_url,
)
except GoogleAdsException as ex:
print(
f'Request with ID "{ex.request_id}" failed with status '
f'"{ex.error.code().name}" and includes the following errors:'
)
for error in ex.failure.errors:
print(f'Error with message "{error.message}".')
if error.location:
for field_path_element in error.location.field_path_elements:
print(f"\t\tOn field: {field_path_element.field_name}")
sys.exit(1)
Ruby
#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# This example shows how to create a Performance Max retail campaign.
#
# This will be created for "All products".
#
# For more information about Performance Max retail campaigns, see
# https://developers.google.com/google-ads/api/docs/performance-max/retail
#
# Prerequisites:
# - You need to have access to a Merchant Center account. You can find
# instructions to create a Merchant Center account here:
# https://support.google.com/merchants/answer/188924.
# This account must be linked to your Google Ads account. The integration
# instructions can be found at:
# https://developers.google.com/google-ads/api/docs/shopping-ads/merchant-center
# - You need your Google Ads account to track conversions. The different ways
# to track conversions can be found here:
# https://support.google.com/google-ads/answer/1722054.
# - You must have at least one conversion action in the account. For
# more about conversion actions, see
# https://developers.google.com/google-ads/api/docs/conversions/overview#conversion_actions
require 'optparse'
require 'date'
require 'open-uri'
require 'google/ads/google_ads'
# We specify temporary IDs that are specific to a single mutate request.
# Temporary IDs are always negative and unique within one mutate request.
#
# See https://developers.google.com/google-ads/api/docs/mutating/best-practices
# for further details.
#
# These temporary IDs are fixed because they are used in multiple places.
BUDGET_TEMPORARY_ID = "-1"
PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID = "-2"
ASSET_GROUP_TEMPORARY_ID = "-3"
# There are also entities that will be created in the same request but do not
# need to be fixed temporary IDs because they are referenced only once.
def next_temp_id
@id ||= ASSET_GROUP_TEMPORARY_ID.to_i
@id -= 1
end
def add_performance_max_retail_campaign(
customer_id,
merchant_center_account_id,
sales_country,
final_url)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# This campaign will override the customer conversion goals.
# Retrieve the current list of customer conversion goals.
customer_conversion_goals = _get_customer_conversion_goals(
client, customer_id)
# Performance Max campaigns require that repeated assets such as headlines
# and descriptions be created before the campaign.
# For the list of required assets for a Performance Max campaign, see
# https://developers.google.com/google-ads/api/docs/performance-max/assets
#
# Create the headlines.
headline_asset_resource_names = create_multiple_text_assets(
client,
customer_id,
[
"Travel",
"Travel Reviews",
"Book travel",
])
# Create the descriptions.
description_asset_resource_names = create_multiple_text_assets(
client,
customer_id,
[
"Take to the air!",
"Fly to the sky!",
])
# The below methods create and return MutateOperations that we later
# provide to the GoogleAdsService.Mutate method in order to create the
# entities in a single request. Since the entities for a Performance Max
# campaign are closely tied to one-another, it's considered a best practice
# to create them in a single Mutate request so they all complete
# successfully or fail entirely, leaving no orphaned entities. See:
# https://developers.google.com/google-ads/api/docs/mutating/overview
campaign_budget_operation = create_campaign_budget_operation(
client,
customer_id,
)
performance_max_campaign_operation = create_performance_max_campaign_operation(
client,
customer_id,
merchant_center_account_id,
sales_country,
)
campaign_criterion_operations = create_campaign_criterion_operations(
client,
customer_id,
)
asset_group_operations = create_asset_group_operation(
client,
customer_id,
final_url,
headline_asset_resource_names,
description_asset_resource_names,
)
conversion_goal_operations = create_conversion_goal_operations(
client,
customer_id,
customer_conversion_goals,
)
asset_group_listing_group_operations = create_asset_group_listing_group_operations(
client,
customer_id,
)
# Send the operations in a single Mutate request.
response = client.service.google_ads.mutate(
customer_id: customer_id,
mutate_operations: [
# It's important to create these entities in this order because
# they depend on each other.
campaign_budget_operation,
performance_max_campaign_operation,
# Expand the list of multiple operations into the list of
# other mutate operations
campaign_criterion_operations,
asset_group_operations,
conversion_goal_operations,
asset_group_listing_group_operations,
].flatten)
print_response_details(response)
end
# Creates a MutateOperation that creates a new CampaignBudget.
#
# A temporary ID will be assigned to this campaign budget so that it can be
# referenced by other objects being created in the same Mutate request.
def create_campaign_budget_operation(client, customer_id)
client.operation.mutate do |m|
m.campaign_budget_operation = client.operation.create_resource.campaign_budget do |cb|
cb.name = "Performance Max campaign budget #{SecureRandom.uuid}"
# The budget period already defaults to DAILY.
cb.amount_micros = 50_000_000
cb.delivery_method = :STANDARD
# A Performance Max campaign cannot use a shared campaign budget.
cb.explicitly_shared = false
# Set a temporary ID in the budget's resource name so it can be referenced
# by the campaign in later steps.
cb.resource_name = client.path.campaign_budget(customer_id, BUDGET_TEMPORARY_ID)
end
end
end
# Creates a MutateOperation that creates a new Performance Max campaign.
#
# A temporary ID will be assigned to this campaign so that it can
# be referenced by other objects being created in the same Mutate request.
def create_performance_max_campaign_operation(
client,
customer_id,
merchant_center_account_id,
sales_country)
client.operation.mutate do |m|
m.campaign_operation = client.operation.create_resource.campaign do |c|
c.name = "Performance Max retail campaign #{SecureRandom.uuid}"
# Set the campaign status as PAUSED. The campaign is the only entity in
# the mutate request that should have its status set.
c.status = :PAUSED
# All Performance Max campaigns have an advertising_channel_type of
# PERFORMANCE_MAX. The advertising_channel_sub_type should not be set.
c.advertising_channel_type = :PERFORMANCE_MAX
# Bidding strategy must be set directly on the campaign.
# Setting a portfolio bidding strategy by resource name is not supported.
# Max Conversion and Maximize Conversion Value are the only strategies
# supported for Performance Max campaigns.
# An optional ROAS (Return on Advertising Spend) can be set for
# maximize_conversion_value. The ROAS value must be specified as a ratio in
# the API. It is calculated by dividing "total value" by "total spend".
# For more information on Maximize Conversion Value, see the support
# article: http://support.google.com/google-ads/answer/7684216.
# A target_roas of 3.5 corresponds to a 350% return on ad spend.
c.bidding_strategy_type = :MAXIMIZE_CONVERSION_VALUE
c.maximize_conversion_value = client.resource.maximize_conversion_value do |mcv|
mcv.target_roas = 3.5
end
# Set the shopping settings.
c.shopping_setting = client.resource.shopping_setting do |ss|
ss.merchant_id = merchant_center_account_id
ss.sales_country = sales_country
end
# Set the Final URL expansion opt out. This flag is specific to
# Performance Max campaigns. If opted out (true), only the final URLs in
# the asset group or URLs specified in the advertiser's Google Merchant
# Center or business data feeds are targeted.
# If opted in (false), the entire domain will be targeted. For best
# results, set this value to false to opt in and allow URL expansions. You
# can optionally add exclusions to limit traffic to parts of your website.
#
# For a Retail campaign, we want the final URLs to be limited to those
# explicitly surfaced via GMC.
c.url_expansion_opt_out = true
# Assign the resource name with a temporary ID.
c.resource_name = client.path.campaign(customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID)
# Set the budget using the given budget resource name.
c.campaign_budget = client.path.campaign_budget(customer_id, BUDGET_TEMPORARY_ID)
# Optional fields
c.start_date = DateTime.parse((Date.today + 1).to_s).strftime('%Y%m%d')
c.end_date = DateTime.parse(Date.today.next_year.to_s).strftime('%Y%m%d')
end
end
end
# Creates a list of MutateOperations that create new campaign criteria.
def create_campaign_criterion_operations(client, customer_id)
operations = []
# Set the LOCATION campaign criteria.
# Target all of New York City except Brooklyn.
# Location IDs are listed here:
# https://developers.google.com/google-ads/api/reference/data/geotargets
# and they can also be retrieved using the GeoTargetConstantService as shown
# here: https://developers.google.com/google-ads/api/docs/targeting/location-targeting
#
# We will add one positive location target for New York City (ID=1023191)
# and one negative location target for Brooklyn (ID=1022762).
# First, add the positive (negative = false) for New York City.
operations << client.operation.mutate do |m|
m.campaign_criterion_operation =
client.operation.create_resource.campaign_criterion do |cc|
cc.campaign = client.path.campaign(
customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID)
cc.location = client.resource.location_info do |li|
li.geo_target_constant = client.path.geo_target_constant("1023191")
end
cc.negative = false
end
end
# Next add the negative target for Brooklyn.
operations << client.operation.mutate do |m|
m.campaign_criterion_operation =
client.operation.create_resource.campaign_criterion do |cc|
cc.campaign = client.path.campaign(
customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID)
cc.location = client.resource.location_info do |li|
li.geo_target_constant = client.path.geo_target_constant("1022762")
end
cc.negative = true
end
end
# Set the LANGUAGE campaign criterion.
operations << client.operation.mutate do |m|
m.campaign_criterion_operation =
client.operation.create_resource.campaign_criterion do |cc|
cc.campaign = client.path.campaign(
customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID)
# Set the language.
# For a list of all language codes, see:
# https://developers.google.com/google-ads/api/reference/data/codes-formats#expandable-7
cc.language = client.resource.language_info do |li|
li.language_constant = client.path.language_constant("1000") # English
end
end
end
operations
end
# Creates multiple text assets and returns the list of resource names.
def create_multiple_text_assets(client, customer_id, texts)
operations = texts.map do |text|
client.operation.mutate do |m|
m.asset_operation = client.operation.create_resource.asset do |asset|
asset.text_asset = client.resource.text_asset do |text_asset|
text_asset.text = text
end
end
end
end
# Send the operations in a single Mutate request.
response = client.service.google_ads.mutate(
customer_id: customer_id,
mutate_operations: operations,
)
asset_resource_names = []
response.mutate_operation_responses.each do |result|
if result.asset_result
asset_resource_names.append(result.asset_result.resource_name)
end
end
print_response_details(response)
asset_resource_names
end
# Creates a list of MutateOperations that create a new asset_group.
#
# A temporary ID will be assigned to this asset group so that it can
# be referenced by other objects being created in the same Mutate request.
def create_asset_group_operation(
client,
customer_id,
final_url,
headline_asset_resource_names,
description_asset_resource_names)
operations = []
# Create the AssetGroup
operations << client.operation.mutate do |m|
m.asset_group_operation = client.operation.create_resource.asset_group do |ag|
ag.name = "Performance Max retail asset group #{SecureRandom.uuid}"
ag.campaign = client.path.campaign(
customer_id,
PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID)
ag.final_urls << final_url
ag.final_mobile_urls << final_url
ag.status = :PAUSED
ag.resource_name = client.path.asset_group(
customer_id,
ASSET_GROUP_TEMPORARY_ID)
end
end
# For the list of required assets for a Performance Max campaign, see
# https://developers.google.com/google-ads/api/docs/performance-max/assets
#
# An AssetGroup is linked to an Asset by creating a new AssetGroupAsset
# and providing:
# the resource name of the AssetGroup
# the resource name of the Asset
# the field_type of the Asset in this AssetGroup.
#
# To learn more about AssetGroups, see
# https://developers.google.com/google-ads/api/docs/performance-max/asset-groups
# Link the previously created multiple text assets.
# Link the headline assets.
headline_asset_resource_names.each do |resource_name|
operations << client.operation.mutate do |m|
m.asset_group_asset_operation = client.operation.create_resource
.asset_group_asset do |aga|
aga.field_type = :HEADLINE
aga.asset_group = client.path.asset_group(
customer_id,
ASSET_GROUP_TEMPORARY_ID)
aga.asset = resource_name
end
end
end
# Link the description assets.
description_asset_resource_names.each do |resource_name|
operations << client.operation.mutate do |m|
m.asset_group_asset_operation = client.operation.create_resource
.asset_group_asset do |aga|
aga.field_type = :DESCRIPTION
aga.asset_group = client.path.asset_group(
customer_id,
ASSET_GROUP_TEMPORARY_ID)
aga.asset = resource_name
end
end
end
# Create and link the long headline text asset.
operations += create_and_link_text_asset(
client,
customer_id,
"Travel the World",
:LONG_HEADLINE)
# Create and link the business name text asset.
operations += create_and_link_text_asset(
client,
customer_id,
"Interplanetary Cruises",
:BUSINESS_NAME)
# Create and link the image assets.
# Create and link the Logo Asset.
operations += create_and_link_image_asset(
client,
customer_id,
"https://gaagl.page.link/bjYi",
:LOGO,
"Logo Image")
# Create and link the Marketing Image Asset.
operations += create_and_link_image_asset(
client,
customer_id,
"https://gaagl.page.link/Eit5",
:MARKETING_IMAGE,
"Marketing Image")
# Create and link the Square Marketing Image Asset.
operations += create_and_link_image_asset(
client,
customer_id,
"https://gaagl.page.link/bjYi",
:SQUARE_MARKETING_IMAGE,
"Square Marketing Image")
operations
end
# Creates a list of MutateOperations that create a new linked text asset.
def create_and_link_text_asset(client, customer_id, text, field_type)
operations = []
temp_id = next_temp_id
# Create the Text Asset.
operations << client.operation.mutate do |m|
m.asset_operation = client.operation.create_resource.asset do |a|
a.resource_name = client.path.asset(customer_id, temp_id)
a.text_asset = client.resource.text_asset do |text_asset|
text_asset.text = text
end
end
end
# Create an AssetGroupAsset to link the Asset to the AssetGroup.
operations << client.operation.mutate do |m|
m.asset_group_asset_operation = client.operation.create_resource
.asset_group_asset do |aga|
aga.field_type = field_type
aga.asset_group = client.path.asset_group(
customer_id,
ASSET_GROUP_TEMPORARY_ID)
aga.asset = client.path.asset(customer_id, temp_id)
end
end
operations
end
# Creates a list of MutateOperations that create a new linked image asset.
def create_and_link_image_asset(client, customer_id, url, field_type, asset_name)
operations = []
temp_id = next_temp_id
# Create the Image Asset.
operations << client.operation.mutate do |m|
m.asset_operation = client.operation.create_resource.asset do |a|
a.resource_name = client.path.asset(customer_id, temp_id)
a.type = :IMAGE
# Provide a unique friendly name to identify your asset.
# When there is an existing image asset with the same content but a different
# name, the new name will be dropped silently.
a.name = asset_name
a.image_asset = client.resource.image_asset do |image_asset|
image_asset.data = get_image_bytes(url)
end
end
end
# Create an AssetGroupAsset to link the Asset to the AssetGroup.
operations << client.operation.mutate do |m|
m.asset_group_asset_operation = client.operation.create_resource
.asset_group_asset do |aga|
aga.field_type = field_type
aga.asset_group = client.path.asset_group(
customer_id,
ASSET_GROUP_TEMPORARY_ID)
aga.asset = client.path.asset(customer_id, temp_id)
end
end
operations
end
def _get_customer_conversion_goals(client, customer_id)
query = <<~EOD
SELECT
customer_conversion_goal.category,
customer_conversion_goal.origin
FROM customer_conversion_goal
EOD
customer_conversion_goals = []
ga_service = client.service.google_ads
# The number of conversion goals is typically less than 50 so we use
# GoogleAdsService.search instead of search_stream.
response = ga_service.search(
customer_id: customer_id,
query: query,
page_size: PAGE_SIZE,
)
# Iterate over the results and build the list of conversion goals.
response.each do |row|
customer_conversion_goals << {
"category" => row.customer_conversion_goal.category,
"origin" => row.customer_conversion_goal.origin
}
end
customer_conversion_goals
end
def create_conversion_goal_operations(client, customer_id, customer_conversion_goals)
campaign_conversion_goal_service = client.service.campaign_conversion_goal
operations = []
# To override the customer conversion goals, we will change the
# biddability of each of the customer conversion goals so that only
# the desired conversion goal is biddable in this campaign.
customer_conversion_goals.each do |customer_conversion_goal|
operations << client.operation.mutate do |m|
m.campaign_conversion_goal_operation = client.operation.campaign_conversion_goal do |op|
op.update = client.resource.campaign_conversion_goal do |ccg|
ccg.resource_name = client.path.campaign_conversion_goal(
customer_id,
PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID,
customer_conversion_goal["category"].to_s,
customer_conversion_goal["origin"].to_s)
# Change the biddability for the campaign conversion goal.
# Set biddability to True for the desired (category, origin).
# Set biddability to False for all other conversion goals.
# Note:
# 1- It is assumed that this Conversion Action
# (category=PURCHASE, origin=WEBSITE) exists in this account.
# 2- More than one goal can be biddable if desired. This example
# shows only one.
ccg.biddable = (customer_conversion_goal["category"] == :PURCHASE &&
customer_conversion_goal["origin"] == :WEBSITE)
end
op.update_mask = Google::Ads::GoogleAds::FieldMaskUtil.all_set_fields_of(op.update)
end
end
end
operations
end
# Create a list of MutateOperations that create a new asset group listing group filter.
def create_asset_group_listing_group_operations(client, customer_id)
operations = []
operations << client.operation.create_resource.
asset_group_listing_group_filter do |lgf|
lgf.asset_group = client.path.asset_group(customer_id, ASSET_GROUP_TEMPORARY_ID)
# Since this is the root node, do not set the ParentListingGroupFilter. For all
# other nodes, this would refer to the parent listing group filter resource name.
# lgf.parent_listing_group_filter = "<PARENT FILTER NAME>"
lgf.type = :UNIT_INCLUDED
lgf.vertical = :SHOPPING
end
operations
end
# Loads image data from a URL.
def get_image_bytes(url)
URI.open(url).read
end
# Prints the details of a MutateGoogleAdsResponse.
def print_response_details(response)
# Parse the mutate response to print details about the entities that
# were created by the request.
suffix = "_result"
response.mutate_operation_responses.each do |result|
result.to_h.select {|k, v| v }.each do |name, value|
if name.to_s.end_with?(suffix)
name = name.to_s.delete_suffix(suffix)
end
puts "Created a(n) #{::Google::Ads::GoogleAds::Utils.camelize(name)} " \
"with #{value.to_s.strip}."
end
end
end
if __FILE__ == $0
PAGE_SIZE = 1000
options = {}
# The following parameter(s) should be provided to run the example. You can
# either specify these by changing the INSERT_XXX_ID_HERE values below, or on
# the command line.
#
# Parameters passed on the command line will override any parameters set in
# code.
#
# Running the example with -h will print the command line usage.
options[:customer_id] = 'INSERT_CUSTOMER_ID_HERE'
options[:merchant_center_account_id] = 'INSERT_MERCHANT_CENTER_ACCOUNT_ID_HERE'
options[:sales_country] = 'INSERT_SALES_COUNTRY_HERE'
options[:final_url] = 'INSERT_FINAL_URL_HERE'
OptionParser.new do |opts|
opts.banner = sprintf('Usage: %s [options]', File.basename(__FILE__))
opts.separator ''
opts.separator 'Options:'
opts.on('-C', '--customer-id CUSTOMER-ID', String, 'Customer ID') do |v|
options[:customer_id] = v
end
opts.on('-m', '--merchant-center-account-id MERCHANT-CENTER-ACCOUNT-ID',
Integer, 'Merchant Center Account ID') do |v|
options[:merchant_center_account_id] = v
end
opts.on('-s', '--sales-country-id SALES-COUNTRY', String, 'Sales Country') do |v|
options[:sales_country] = v
end
opts.on('-f', '--final-url FINAL-URL', String, 'Final URL') do |v|
options[:final_url] = v
end
opts.separator ''
opts.separator 'Help:'
opts.on_tail('-h', '--help', 'Show this message') do
puts opts
exit
end
end.parse!
begin
add_performance_max_retail_campaign(
options.fetch(:customer_id).tr("-", ""),
options.fetch(:merchant_center_account_id),
options.fetch(:sales_country),
options.fetch(:final_url))
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
e.failure.errors.each do |error|
STDERR.printf("Error with message: %s\n", error.message)
if error.location
error.location.field_path_elements.each do |field_path_element|
STDERR.printf("\tOn field: %s\n", field_path_element.field_name)
end
end
error.error_code.to_h.each do |k, v|
next if v == :UNSPECIFIED
STDERR.printf("\tType: %s\n\tCode: %s\n", k, v)
end
end
raise
end
end
Perl
#!/usr/bin/perl -w
#
# Copyright 2021, Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# This example shows how to create a Performance Max retail campaign.
#
# This will be created for "All products".
#
# For more information about Performance Max retail campaigns, see
# https://developers.google.com/google-ads/api/docs/performance-max/retail.
#
# Prerequisites:
# - You need to have access to a Merchant Center account. You can find
# instructions to create a Merchant Center account here:
# https://support.google.com/merchants/answer/188924.
# This account must be linked to your Google Ads account. The integration
# instructions can be found at:
# https://developers.google.com/google-ads/api/docs/shopping-ads/merchant-center.
# - You need your Google Ads account to track conversions. The different ways
# to track conversions can be found here:
# https://support.google.com/google-ads/answer/1722054.
# - You must have at least one conversion action in the account. For more about
# conversion actions, see
# https://developers.google.com/google-ads/api/docs/conversions/overview#conversion_actions.
use strict;
use warnings;
use utf8;
use FindBin qw($Bin);
use lib "$Bin/../../lib";
use Google::Ads::GoogleAds::Client;
use Google::Ads::GoogleAds::Utils::GoogleAdsHelper;
use Google::Ads::GoogleAds::Utils::MediaUtils;
use Google::Ads::GoogleAds::Utils::FieldMasks;
use Google::Ads::GoogleAds::V11::Resources::CampaignBudget;
use Google::Ads::GoogleAds::V11::Resources::Campaign;
use Google::Ads::GoogleAds::V11::Resources::ShoppingSetting;
use Google::Ads::GoogleAds::V11::Resources::CampaignCriterion;
use Google::Ads::GoogleAds::V11::Resources::Asset;
use Google::Ads::GoogleAds::V11::Resources::AssetGroup;
use Google::Ads::GoogleAds::V11::Resources::AssetGroupAsset;
use Google::Ads::GoogleAds::V11::Resources::CampaignConversionGoal;
use Google::Ads::GoogleAds::V11::Resources::AssetGroupListingGroupFilter;
use Google::Ads::GoogleAds::V11::Common::MaximizeConversionValue;
use Google::Ads::GoogleAds::V11::Common::LocationInfo;
use Google::Ads::GoogleAds::V11::Common::LanguageInfo;
use Google::Ads::GoogleAds::V11::Common::TextAsset;
use Google::Ads::GoogleAds::V11::Common::ImageAsset;
use Google::Ads::GoogleAds::V11::Enums::BudgetDeliveryMethodEnum qw(STANDARD);
use Google::Ads::GoogleAds::V11::Enums::CampaignStatusEnum;
use Google::Ads::GoogleAds::V11::Enums::AdvertisingChannelTypeEnum
qw(PERFORMANCE_MAX);
use Google::Ads::GoogleAds::V11::Enums::AssetGroupStatusEnum;
use Google::Ads::GoogleAds::V11::Enums::AssetFieldTypeEnum
qw(HEADLINE DESCRIPTION LONG_HEADLINE BUSINESS_NAME LOGO MARKETING_IMAGE SQUARE_MARKETING_IMAGE);
use Google::Ads::GoogleAds::V11::Enums::ConversionActionCategoryEnum
qw(PURCHASE);
use Google::Ads::GoogleAds::V11::Enums::ConversionOriginEnum qw(WEBSITE);
use Google::Ads::GoogleAds::V11::Enums::ListingGroupFilterTypeEnum
qw(UNIT_INCLUDED);
use Google::Ads::GoogleAds::V11::Enums::ListingGroupFilterVerticalEnum
qw(SHOPPING);
use Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation;
use
Google::Ads::GoogleAds::V11::Services::CampaignBudgetService::CampaignBudgetOperation;
use Google::Ads::GoogleAds::V11::Services::CampaignService::CampaignOperation;
use
Google::Ads::GoogleAds::V11::Services::CampaignCriterionService::CampaignCriterionOperation;
use Google::Ads::GoogleAds::V11::Services::AssetService::AssetOperation;
use
Google::Ads::GoogleAds::V11::Services::AssetGroupService::AssetGroupOperation;
use
Google::Ads::GoogleAds::V11::Services::AssetGroupAssetService::AssetGroupAssetOperation;
use
Google::Ads::GoogleAds::V11::Services::CampaignConversionGoalService::CampaignConversionGoalOperation;
use
Google::Ads::GoogleAds::V11::Services::AssetGroupListingGroupFilterService::AssetGroupListingGroupFilterOperation;
use Google::Ads::GoogleAds::V11::Utils::ResourceNames;
use Getopt::Long qw(:config auto_help);
use Pod::Usage;
use Cwd qw(abs_path);
use Data::Uniqid qw(uniqid);
use POSIX qw(strftime);
# We specify temporary IDs that are specific to a single mutate request.
# Temporary IDs are always negative and unique within one mutate request.
#
# See https://developers.google.com/google-ads/api/docs/mutating/best-practices
# for further details.
#
# These temporary IDs are fixed because they are used in multiple places.
use constant BUDGET_TEMPORARY_ID => -1;
use constant PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID => -2;
use constant ASSET_GROUP_TEMPORARY_ID => -3;
# There are also entities that will be created in the same request but do not
# need to be fixed temporary IDs because they are referenced only once.
our $next_temp_id = ASSET_GROUP_TEMPORARY_ID - 1;
use constant PAGE_SIZE => 1000;
# The following parameter(s) should be provided to run the example. You can
# either specify these by changing the INSERT_XXX_ID_HERE values below, or on
# the command line.
#
# Parameters passed on the command line will override any parameters set in
# code.
#
# Running the example with -h will print the command line usage.
my $customer_id = "INSERT_CUSTOMER_ID_HERE";
my $merchant_center_account_id = "INSERT_MERCHANT_CENTER_ACCOUNT_ID_HERE";
my $sales_country = "US";
my $final_url = "http://www.example.com";
sub add_performance_max_retail_campaign {
my ($api_client, $customer_id, $merchant_center_account_id, $sales_country,
$final_url)
= @_;
# This campaign will override the customer conversion goals.
# Retrieve the current list of customer conversion goals.
my $customer_conversion_goals =
get_customer_conversion_goals($api_client, $customer_id);
# Performance Max campaigns require that repeated assets such as headlines
# and descriptions be created before the campaign.
# For the list of required assets for a Performance Max campaign, see
# https://developers.google.com/google-ads/api/docs/performance-max/assets.
#
# Create the headlines.
my $headline_asset_resource_names =
create_multiple_text_assets($api_client, $customer_id,
["Travel", "Travel Reviews", "Book travel"]);
# Create the descriptions.
my $description_asset_resource_names =
create_multiple_text_assets($api_client, $customer_id,
["Take to the air!", "Fly to the sky!"]);
# It's important to create the below entities in this order because they depend
# on each other.
my $operations = [];
# The below methods create and return MutateOperations that we later provide to
# the GoogleAdsService->mutate() method in order to create the entities in a
# single request. Since the entities for a Performance Max campaign are closely
# tied to one-another, it's considered a best practice to create them in a
# single mutate request so they all complete successfully or fail entirely,
# leaving no orphaned entities. See:
# https://developers.google.com/google-ads/api/docs/mutating/overview.
push @$operations, create_campaign_budget_operation($customer_id);
push @$operations,
create_performance_max_campaign_operation($customer_id,
$merchant_center_account_id, $sales_country);
push @$operations, @{create_campaign_criterion_operations($customer_id)};
push @$operations,
@{
create_asset_group_operations(
$customer_id, $final_url,
$headline_asset_resource_names, $description_asset_resource_names
)};
push @$operations,
@{create_conversion_goal_operations($customer_id,
$customer_conversion_goals)};
# Retail Performance Max campaigns require listing groups, which are created
# via the AssetGroupListingGroupFilter resource.
push @$operations,
@{create_asset_group_listing_group_operations($customer_id)};
# Issue a mutate request to create everything and print its information.
my $mutate_google_ads_response = $api_client->GoogleAdsService()->mutate({
customerId => $customer_id,
mutateOperations => $operations
});
print_response_details($mutate_google_ads_response);
return 1;
}
# Creates a MutateOperation that creates a new CampaignBudget.
#
# A temporary ID will be assigned to this campaign budget so that it can be
# referenced by other objects being created in the same mutate request.
sub create_campaign_budget_operation {
my ($customer_id) = @_;
# Create a mutate operation that creates a campaign budget operation.
return
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
campaignBudgetOperation =>
Google::Ads::GoogleAds::V11::Services::CampaignBudgetService::CampaignBudgetOperation
->new({
create => Google::Ads::GoogleAds::V11::Resources::CampaignBudget->new(
{
# Set a temporary ID in the budget's resource name so it can be
# referenced by the campaign in later steps.
resourceName =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::campaign_budget(
$customer_id, BUDGET_TEMPORARY_ID
),
name => "Performance Max retail campaign budget #" . uniqid(),
# The budget period already defaults to DAILY.
amountMicros => 50000000,
deliveryMethod => STANDARD,
# A Performance Max campaign cannot use a shared campaign budget.
explicitlyShared => "false",
})})});
}
# Creates a MutateOperation that creates a new Performance Max campaign.
#
# A temporary ID will be assigned to this campaign so that it can be referenced
# by other objects being created in the same mutate request.
sub create_performance_max_campaign_operation {
my ($customer_id, $merchant_center_account_id, $sales_country) = @_;
# Create a mutate operation that creates a campaign operation.
return
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
campaignOperation =>
Google::Ads::GoogleAds::V11::Services::CampaignService::CampaignOperation
->new({
create => Google::Ads::GoogleAds::V11::Resources::Campaign->new({
# Assign the resource name with a temporary ID.
resourceName =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::campaign(
$customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
name => "Performance Max retail campaign #'" . uniqid(),
# Set the budget using the given budget resource name.
campaignBudget =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::campaign_budget(
$customer_id, BUDGET_TEMPORARY_ID
),
# Set the campaign status as PAUSED. The campaign is the only entity in
# the mutate request that should have its status set.
status =>
Google::Ads::GoogleAds::V11::Enums::CampaignStatusEnum::PAUSED,
# All Performance Max campaigns have an advertisingChannelType of
# PERFORMANCE_MAX. The advertisingChannelSubType should not be set.
advertisingChannelType => PERFORMANCE_MAX,
# Bidding strategy must be set directly on the campaign.
# Setting a portfolio bidding strategy by resource name is not supported.
# Max Conversion and Max Conversion Value are the only strategies
# supported for Performance Max campaigns.
# An optional ROAS (Return on Advertising Spend) can be set for
# maximizeConversionValue. The ROAS value must be specified as a ratio in
# the API. It is calculated by dividing "total value" by "total spend".
# For more information on Max Conversion Value, see the support article:
# http://support.google.com/google-ads/answer/7684216.
# A targetRoas of 3.5 corresponds to a 350% return on ad spend.
maximizeConversionValue =>
Google::Ads::GoogleAds::V11::Common::MaximizeConversionValue->
new({
targetRoas => 3.5
}
),
# Set the final URL expansion opt out. This flag is specific to
# Performance Max campaigns. If opted out (true), only the final URLs in
# the asset group or URLs specified in the advertiser's Google Merchant
# Center or business data feeds are targeted.
# If opted in (false), the entire domain will be targeted. For best
# results, set this value to false to opt in and allow URL expansions. You
# can optionally add exclusions to limit traffic to parts of your website.
#
# For a Retail campaign, we want the final URL to be limited to those
# explicitly surfaced via GMC.
urlExpansionOptOut => "true",
# Set the shopping settings.
shoppingSetting =>
Google::Ads::GoogleAds::V11::Resources::ShoppingSetting->new({
merchantId => $merchant_center_account_id,
salesCountry => $sales_country
}
),
# Optional fields.
startDate => strftime("%Y%m%d", localtime(time + 60 * 60 * 24)),
endDate =>
strftime("%Y%m%d", localtime(time + 60 * 60 * 24 * 365)),
})})});
}
# Creates a list of MutateOperations that create new campaign criteria.
sub create_campaign_criterion_operations {
my ($customer_id) = @_;
my $operations = [];
# Set the LOCATION campaign criteria.
# Target all of New York City except Brooklyn.
# Location IDs are listed here:
# https://developers.google.com/google-ads/api/reference/data/geotargets
# and they can also be retrieved using the GeoTargetConstantService as shown
# here: https://developers.google.com/google-ads/api/docs/targeting/location-targeting.
#
# We will add one positive location target for New York City (ID=1023191)
# and one negative location target for Brooklyn (ID=1022762).
# First, add the positive (negative = false) for New York City.
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
campaignCriterionOperation =>
Google::Ads::GoogleAds::V11::Services::CampaignCriterionService::CampaignCriterionOperation
->new({
create =>
Google::Ads::GoogleAds::V11::Resources::CampaignCriterion->new({
campaign =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::campaign(
$customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
location =>
Google::Ads::GoogleAds::V11::Common::LocationInfo->new({
geoTargetConstant =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::geo_target_constant(
1023191)}
),
negative => "false"
})})});
# Next add the negative target for Brooklyn.
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
campaignCriterionOperation =>
Google::Ads::GoogleAds::V11::Services::CampaignCriterionService::CampaignCriterionOperation
->new({
create =>
Google::Ads::GoogleAds::V11::Resources::CampaignCriterion->new({
campaign =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::campaign(
$customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
location =>
Google::Ads::GoogleAds::V11::Common::LocationInfo->new({
geoTargetConstant =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::geo_target_constant(
1022762)}
),
negative => "true"
})})});
# Set the LANGUAGE campaign criterion.
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
campaignCriterionOperation =>
Google::Ads::GoogleAds::V11::Services::CampaignCriterionService::CampaignCriterionOperation
->new({
create =>
Google::Ads::GoogleAds::V11::Resources::CampaignCriterion->new({
campaign =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::campaign(
$customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
# Set the language.
# For a list of all language codes, see:
# https://developers.google.com/google-ads/api/reference/data/codes-formats#expandable-7.
language =>
Google::Ads::GoogleAds::V11::Common::LanguageInfo->new({
languageConstant =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::language_constant(
1000) # English
})})})});
return $operations;
}
# Creates multiple text assets and returns the list of resource names.
sub create_multiple_text_assets {
my ($api_client, $customer_id, $texts) = @_;
# Here again we use the GoogleAdService to create multiple text assets in a
# single request.
my $operations = [];
foreach my $text (@$texts) {
# Create a mutate operation for a text asset.
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation
->new({
assetOperation =>
Google::Ads::GoogleAds::V11::Services::AssetService::AssetOperation->
new({
create => Google::Ads::GoogleAds::V11::Resources::Asset->new({
textAsset =>
Google::Ads::GoogleAds::V11::Common::TextAsset->new({
text => $text
})})})});
}
# Issue a mutate request to add all assets.
my $mutate_google_ads_response = $api_client->GoogleAdsService()->mutate({
customerId => $customer_id,
mutateOperations => $operations
});
my $asset_resource_names = [];
foreach
my $response (@{$mutate_google_ads_response->{mutateOperationResponses}})
{
push @$asset_resource_names, $response->{assetResult}{resourceName};
}
print_response_details($mutate_google_ads_response);
return $asset_resource_names;
}
# Creates a list of MutateOperations that create a new asset group.
#
# A temporary ID will be assigned to this asset group so that it can be referenced
# by other objects being created in the same mutate request.
sub create_asset_group_operations {
my (
$customer_id, $final_url,
$headline_asset_resource_names,
$description_asset_resource_names
) = @_;
my $operations = [];
# Create a mutate operation that creates an asset group operation.
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
assetGroupOperation =>
Google::Ads::GoogleAds::V11::Services::AssetGroupService::AssetGroupOperation
->new({
create => Google::Ads::GoogleAds::V11::Resources::AssetGroup->new({
resourceName =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset_group(
$customer_id, ASSET_GROUP_TEMPORARY_ID
),
name => "Performance Max retail asset group #" . uniqid(),
campaign =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::campaign(
$customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
),
finalUrls => [$final_url],
finalMobileUrls => [$final_url],
status =>
Google::Ads::GoogleAds::V11::Enums::AssetGroupStatusEnum::PAUSED
})})});
# For the list of required assets for a Performance Max campaign, see
# https://developers.google.com/google-ads/api/docs/performance-max/assets.
# An AssetGroup is linked to an Asset by creating a new AssetGroupAsset
# and providing:
# - the resource name of the AssetGroup
# - the resource name of the Asset
# - the fieldType of the Asset in this AssetGroup
#
# To learn more about AssetGroups, see
# https://developers.google.com/google-ads/api/docs/performance-max/asset-groups.
# Link the previously created multiple text assets.
# Link the headline assets.
foreach my $resource_name (@$headline_asset_resource_names) {
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation
->new({
assetGroupAssetOperation =>
Google::Ads::GoogleAds::V11::Services::AssetGroupAssetService::AssetGroupAssetOperation
->new({
create =>
Google::Ads::GoogleAds::V11::Resources::AssetGroupAsset->new({
asset => $resource_name,
assetGroup =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset_group(
$customer_id, ASSET_GROUP_TEMPORARY_ID
),
fieldType => HEADLINE
})})});
}
# Link the description assets.
foreach my $resource_name (@$description_asset_resource_names) {
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation
->new({
assetGroupAssetOperation =>
Google::Ads::GoogleAds::V11::Services::AssetGroupAssetService::AssetGroupAssetOperation
->new({
create =>
Google::Ads::GoogleAds::V11::Resources::AssetGroupAsset->new({
asset => $resource_name,
assetGroup =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset_group(
$customer_id, ASSET_GROUP_TEMPORARY_ID
),
fieldType => DESCRIPTION
})})});
}
# Create and link the long headline text asset.
push @$operations,
@{create_and_link_text_asset($customer_id, "Travel the World",
LONG_HEADLINE)};
# Create and link the business name text asset.
push @$operations,
@{
create_and_link_text_asset($customer_id, "Interplanetary Cruises",
BUSINESS_NAME)};
# Create and link the image assets.
# Create and link the logo asset.
push @$operations,
@{
create_and_link_image_asset($customer_id, "https://gaagl.page.link/bjYi",
LOGO, "Logo Image")};
# Create and link the marketing image asset.
push @$operations,
@{
create_and_link_image_asset(
$customer_id, "https://gaagl.page.link/Eit5",
MARKETING_IMAGE, "Marketing Image"
)};
# Create and link the square marketing image asset.
push @$operations,
@{
create_and_link_image_asset(
$customer_id, "https://gaagl.page.link/bjYi",
SQUARE_MARKETING_IMAGE, "Square Marketing Image"
)};
return $operations;
}
# Creates a list of MutateOperations that create a new linked text asset.
sub create_and_link_text_asset {
my ($customer_id, $text, $field_type) = @_;
my $operations = [];
# Create a new mutate operation for a text asset.
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
assetOperation =>
Google::Ads::GoogleAds::V11::Services::AssetService::AssetOperation->
new({
create => Google::Ads::GoogleAds::V11::Resources::Asset->new({
resourceName =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset(
$customer_id, $next_temp_id
),
textAsset => Google::Ads::GoogleAds::V11::Common::TextAsset->new({
text => $text
})})})});
# Create an asset group asset to link the asset to the asset group.
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
assetGroupAssetOperation =>
Google::Ads::GoogleAds::V11::Services::AssetGroupAssetService::AssetGroupAssetOperation
->new({
create =>
Google::Ads::GoogleAds::V11::Resources::AssetGroupAsset->new({
asset => Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset(
$customer_id, $next_temp_id
),
assetGroup =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset_group(
$customer_id, ASSET_GROUP_TEMPORARY_ID
),
fieldType => $field_type
})})});
$next_temp_id--;
return $operations;
}
# Creates a list of MutateOperations that create a new linked image asset.
sub create_and_link_image_asset {
my ($customer_id, $url, $field_type, $asset_name) = @_;
my $operations = [];
# Create a new mutate operation for an image asset.
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
assetOperation =>
Google::Ads::GoogleAds::V11::Services::AssetService::AssetOperation->
new({
create => Google::Ads::GoogleAds::V11::Resources::Asset->new({
resourceName =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset(
$customer_id, $next_temp_id
),
# Provide a unique friendly name to identify your asset.
# When there is an existing image asset with the same content but a different
# name, the new name will be dropped silently.
name => $asset_name,
imageAsset =>
Google::Ads::GoogleAds::V11::Common::ImageAsset->new({
data => get_base64_data_from_url($url)})})})});
# Create an asset group asset to link the asset to the asset group.
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
assetGroupAssetOperation =>
Google::Ads::GoogleAds::V11::Services::AssetGroupAssetService::AssetGroupAssetOperation
->new({
create =>
Google::Ads::GoogleAds::V11::Resources::AssetGroupAsset->new({
asset => Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset(
$customer_id, $next_temp_id
),
assetGroup =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset_group(
$customer_id, ASSET_GROUP_TEMPORARY_ID
),
fieldType => $field_type
})})});
$next_temp_id--;
return $operations;
}
# Retrieves the list of customer conversion goals.
sub get_customer_conversion_goals {
my ($api_client, $customer_id) = @_;
my $customer_conversion_goals = [];
# Create a query that retrieves all customer conversion goals.
my $query =
"SELECT customer_conversion_goal.category, customer_conversion_goal.origin "
. "FROM customer_conversion_goal";
# The number of conversion goals is typically less than 50 so we use
# GoogleAdsService->search() method instead of search_stream().
my $search_response = $api_client->GoogleAdsService()->search({
customerId => $customer_id,
query => $query,
pageSize => PAGE_SIZE
});
# Iterate over the results and build the list of conversion goals.
foreach my $google_ads_row (@{$search_response->{results}}) {
push @$customer_conversion_goals,
{
category => $google_ads_row->{customerConversionGoal}{category},
origin => $google_ads_row->{customerConversionGoal}{origin}};
}
return $customer_conversion_goals;
}
# Creates a list of MutateOperations that override customer conversion goals.
sub create_conversion_goal_operations {
my ($customer_id, $customer_conversion_goals) = @_;
my $operations = [];
# To override the customer conversion goals, we will change the biddability of
# each of the customer conversion goals so that only the desired conversion goal
# is biddable in this campaign.
foreach my $customer_conversion_goal (@$customer_conversion_goals) {
my $campaign_conversion_goal =
Google::Ads::GoogleAds::V11::Resources::CampaignConversionGoal->new({
resourceName =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::campaign_conversion_goal(
$customer_id,
PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID,
$customer_conversion_goal->{category},
$customer_conversion_goal->{origin})});
# Change the biddability for the campaign conversion goal.
# Set biddability to true for the desired (category, origin).
# Set biddability to false for all other conversion goals.
# Note:
# 1- It is assumed that this Conversion Action
# (category=PURCHASE, origin=WEBSITE) exists in this account.
# 2- More than one goal can be biddable if desired. This example
# shows only one.
if ( $customer_conversion_goal->{category} eq PURCHASE
&& $customer_conversion_goal->{origin} eq WEBSITE)
{
$campaign_conversion_goal->{biddable} = "true";
} else {
$campaign_conversion_goal->{biddable} = "false";
}
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation
->new({
campaignConversionGoalOperation =>
Google::Ads::GoogleAds::V11::Services::CampaignConversionGoalService::CampaignConversionGoalOperation
->new({
update => $campaign_conversion_goal,
# Set the update mask on the operation. Here the update mask will be
# a list of all the fields that were set on the update object.
updateMask => all_set_fields_of($campaign_conversion_goal)})});
}
return $operations;
}
# Creates a list of MutateOperations that create a new asset group listing group filter.
sub create_asset_group_listing_group_operations {
my ($customer_id) = @_;
my $operations = [];
# Create a new listing group filter containing the "default" listing group (All
# products).
my $listing_group_filter =
Google::Ads::GoogleAds::V11::Resources::AssetGroupListingGroupFilter->new({
assetGroup =>
Google::Ads::GoogleAds::V11::Utils::ResourceNames::asset_group(
$customer_id, ASSET_GROUP_TEMPORARY_ID
),
# Since this is the root node, do not set the parentListingGroupFilter.
# For all other nodes, this would refer to the parent listing group filter
# resource name.
# parentListingGroupFilter => "<PARENT FILTER NAME>"
# The subdivision type means this node has children. This type is used for
# the root node as well.
type => UNIT_INCLUDED,
# Because this is a Performance Max campaign for retail, we need to specify
# that this is in the shopping vertical.
vertical => SHOPPING
});
push @$operations,
Google::Ads::GoogleAds::V11::Services::GoogleAdsService::MutateOperation->
new({
assetGroupListingGroupFilterOperation =>
Google::Ads::GoogleAds::V11::Services::AssetGroupListingGroupFilterService::AssetGroupListingGroupFilterOperation
->new({
create => $listing_group_filter
})});
return $operations;
}
# Prints the details of a MutateGoogleAdsResponse.
# Parses the "response" oneof field name and uses it to extract the new entity's
# name and resource name.
sub print_response_details {
my ($mutate_google_ads_response) = @_;
foreach
my $response (@{$mutate_google_ads_response->{mutateOperationResponses}})
{
my $result_type = [keys %$response]->[0];
printf "Created a(n) %s with '%s'.\n",
ucfirst $result_type =~ s/Result$//r,
$response->{$result_type}{resourceName};
}
}
# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
return 1;
}
# Get Google Ads Client, credentials will be read from ~/googleads.properties.
my $api_client = Google::Ads::GoogleAds::Client->new();
# By default examples are set to die on any server returned fault.
$api_client->set_die_on_faults(1);
# Parameters passed on the command line will override any parameters set in code.
GetOptions(
"customer_id=s" => \$customer_id,
"merchant_center_account_id=i" => \$merchant_center_account_id,
"sales_country=s" => \$sales_country,
"final_url=s" => \$final_url
);
# Print the help message if the parameters are not initialized in the code nor
# in the command line.
pod2usage(2)
if not check_params($customer_id, $merchant_center_account_id, $sales_country,
$final_url);
# Call the example.
add_performance_max_retail_campaign($api_client, $customer_id =~ s/-//gr,
$merchant_center_account_id, $sales_country, $final_url);
=pod
=head1 NAME
add_performance_max_retail_campaign
=head1 DESCRIPTION
This example shows how to create a Performance Max retail campaign.
This will be created for "All products".
For more information about Performance Max retail campaigns, see
https://developers.google.com/google-ads/api/docs/performance-max/retail.
Prerequisites:
- You need to have access to a Merchant Center account. You can find
instructions to create a Merchant Center account here:
https://support.google.com/merchants/answer/188924.
This account must be linked to your Google Ads account. The integration
instructions can be found at:
https://developers.google.com/google-ads/api/docs/shopping-ads/merchant-center.
- You need your Google Ads account to track conversions. The different ways
to track conversions can be found here:
https://support.google.com/google-ads/answer/1722054.
- You must have at least one conversion action in the account. For more about
conversion actions, see
https://developers.google.com/google-ads/api/docs/conversions/overview#conversion_actions.
=head1 SYNOPSIS
add_performance_max_retail_campaign.pl [options]
-help Show the help message.
-customer_id The Google Ads customer ID.
-merchant_center_account_id The Merchant Center account ID.
-sales_country [optional] The sales country of products to include in the campaign.
-final_url [optional] The final URL for the asset group of the campaign.
=cut
