4.2 建立廣告活動
簡介
完成上述步驟後，您就可以讓商家建立零售業專用最高成效廣告活動，並使用機器學習技術，為放送每則廣告做出最明智的決策。
如要瞭解廣告主必須在 Google Ads 使用者介面中手動執行哪些操作，才能建立最高成效廣告活動，請參閱「建立最高成效廣告活動」。本節將說明如何使用 Google Ads API，讓廣告客戶建立最高成效廣告活動，放送購物廣告。
本節僅涵蓋可為商家帶來最大價值，同時盡量簡化導入程序的基本廣告活動功能。建議您為每個廣告活動向商家提供下列三種自訂選項：
廣告活動名稱：廣告活動在報表中顯示的方式。
預算：廣告活動應平均支出的金額。
指定地理區域：廣告活動應放送廣告的位置。
此外，您還需要在後端指定其他幾個參數，如下所列。
出價策略
自動出價策略會定義廣告活動在設定出價時要盡量提高哪些指標。最高成效廣告活動提供兩種出價策略：
盡量爭取轉換：廣告活動會在指定預算範圍內，盡力爭取最多轉換次數 (例如購物次數)。
盡量提高轉換價值 (建議)：廣告活動會嘗試在指定預算範圍內，盡量提高轉換的總金錢價值 (例如購物支出的美元金額)，因為您在轉換追蹤設定中已將其定義為轉換價值。
為簡化技術複雜度和商家使用體驗，建議您代表商家選取「盡量提高轉換價值」出價策略，但不要指定廣告投資報酬率。這與透過重新導向選項可用的內容一致。
素材資源群組和商家資訊群組
素材資源群組是廣告活動廣告素材元素 (例如產品、圖片、影片) 的儲存位置。在基礎支柱中，只有 Merchant Center 中的產品適用。因此，每個廣告活動只需要一個素材資源群組，您可以代表商家在後端建立素材資源群組。
商家可以使用商家資訊群組，將廣告活動中的產品細分為不同群組 (例如，只宣傳特定產品)。這是進階功能，不建議在基礎支柱中使用，但每個廣告活動都必須至少包含一個商家資訊群組。因此，每個廣告活動只需要一個產品資訊群組，您可以代表商家在後端建立這個群組。
使用者體驗指南
本節的第一部分會討論在 Google Ads 新手上路流程中，建立第一個廣告活動的情況。第二部分說明如何建立其他廣告活動。如果您允許商家指定廣告活動的地理區域，這點就格外重要。
在 Google Ads 新手上路期間建立廣告活動
連結 Google Ads 帳戶後，系統會提示使用者設定最高成效廣告活動：
廣告活動名稱可預先填入有意義的名稱，例如「商店建構工具名稱」的最高成效廣告活動。
我們也建議您加入廣告預覽畫面，並簡要說明最高成效廣告活動的運作方式。Google Ads API 並未提供產生廣告預覽畫面的做法，因此您必須自行實作。由於廣告類型的設計可能會有所變更，因此不必讓圖片與原始圖片完全相同。
如果商家符合優待券資格，請在提示中提及這項資訊。
請務必在流程的這個階段提供購物廣告政策的連結。
您可以選擇允許商家指定廣告活動的地理區域。
商家在廣告活動設定步驟中，可能會遇到以下兩種情況：
未設定帳單。在這個流程中建立新的 Google Ads 帳戶時，一律會發生這種情況。
已為已連結的 Google Ads 帳戶設定帳單 (例如，商家重複使用已用於放送其他類型廣告活動的 Google Ads 帳戶)。
在 Google Ads 帳戶連結步驟中，系統應該已偵測到帳單問題。情境 1 和 2 唯一的差異在於主要動作的行為和行動號召 (CTA)：
在情境 1 中，行動號召應稱為「設定帳單」並開啟帳單彈出式視窗。提供結帳資訊並關閉彈出式視窗後，請繼續進行「查看並完成設定」步驟。
在第 2 種情況下，應呼叫「繼續」的 CTA，並直接進入「查看並完成設定」步驟。
以下是情境 1 的廣告活動設定步驟範例。
請向商家提供廣告活動名稱、納入的產品和預算等其他資訊。以下是可能的樣式範例。
如果商家輸入的預算低於廣告所在國家/地區的建議門檻，請提供通知，並建議最低預算。以下是建議的樣式。
完成廣告活動設定步驟並提供帳單資訊 (如有需要) 後，使用者會繼續進行「查看並完成」步驟。使用者在啟動廣告活動前，可以最後一次檢查廣告活動設定。在這個步驟中，UI 可能會如下所示：
結束新手上路流程後，建議您向使用者預覽後續動作。請參閱下方範例。
新手上路程序結束後，商家應會被導向總覽頁面。以下是可能的樣式範例。
多媒體廣告活動和建立其他廣告活動
您的使用者介面應可顯示多個廣告活動，因為商家可能已擁有最高成效廣告活動，或想建立多個廣告活動，尤其是當您允許他們指定地理區域時。以下範例說明如何允許商家為廣告活動指定地理區域。請務必確保地理指定範圍比商家宣傳的國家/地區更狹窄。
如果商家有多個廣告活動，請在總覽頁面上匯總廣告指標。以下是可能的樣式範例。
在 Google Ads 詳細資料檢視畫面中列出個別廣告活動。以下是這項功能的示例。
建議您從 Google Ads 詳細資料檢視畫面開始建立其他廣告活動。下方動畫顯示這個流程的示例。請注意，動畫會略過填入預算資訊的步驟，因為本指南前面已介紹這部分。
技術指南
將 Google Ads 帳戶連結至 Merchant Center 帳戶後，您可以按照下列步驟建立零售專用最高成效廣告活動：
- 建立預算作業
- 建立廣告活動作業
- 建立廣告活動條件
- 使用商家資訊群組篩選器建立素材資源群組
- 覆寫轉換目標
- 一併傳送所有作業
請注意，下列說明適用於管理最高成效廣告活動：
您必須使用至少 Google Ads API 9 版
您必須在單一變異要求中傳送所有變異作業。因此，您必須先建立所有變異操作，然後再將這些操作一併傳送至 Google Ads API 的單一變異要求。
您會在所建立的所有作業中使用暫時 ID，這是因為您會傳送包含所有作業的單一變異要求，而這些作業會使用這些暫時 ID 讓 Google 知道這些作業彼此相關。
設定名稱
如果您的商家有可能直接存取 Google Ads 平台，建議您更謹慎地選擇廣告活動名稱，以便清楚表明您是透過程式輔助方式建立廣告活動。這會向商家傳達，最好透過自家平台，而非 Google Ads 平台編輯廣告活動。舉例來說，即使您允許商家自訂名稱，仍建議您在名稱前面或後面加上「Created by platform X」。
步驟 1：建立預算作業
您可以在「建立廣告活動預算」一文中找到程式碼範例，因此我們這裡只會強調最重要的幾點：
最高成效廣告活動和其他廣告活動一樣需要預算，但有下列限制：
- 預算必須設有每日預算週期。
- 無法共用預算。
預算的放送方式為標準。標準放送會考量整天的廣告預期成效，也更能夠在平均每日預算的範圍內爭取最佳的成效。
如本節前述，您必須在建立的所有作業中使用暫時 ID。因此，您會在程式碼範例中看到
_BUDGET_TEMPORARY_ID已在預算的資源名稱中設定，以便在後續步驟中供廣告活動參照。
步驟 2：建立廣告活動和出價策略
您可以參考「建立廣告活動和出價策略」一文中的程式碼範例，瞭解如何建立標準最高成效廣告活動。以下提供其他注意事項：
程式碼範例會使用「盡量提高轉換價值」出價策略，這是我們建議您在基礎支柱中使用的出價策略。您可以使用「盡量提高轉換價值」選項，指定目標廣告投資報酬率。即使您選擇不指定目標廣告投資報酬率值，也必須設定這個值 (除非您使用的是 Java)。在 Java 中，您有：
setMaximizeConversionValue(MaximizeConversionValue.newBuilder().build())網址擴展功能可讓廣告活動指定整個網域，而非僅指定廣告客戶在 Merchant Center 中指定的網址。建議您使用最終到達網址擴展功能，讓廣告活動的觸及數和成效不受限制。請注意，這並不代表廣告會放送到商家網站上的任何網頁。
start_date和end_date為選用欄位。
對於零售專用最高成效廣告活動，您還必須建立包含下列欄位的 ShoppingSetting，並將其加入廣告活動。這會指定要使用的 Merchant Center 帳戶，以及要使用該帳戶中的哪個產品動態饋給。如建立零售業專用最高成效廣告活動所述，您需要設定下列 ShoppingSetting 欄位：
merchant_id(必要)：含有要宣傳產品的帳戶 Merchant Center ID。feed_label(可能需要)：如果商家使用的是舊版產品動態饋給的現有 Merchant Center 帳戶，您應使用 feed_label 指定要讓廣告活動使用您建立的產品動態饋給；這會對應至 Content API 中的DatafeedTarget。
以下是建立最高成效零售廣告活動和出價策略的操作範例。這項假設是基於 Merchant Center 帳戶中只有一個產品動態饋給 (也就是你管理的動態饋給)，因此不會設定 feed_label。
Python
mutate_operation = googleads_client.get_type("MutateOperation")
campaign = mutate_operation.campaign_operation.create
campaign.name = f"Performance Max campaign #{uuid4()}"
campaign.status = googleads_client.enums.CampaignStatusEnum.ENABLED
campaign.advertising_channel_type = ( googleads_client.enums.AdvertisingChannelTypeEnum.PERFORMANCE_MAX
)
# Add Merchant Center ID to create a Performance Max for Retail
# campaign. This ID should be linked to the Ads account
# where you are creating the campaign
campaign.shopping_setting.merchant_id = int(google_merchant_id)
campaign.maximize_conversion_value.target_roas = None
# Set the Final URL expansion opt out. This option 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.
campaign.url_expansion_opt_out = False
# Assign the resource name with a temporary ID.
campaign_service = googleads_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
)
print("mutate_operation for step 2 - campaign and bidding strategy creation")
print(mutate_operation)
return mutate_operation
步驟 3：建立廣告活動條件
您可以在「建立廣告活動條件」中查看程式碼範例，以下列出最重要的要點：
如程式碼範例所示，您必須先啟動所有必要的服務，才能繼續設定廣告活動條件「位置」和「語言」。
設定地區廣告活動條件時，您可以將
campaign_criterion.negative設為 True，為要排除的地區新增排除指定目標。請務必使用步驟 2 中的臨時 ID，告訴 Google 您要為哪個廣告活動建立這項條件。
步驟 4：使用商家資訊群組篩選器建立素材資源群組
如這篇文章所述，素材資源群組是以某主題為核心或與目標對象相關的一組素材資源。素材資源群組會用來組合所有廣告，並根據廣告目標建立所有適用的廣告格式。
您可以使用購物商家資訊群組將產品劃分為群組，以便納入或排除某組產品。可讓您篩選在廣告活動中顯示的產品組合。
您可以參考最高成效廣告活動商家資訊群組中的程式碼範例，建立多個產品商家資訊群組，但對於基礎支柱，建議您設定單一廣告活動，指定商家的所有產品。因此，我們在下方提供較簡單的程式碼範例。您必須加入根 AssetGroupListingGroupFilter 節點，其中包含所有產品。否則系統不會放送廣告。
Python
googleads_service = googleads_client.get_service("GoogleAdsService")
operations = []
# Create the AssetGroup
mutate_operation = googleads_client.get_type("MutateOperation")
asset_group = mutate_operation.asset_group_operation.create
asset_group.name = f"Performance Max asset group #{uuid4()}"
asset_group.campaign = googleads_service.campaign_path(
customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID
)
asset_group.status = googleads_client.enums.AssetGroupStatusEnum.ENABLED
asset_group.resource_name = googleads_service.asset_group_path(
customer_id,
_ASSET_GROUP_TEMPORARY_ID,
)
operations.append(mutate_operation)
# Create a listing group and link it to the AssetGroup.
# The way you link a listing group to an AssetGroup is different
# than when you are linking headlines, descriptions, images, etc
# where you set the field_type of the asset_group_asset as HEADLINE, for example.
# https://developers.google.com/google-ads/api/reference/rpc/v13/AssetGroupListingGroupFilter
mutate_operation = googleads_client.get_type("MutateOperation")
asset_group_listing_group = mutate_operation.asset_group_listing_group_filter_operation.create
asset_group_listing_group.asset_group = googleads_service.asset_group_path(
customer_id,
_ASSET_GROUP_TEMPORARY_ID,
)
asset_group_listing_group.type_ = googleads_client.enums.ListingGroupFilterTypeEnum.UNIT_INCLUDED
# here are other options for ListingGroupFilterTypeEnum
# https://developers.google.com/google-ads/api/reference/rpc/v13/ListingGroupFilterTypeEnum.ListingGroupFilterType
asset_group_listing_group.vertical = googleads_client.enums.ListingGroupFilterVerticalEnum.SHOPPING
operations.append(mutate_operation)
print("mutate_operation for step 4 - create asset group and product group attached to that asset group")
print(operations)
return operations
您可以為素材資源群組加入廣告標題、說明，甚至圖片，以提升廣告活動成效。不過，由於這並非零售業專用最高成效廣告活動的必要條件，因此不建議用於基礎支柱。
步驟 5：覆寫轉換目標
如同「轉換追蹤」一節所述，如果您允許商家使用現有的 Google Ads 帳戶，強烈建議您在廣告活動層級設定轉換目標。方法是在客戶或帳戶層級覆寫轉換目標。如果未設定廣告活動層級轉換目標，廣告活動會預設為使用客戶層級轉換目標。
您可以在「更新廣告活動轉換目標」中找到程式碼範例。首先，您必須取得帳戶的轉換目標。接著，您可以逐一檢查轉換目標，並確認每個目標是否用於促進線上銷售 (也就是「購買」類別，來源「網站」)。如果不是，請將可出價性設為 False。如果是，請將可出價性設為 True。這樣一來，最高成效廣告活動就能提升線上銷售業績。
步驟 6：一併傳送所有變更作業
最後，您必須一併傳送所有變異操作。如以下程式碼範例所示，運算順序非常重要，因為它們彼此相依。例如，performance_max_campaign_operation 使用 campaign_budget_operation 的資料，而 campaign_criterion_operations 使用 performance_max_campaign_operation 的資料。
Python
ga_service = googleads_client.get_service("GoogleAdsService")
response = ga_service.mutate(
customer_id=customer_id,
mutate_operations=[
# It's important to create the entities in this order
# because they depend on each other
campaign_budget_operation, # Step 1
performance_max_campaign_operation, # Step 2
# Expand the list of multiple operations into the list of
# other mutate operations
*campaign_criterion_operations, # Step 3
*asset_group_operations, # Step 4
*conversion_goal_operations, # Step 5
],
)
廣告活動建立成功後，API 會傳回類似以下的內容：
Python
mutate_operation_responses {
campaign_budget_result {
resource_name: "customers/7244690427/campaignBudgets/10689184019"
}
}
mutate_operation_responses {
campaign_result {
resource_name: "customers/7244690427/campaigns/16822128600"
}
}
mutate_operation_responses {
campaign_criterion_result {
resource_name: "customers/7244690427/campaignCriteria/16822128600~20009"
}
}
mutate_operation_responses {
campaign_criterion_result {
resource_name: "customers/7244690427/campaignCriteria/16822128600~20024"
}
}
mutate_operation_responses {
campaign_criterion_result {
resource_name: "customers/7244690427/campaignCriteria/16822128600~1003"
}
}
mutate_operation_responses {
asset_group_result {
resource_name: "customers/7244690427/assetGroups/6444254998"
}
}
mutate_operation_responses {
asset_group_listing_group_filter_result {
resource_name: "customers/7244690427/assetGroupListingGroupFilters/6444254998~6454725458"
}
}
mutate_operation_responses {
campaign_conversion_goal_result {
resource_name: "customers/7244690427/campaignConversionGoals/16822128600~PURCHASE~WEBSITE"
}
}
請儲存廣告活動和預算的 resource_name，因為您需要這些資訊來編輯廣告活動設定，並用於製作報表。
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 static com.google.ads.googleads.v21.enums.EuPoliticalAdvertisingStatusEnum.EuPoliticalAdvertisingStatus.DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING; 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.v21.common.ImageAsset; import com.google.ads.googleads.v21.common.LanguageInfo; import com.google.ads.googleads.v21.common.LocationInfo; import com.google.ads.googleads.v21.common.MaximizeConversionValue; import com.google.ads.googleads.v21.common.TextAsset; import com.google.ads.googleads.v21.enums.AdvertisingChannelTypeEnum.AdvertisingChannelType; import com.google.ads.googleads.v21.enums.AssetFieldTypeEnum.AssetFieldType; import com.google.ads.googleads.v21.enums.AssetGroupStatusEnum.AssetGroupStatus; import com.google.ads.googleads.v21.enums.BudgetDeliveryMethodEnum.BudgetDeliveryMethod; import com.google.ads.googleads.v21.enums.CampaignStatusEnum.CampaignStatus; import com.google.ads.googleads.v21.enums.ConversionActionCategoryEnum.ConversionActionCategory; import com.google.ads.googleads.v21.enums.ConversionOriginEnum.ConversionOrigin; import com.google.ads.googleads.v21.enums.ListingGroupFilterListingSourceEnum.ListingGroupFilterListingSource; import com.google.ads.googleads.v21.enums.ListingGroupFilterTypeEnum.ListingGroupFilterType; import com.google.ads.googleads.v21.errors.GoogleAdsError; import com.google.ads.googleads.v21.errors.GoogleAdsException; import com.google.ads.googleads.v21.resources.Asset; import com.google.ads.googleads.v21.resources.AssetGroup; import com.google.ads.googleads.v21.resources.AssetGroupAsset; import com.google.ads.googleads.v21.resources.AssetGroupListingGroupFilter; import com.google.ads.googleads.v21.resources.Campaign; import com.google.ads.googleads.v21.resources.Campaign.ShoppingSetting; import com.google.ads.googleads.v21.resources.CampaignAsset; import com.google.ads.googleads.v21.resources.CampaignBudget; import com.google.ads.googleads.v21.resources.CampaignConversionGoal; import com.google.ads.googleads.v21.resources.CampaignCriterion; import com.google.ads.googleads.v21.resources.CustomerConversionGoal; import com.google.ads.googleads.v21.services.AssetGroupAssetOperation; import com.google.ads.googleads.v21.services.AssetGroupListingGroupFilterOperation; import com.google.ads.googleads.v21.services.AssetGroupOperation; import com.google.ads.googleads.v21.services.AssetOperation; import com.google.ads.googleads.v21.services.CampaignAssetOperation; import com.google.ads.googleads.v21.services.CampaignBudgetOperation; import com.google.ads.googleads.v21.services.CampaignConversionGoalOperation; import com.google.ads.googleads.v21.services.CampaignCriterionOperation; import com.google.ads.googleads.v21.services.CampaignOperation; import com.google.ads.googleads.v21.services.GoogleAdsRow; import com.google.ads.googleads.v21.services.GoogleAdsServiceClient; import com.google.ads.googleads.v21.services.GoogleAdsServiceClient.SearchPagedResponse; import com.google.ads.googleads.v21.services.MutateGoogleAdsResponse; import com.google.ads.googleads.v21.services.MutateOperation; import com.google.ads.googleads.v21.services.MutateOperationResponse; import com.google.ads.googleads.v21.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; @Parameter( names = "--brandGuidelinesEnabled", arity = 1, description = "A boolean value indicating if the created campaign is enabled for brand guidelines") private boolean brandGuidelinesEnabled = false; } 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, params.brandGuidelinesEnabled); } 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. * @param brandGuidelinesEnabled indicates if the campaign is enabled for brand guidelines. */ private void runExample( GoogleAdsClient googleAdsClient, long customerId, long merchantCenterAccountId, String salesCountry, String finalUrl, boolean brandGuidelinesEnabled) 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, brandGuidelinesEnabled)); mutateOperations.addAll(createCampaignCriterionOperations(customerId)); String assetGroupResourceName = ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID); mutateOperations.add(createAssetGroupOperation(customerId, assetGroupResourceName, finalUrl)); // Retail Performance Max campaigns require listing groups, which are created via the // AssetGroupListingGroupFilter resource. mutateOperations.add(createAssetGroupListingGroupFilterOperation(assetGroupResourceName)); mutateOperations.addAll( createAssetAndAssetGroupAssetOperations( customerId, assetGroupResourceName, headlineAssetResourceNames, descriptionAssetResourceNames, brandGuidelinesEnabled)); mutateOperations.addAll(createConversionGoalOperations(customerId, customerConversionGoals)); 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, boolean brandGuidelinesEnabled) { 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. // For first time users, it's recommended not to set a target ROAS value. Although // the target ROAS value is optional, you still need to define the enclosing // maximize_conversion_value. .setMaximizeConversionValue( MaximizeConversionValue.newBuilder() // .setTargetRoas(3.5) .build()) // Below is what you would use if you want to maximize conversions: // .setMaximizeConversions( // MaximizeConversions.newBuilder() // // The target CPA is optional. This is the average amount that you would like // // to spend per conversion action. // // .setTargetCpaMicros(1_000_000) // .build()) // Sets the shopping settings. .setShoppingSetting( ShoppingSetting.newBuilder() .setMerchantId(merchantCenterAccountId) // Optional: To use products only from a specific feed, set FeedLabel to the // feed label used in Merchant Center. See: // https://support.google.com/merchants/answer/12453549. // Removing the feedLabel field will use products from all feeds. // .setFeedLabel("INSERT_FEED_LABEL_HERE") .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) // Sets if the campaign is enabled for brand guidelines. For more information on brand // guidelines, see https://support.google.com/google-ads/answer/14934472. .setBrandGuidelinesEnabled(brandGuidelinesEnabled) // 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)) // Declares whether this campaign serves political ads targeting the EU. .setContainsEuPoliticalAdvertising(DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING) // 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 campaignCriteria.add( CampaignCriterion.newBuilder() .setCampaign(campaignResourceName) // Adds one positive location target for New York City (ID=1023191), specifically adding // the positive criteria before the negative one. .setLocation( LocationInfo.newBuilder() .setGeoTargetConstant(ResourceNames.geoTargetConstant(1023191)) .build()) .setNegative(false) .build()); // Next adds the negative target for Brooklyn (ID=1022762). 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. * * <p>These repeated assets must be created in a separate request prior to creating the campaign. */ 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 MutateOperation that create a new AssetGroup. */ private MutateOperation createAssetGroupOperation( long customerId, String assetGroupResourceName, String finalUrl) { 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(); return MutateOperation.newBuilder().setAssetGroupOperation(assetGroupOperation).build(); } /** Creates a list of MutateOperations that create a new AssetGroup. */ private List<MutateOperation> createAssetAndAssetGroupAssetOperations( long customerId, String assetGroupResourceName, List<String> headlineAssetResourceNames, List<String> descriptionAssetResourceNames, boolean brandGuidelinesEnabled) throws IOException { List<MutateOperation> mutateOperations = new ArrayList<>(); // 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) { mutateOperations.add( createAssetGroupAssetMutateOperation( AssetFieldType.HEADLINE, resourceName, assetGroupResourceName)); } // Links the description assets. for (String resourceName : descriptionAssetResourceNames) { mutateOperations.add( createAssetGroupAssetMutateOperation( AssetFieldType.DESCRIPTION, resourceName, assetGroupResourceName)); } // 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 and logo assets. mutateOperations.addAll( createAndLinkBrandAssets( customerId, brandGuidelinesEnabled, "Interplanetary Cruises", "https://gaagl.page.link/1Crm", "Logo Image")); // Creates and links the image assets. // 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 sortMutateOperations(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. mutateOperations.add( createAssetGroupAssetMutateOperation( assetFieldType, assetResourceName, assetGroupResourceName)); 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. mutateOperations.add( createAssetGroupAssetMutateOperation( assetFieldType, assetResourceName, assetGroupResourceName)); return mutateOperations; } /** Creates a list of MutateOperations that create linked brand assets. */ List<MutateOperation> createAndLinkBrandAssets( long customerId, boolean brandGuidelinesEnabled, String businessName, String logoUrl, String logoName) throws IOException { List<MutateOperation> mutateOperations = new ArrayList<>(); // Creates the brand name text asset. String businessNameAssetResourceName = ResourceNames.asset(customerId, getNextTemporaryId()); Asset businessNameAsset = Asset.newBuilder() .setResourceName(businessNameAssetResourceName) .setTextAsset(TextAsset.newBuilder().setText(businessName).build()) .build(); AssetOperation businessNameAssetOperation = AssetOperation.newBuilder().setCreate(businessNameAsset).build(); mutateOperations.add( MutateOperation.newBuilder().setAssetOperation(businessNameAssetOperation).build()); // Creates the logo image asset. String logoAssetResourceName = ResourceNames.asset(customerId, getNextTemporaryId()); // Creates a media file. byte[] logoBytes = ByteStreams.toByteArray(new URL(logoUrl).openStream()); Asset logoAsset = Asset.newBuilder() .setResourceName(logoAssetResourceName) .setImageAsset(ImageAsset.newBuilder().setData(ByteString.copyFrom(logoBytes)).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(logoName) .build(); AssetOperation logoImageAssetOperation = AssetOperation.newBuilder().setCreate(logoAsset).build(); mutateOperations.add( MutateOperation.newBuilder().setAssetOperation(logoImageAssetOperation).build()); if (brandGuidelinesEnabled) { // Creates CampaignAsset resources to link the Asset resources to the Campaign. mutateOperations.add( createCampaignAssetMutateOperation( customerId, AssetFieldType.BUSINESS_NAME, businessNameAssetResourceName)); mutateOperations.add( createCampaignAssetMutateOperation( customerId, AssetFieldType.LOGO, logoAssetResourceName)); } else { // Creates an AssetGroupAsset to link the Asset to the AssetGroup. mutateOperations.add( createAssetGroupAssetMutateOperation( AssetFieldType.BUSINESS_NAME, businessNameAssetResourceName, ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID))); mutateOperations.add( createAssetGroupAssetMutateOperation( AssetFieldType.LOGO, logoAssetResourceName, ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID))); } return mutateOperations; } /** Creates a MutateOperation to add an AssetGroupAsset. */ MutateOperation createAssetGroupAssetMutateOperation( AssetFieldType fieldType, String assetResourceName, String assetGroupResourceName) { AssetGroupAsset assetGroupAsset = AssetGroupAsset.newBuilder() .setFieldType(fieldType) .setAssetGroup(assetGroupResourceName) .setAsset(assetResourceName) .build(); AssetGroupAssetOperation assetGroupAssetOperation = AssetGroupAssetOperation.newBuilder().setCreate(assetGroupAsset).build(); return MutateOperation.newBuilder() .setAssetGroupAssetOperation(assetGroupAssetOperation) .build(); } /** Creates a MutateOperation to add a CampaignAsset. */ MutateOperation createCampaignAssetMutateOperation( long customerId, AssetFieldType fieldType, String assetResourceName) { CampaignAsset campaignAsset = CampaignAsset.newBuilder() .setFieldType(fieldType) .setCampaign(ResourceNames.campaign(customerId, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID)) .setAsset(assetResourceName) .build(); CampaignAssetOperation campaignAssetOperation = CampaignAssetOperation.newBuilder().setCreate(campaignAsset).build(); return MutateOperation.newBuilder().setCampaignAssetOperation(campaignAssetOperation).build(); } /** * Sorts a list of mutate operations. * * <p>This sorts the list such that all asset operations precede all asset group asset and * campaign asset operations. If asset group assets are created before assets then an error will * be returned by the API. */ private List<MutateOperation> sortMutateOperations(List<MutateOperation> operations) { List<MutateOperation> sortedOperations = new ArrayList<>(); sortedOperations.addAll( operations.stream().filter(o -> o.hasAssetOperation()).collect(Collectors.toList())); sortedOperations.addAll( operations.stream() .filter(o -> o.hasAssetGroupAssetOperation()) .collect(Collectors.toList())); sortedOperations.addAll( operations.stream() .filter(o -> o.hasCampaignAssetOperation()) .collect(Collectors.toList())); return sortedOperations; } /** 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 uses the SHOPPING listing source, as required for a Performance // Max retail campaign. .setListingSource(ListingGroupFilterListingSource.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.Config; using Google.Ads.GoogleAds.Lib; using Google.Ads.GoogleAds.V21.Common; using Google.Ads.GoogleAds.V21.Errors; using Google.Ads.GoogleAds.V21.Resources; using Google.Ads.GoogleAds.V21.Services; using Google.Api.Gax; using Google.Protobuf; using System; using System.Collections.Generic; using System.Threading; using static Google.Ads.GoogleAds.V21.Enums.AdvertisingChannelTypeEnum.Types; using static Google.Ads.GoogleAds.V21.Enums.AssetFieldTypeEnum.Types; using static Google.Ads.GoogleAds.V21.Enums.AssetGroupStatusEnum.Types; using static Google.Ads.GoogleAds.V21.Enums.BudgetDeliveryMethodEnum.Types; using static Google.Ads.GoogleAds.V21.Enums.CampaignStatusEnum.Types; using static Google.Ads.GoogleAds.V21.Enums.ConversionActionCategoryEnum.Types; using static Google.Ads.GoogleAds.V21.Enums.ConversionOriginEnum.Types; using static Google.Ads.GoogleAds.V21.Enums.EuPoliticalAdvertisingStatusEnum.Types; using static Google.Ads.GoogleAds.V21.Enums.ListingGroupFilterListingSourceEnum.Types; using static Google.Ads.GoogleAds.V21.Enums.ListingGroupFilterTypeEnum.Types; using static Google.Ads.GoogleAds.V21.Resources.Campaign.Types; namespace Google.Ads.GoogleAds.Examples.V21 { /// <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 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> /// Optional: A boolean value indicating if the campaign is enabled for brand /// guidelines. /// </summary> [Option("brandGuidelinesEnabled", Required = false, HelpText = "A boolean value indicating if the campaign is enabled for brand guidelines.")] public bool BrandGuidelinesEnabled { 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.FinalUrl, options.BrandGuidelinesEnabled ); } // 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 AssetTemporaryResourceNameGenerator { private long customerId; private long next; public AssetTemporaryResourceNameGenerator(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="finalUrl">The final URL.</param> /// <param name="brandGuidelinesEnabled">Whether or not to enable brand guidelines.</param> public void Run( GoogleAdsClient client, long customerId, long merchantCenterAccountId, string finalUrl, bool brandGuidelinesEnabled) { try { GoogleAdsServiceClient googleAdsServiceClient = client.GetService(Services.V21.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, brandGuidelinesEnabled ); List<MutateOperation> campaignCriterionOperations = CreateCampaignCriterionOperations(tempResourceNameCampaign); List<MutateOperation> assetGroupOperations = CreateAssetGroupOperations( tempResourceNameCampaign, assetGroupResourceName, finalUrl, headlineAssetResourceNames, descriptionAssetResourceNames, new AssetTemporaryResourceNameGenerator( customerId, TEMPORARY_ID_ASSET_GROUP ), client.Config, brandGuidelinesEnabled ); 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="brandGuidelinesEnabled">Whether or not to enable brand guidelines.</param> /// <returns>A MutateOperations that will create this new campaign.</returns> private MutateOperation CreatePerformanceMaxCampaignOperation( string campaignResourceName, string campaignBudgetResourceName, long merchantCenterAccountId, bool brandGuidelinesEnabled) { 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, // Optional: To use products only from a specific feed, set FeedLabel // to the feed label used in Merchant Center. // See: https://support.google.com/merchants/answer/12453549. // Omitting the FeedLabel field will use products from all feeds. // FeedLabel = "INSERT_FEED_LABEL_HERE" }, // 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, // Set if the campaign is enabled for brand guidelines. For more information // on brand guidelines, see https://support.google.com/google-ads/answer/14934472. BrandGuidelinesEnabled = brandGuidelinesEnabled, // Declare whether or not this campaign contains political ads targeting the EU. ContainsEuPoliticalAdvertising = EuPoliticalAdvertisingStatus.DoesNotContainEuPoliticalAdvertising, // 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. /// These repeated assets must be created in a separate request prior to /// creating the campaign. /// </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.V21.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> /// <param name="brandGuidelinesEnabled">Whether or not to enable brand guidelines.</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, AssetTemporaryResourceNameGenerator resourceNameGenerator, GoogleAdsConfig config, bool brandGuidelinesEnabled) { List<MutateOperation> operations = new List<MutateOperation>(); // For the list of required assets for a Performance Max campaign, see // https://developers.google.com/google-ads/api/docs/performance-max/assets // Create and link the long headline text asset. string longHeadlineResourceName = resourceNameGenerator.Next(); operations.Add( CreateTextAssetOperation( longHeadlineResourceName, "Travel the World" ) ); // Create the business name text asset. string businessNameResourceName = resourceNameGenerator.Next(); operations.Add( CreateTextAssetOperation( businessNameResourceName, "Interplanetary Cruises" ) ); // Create the Logo Asset. string logoResourceName = resourceNameGenerator.Next(); operations.Add( CreateImageAssetOperation( logoResourceName, "https://gaagl.page.link/1Crm", "Logo Image", config ) ); // Create the Marketing Image Asset. string marketingImageResourceName = resourceNameGenerator.Next(); operations.Add( CreateImageAssetOperation( marketingImageResourceName, "https://gaagl.page.link/Eit5", "Marketing Image", config ) ); // Create the Square Marketing Image Asset. string squareMarketingImageResourceName = resourceNameGenerator.Next(); operations.Add( CreateImageAssetOperation( squareMarketingImageResourceName, "https://gaagl.page.link/bjYi", "Square Marketing Image", config ) ); // 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 // // Also, note that all asset creation operations must be before the // asset group creation operation and the asset group linking operations. // 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 } } } ); // Link the previously created 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 } } } ); } operations.Add( CreateLinkAssetOperation( AssetFieldType.LongHeadline, assetGroupResourceName, longHeadlineResourceName ) ); operations.Add( CreateLinkAssetOperation( AssetFieldType.BusinessName, assetGroupResourceName, businessNameResourceName, brandGuidelinesEnabled ) ); operations.Add( CreateLinkAssetOperation( AssetFieldType.Logo, assetGroupResourceName, logoResourceName, brandGuidelinesEnabled ) ); operations.Add( CreateLinkAssetOperation( AssetFieldType.MarketingImage, assetGroupResourceName, marketingImageResourceName ) ); operations.Add( CreateLinkAssetOperation( AssetFieldType.SquareMarketingImage, assetGroupResourceName, squareMarketingImageResourceName ) ); return operations; } /// <summary> /// Creates a MutateOperation that creates a new text asset. /// </summary> /// <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> /// <returns>A MutateOperation that creates the new text asset.</returns> private MutateOperation CreateTextAssetOperation( string assetResourceName, string text) => new MutateOperation() { AssetOperation = new AssetOperation() { Create = new Asset() { ResourceName = assetResourceName, TextAsset = new TextAsset() { Text = text } } } }; /// <summary> /// Creates a MutateOperation that creates a new image asset. /// </summary> /// <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="assetName">The asset name.</param> /// <param name="config">The Google Ads config.</param> /// <returns>A MutateOperation that creates a new image asset.</returns> private MutateOperation CreateImageAssetOperation( string assetResourceName, string url, string assetName, GoogleAdsConfig config) => 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 } } }; /// <summary> /// Creates a MutateOperation that links an asset to an asset group. /// </summary> /// <param name="fieldType">The field type of the asset to be linked.</param> /// <param name="linkedEntityResourceName">The resource name of the entity (asset group or /// campaign) to link the asset to.</param> /// <param name="assetResourceName">The resource name of the text asset to be /// linked.</param> /// <param name="brandGuidelinesEnabled">Whether or not to enable brand guidelines.</param> /// <returns>A MutateOperation that links an asset to an asset group.</returns> private MutateOperation CreateLinkAssetOperation( AssetFieldType fieldType, string linkedEntityResourceName, string assetResourceName, bool brandGuidelinesEnabled = false) { if (brandGuidelinesEnabled) { return new MutateOperation() { CampaignAssetOperation = new CampaignAssetOperation() { Create = new CampaignAsset() { FieldType = fieldType, Campaign = linkedEntityResourceName, Asset = assetResourceName } } }; } else { return new MutateOperation() { AssetGroupAssetOperation = new AssetGroupAssetOperation() { Create = new AssetGroupAsset() { FieldType = fieldType, AssetGroup = linkedEntityResourceName, Asset = assetResourceName } } }; } } /// <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.V21.GoogleAdsService); List<CustomerConversionGoal> conversionGoals = new List<CustomerConversionGoal>(); SearchGoogleAdsRequest request = new SearchGoogleAdsRequest() { CustomerId = customerId.ToString(), 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 listing source. ListingSource = ListingGroupFilterListingSource.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\V21\GoogleAdsClient; use Google\Ads\GoogleAds\Lib\V21\GoogleAdsClientBuilder; use Google\Ads\GoogleAds\Lib\V21\GoogleAdsException; use Google\Ads\GoogleAds\Util\FieldMasks; use Google\Ads\GoogleAds\Util\V21\ResourceNames; use Google\Ads\GoogleAds\V21\Common\ImageAsset; use Google\Ads\GoogleAds\V21\Common\LanguageInfo; use Google\Ads\GoogleAds\V21\Common\LocationInfo; use Google\Ads\GoogleAds\V21\Common\MaximizeConversionValue; use Google\Ads\GoogleAds\V21\Common\TextAsset; use Google\Ads\GoogleAds\V21\Enums\AdvertisingChannelTypeEnum\AdvertisingChannelType; use Google\Ads\GoogleAds\V21\Enums\AssetFieldTypeEnum\AssetFieldType; use Google\Ads\GoogleAds\V21\Enums\AssetGroupStatusEnum\AssetGroupStatus; use Google\Ads\GoogleAds\V21\Enums\BudgetDeliveryMethodEnum\BudgetDeliveryMethod; use Google\Ads\GoogleAds\V21\Enums\CampaignStatusEnum\CampaignStatus; use Google\Ads\GoogleAds\V21\Enums\ConversionActionCategoryEnum\ConversionActionCategory; use Google\Ads\GoogleAds\V21\Enums\ConversionOriginEnum\ConversionOrigin; use Google\Ads\GoogleAds\V21\Enums\EuPoliticalAdvertisingStatusEnum\EuPoliticalAdvertisingStatus; use Google\Ads\GoogleAds\V21\Enums\ListingGroupFilterListingSourceEnum\ListingGroupFilterListingSource; use Google\Ads\GoogleAds\V21\Enums\ListingGroupFilterTypeEnum\ListingGroupFilterType; use Google\Ads\GoogleAds\V21\Errors\GoogleAdsError; use Google\Ads\GoogleAds\V21\Resources\Asset; use Google\Ads\GoogleAds\V21\Resources\AssetGroup; use Google\Ads\GoogleAds\V21\Resources\AssetGroupAsset; use Google\Ads\GoogleAds\V21\Resources\AssetGroupListingGroupFilter; use Google\Ads\GoogleAds\V21\Resources\Campaign; use Google\Ads\GoogleAds\V21\Resources\Campaign\ShoppingSetting; use Google\Ads\GoogleAds\V21\Resources\CampaignAsset; use Google\Ads\GoogleAds\V21\Resources\CampaignBudget; use Google\Ads\GoogleAds\V21\Resources\CampaignConversionGoal; use Google\Ads\GoogleAds\V21\Resources\CampaignCriterion; use Google\Ads\GoogleAds\V21\Services\AssetGroupAssetOperation; use Google\Ads\GoogleAds\V21\Services\AssetGroupListingGroupFilterOperation; use Google\Ads\GoogleAds\V21\Services\AssetGroupOperation; use Google\Ads\GoogleAds\V21\Services\AssetOperation; use Google\Ads\GoogleAds\V21\Services\CampaignAssetOperation; use Google\Ads\GoogleAds\V21\Services\CampaignBudgetOperation; use Google\Ads\GoogleAds\V21\Services\CampaignConversionGoalOperation; use Google\Ads\GoogleAds\V21\Services\CampaignCriterionOperation; use Google\Ads\GoogleAds\V21\Services\CampaignOperation; use Google\Ads\GoogleAds\V21\Services\GoogleAdsRow; use Google\Ads\GoogleAds\V21\Services\MutateGoogleAdsRequest; use Google\Ads\GoogleAds\V21\Services\MutateGoogleAdsResponse; use Google\Ads\GoogleAds\V21\Services\MutateOperation; use Google\Ads\GoogleAds\V21\Services\MutateOperationResponse; use Google\Ads\GoogleAds\V21\Services\SearchGoogleAdsRequest; 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'; // 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'; // Optional: Indicates whether the created campaign is enabled for brand guidelines. private const BRAND_GUIDELINES_ENABLED = false; // 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; 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::BRAND_GUIDELINES_ENABLED => 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::FINAL_URL] ?: self::FINAL_URL, filter_var( $options[ArgumentNames::BRAND_GUIDELINES_ENABLED] ?: self::BRAND_GUIDELINES_ENABLED, FILTER_VALIDATE_BOOLEAN ) ); } 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 $finalUrl the final URL for the asset group of the campaign * @param bool $brandGuidelinesEnabled whether the created campaign will be enabled for brand * guidelines */ public static function runExample( GoogleAdsClient $googleAdsClient, int $customerId, int $merchantCenterAccountId, string $finalUrl, bool $brandGuidelinesEnabled ) { // 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, $brandGuidelinesEnabled ); $operations = array_merge($operations, self::createCampaignCriterionOperations($customerId)); $operations[] = self::createAssetGroupOperation($customerId, $finalUrl); $operations[] = self::createAssetGroupListingGroupFilterOperation($customerId); $operations = array_merge($operations, self::createAssetandAssetGroupAssetOperations( $customerId, $headlineAssetResourceNames, $descriptionAssetResourceNames, $brandGuidelinesEnabled )); $operations = array_merge($operations, self::createConversionGoalOperations( $customerId, $customerConversionGoals )); // Issues a mutate request to create everything and prints its information. $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); $response = $googleAdsServiceClient->mutate( MutateGoogleAdsRequest::build($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 bool $brandGuidelinesEnabled whether the created campaign will be enabled for brand * guidelines * @return MutateOperation the mutate operation that creates the campaign */ private static function createPerformanceMaxCampaignOperation( int $customerId, int $merchantCenterAccountId, bool $brandGuidelinesEnabled ): 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 ]), // Below is what you would use if you want to maximize conversions // You can optionally set the 'target_cpa_micros' field on MaximizeConversions. // This is the average amount that you would like to spend per conversion // action. // 'maximize_conversions' => new MaximizeConversions(), // 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 if the campaign is enabled for brand guidelines. For more information // on brand guidelines, see // https://support.google.com/google-ads/answer/14934472. 'brand_guidelines_enabled' => $brandGuidelinesEnabled, // Sets the shopping settings. 'shopping_setting' => new ShoppingSetting([ 'merchant_id' => $merchantCenterAccountId, // Optional: To use products only from a specific feed, set feed_label to // the feed label used in Merchant Center. // See: https://support.google.com/merchants/answer/12453549. // Removing the feed_label field will use products from all feeds. // 'feed_label' => 'INSERT_FEED_LABEL_HERE' ]), // Declare whether or not this campaign serves political ads targeting the EU. 'contains_eu_political_advertising' => EuPoliticalAdvertisingStatus::DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING // 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 $operations[] = new MutateOperation([ 'campaign_criterion_operation' => new CampaignCriterionOperation([ 'create' => new CampaignCriterion([ 'campaign' => ResourceNames::forCampaign( $customerId, self::PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ), 'location' => new LocationInfo([ // Adds one positive location target for New York City (ID=1023191), // specifically adding the positive criteria before the negative one. '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([ // Next add the negative target for Brooklyn (ID=1022762). '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. * * These repeated assets must be created in a separate request prior to creating the campaign. * * @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. $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); /** @var MutateGoogleAdsResponse $mutateGoogleAdsResponse */ $mutateGoogleAdsResponse = $googleAdsServiceClient->mutate( MutateGoogleAdsRequest::build($customerId, $operations) ); $assetResourceNames = []; foreach ($mutateGoogleAdsResponse->getMutateOperationResponses() as $response) { /** @var MutateOperationResponse $response */ $assetResourceNames[] = $response->getAssetResult()->getResourceName(); } self::printResponseDetails($mutateGoogleAdsResponse); return $assetResourceNames; } /** * Creates a MutateOperation that creates 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 int $customerId the customer ID * @return MutateOperation a mutate operation creates a new asset group. */ private static function createAssetGroupOperation( int $customerId, string $finalUrl ): MutateOperation { // Creates a new mutate operation that creates an asset group operation. return 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 ]) ]) ]); } /** * Creates a MutateOperation that creates a new asset group listing group filter. * * A temporary ID will be assigned to this listing group filter so that it can be referenced by * other objects being created in the same Mutate request. * * @param int $customerId the customer ID * @return MutateOperation a MutateOperation that creates a new asset group listing group filter */ private static function createAssetGroupListingGroupFilterOperation( int $customerId ): MutateOperation { return 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' => ResourceNames::forAssetGroup( $customerId, self::ASSET_GROUP_TEMPORARY_ID ), // 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 listing source. 'listing_source' => ListingGroupFilterListingSource::SHOPPING ]) ]) ]); } /** * Creates a list of MutateOperations that create new asset group asset and assets. * * 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 int $customerId the customer ID * @param string[] $headlineAssetResourceNames a list of headline resource names * @param string[] $descriptionAssetResourceNames a list of description resource names * @param bool $brandGuidelinesEnabled whether the created campaign will be enabled for brand * guidelines * @return MutateOperation[] a list of MutateOperations that create new asset group assets and * assets */ private static function createAssetandAssetGroupAssetOperations( int $customerId, array $headlineAssetResourceNames, array $descriptionAssetResourceNames, bool $brandGuidelinesEnabled ): array { $operations = []; // 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::createAndLinkBrandAssets( $customerId, $brandGuidelinesEnabled, 'Interplanetary Cruises', 'https://gaagl.page.link/1Crm', 'Logo Image' )); // Creates and links the image assets. // 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' )); // After being created the list must be sorted so that all asset operations come before all // the asset group asset operations, otherwise the API will reject the request. return self::sortAssetAndAssetGroupAssetOperations($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; } /** * Creates a list of MutateOperations that create linked brand assets. * * @param int $customerId the customer ID * @param bool $brandGuidelinesEnabled whether the created campaign will be enabled for brand * guidelines * @param string $businessName the business name text to be put into an asset * @param string $logoUrl the URL of the logo to be retrieved and put into an asset * @param string $logoName the asset name of the logo * @return MutateOperation[] a list of MutateOperations that create a new linked text asset */ private static function createAndLinkBrandAssets( int $customerId, bool $brandGuidelinesEnabled, string $businessName, string $logoUrl, string $logoName ): array { $operations = []; // Creates a new mutate operation that creates a text asset. $businessNameTempId = self::$nextTempId--; $operations[] = new MutateOperation([ 'asset_operation' => new AssetOperation([ 'create' => new Asset([ 'resource_name' => ResourceNames::forAsset($customerId, $businessNameTempId), 'text_asset' => new TextAsset(['text' => $businessName]) ]) ]) ]); $logoTempId = self::$nextTempId--; // 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, $logoTempId), // 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' => $logoName, 'image_asset' => new ImageAsset(['data' => file_get_contents($logoUrl)]) ]) ]) ]); if ($brandGuidelinesEnabled) { // Creates a campaign asset to link the business name and logo assets to the campaign. $operations[] = new MutateOperation([ 'campaign_asset_operation' => new CampaignAssetOperation([ 'create' => new CampaignAsset([ 'asset' => ResourceNames::forAsset($customerId, $businessNameTempId), 'campaign' => ResourceNames::forCampaign( $customerId, self::PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ), 'field_type' => AssetFieldType::BUSINESS_NAME ]) ]) ]); $operations[] = new MutateOperation([ 'campaign_asset_operation' => new CampaignAssetOperation([ 'create' => new CampaignAsset([ 'asset' => ResourceNames::forAsset($customerId, $logoTempId), 'campaign' => ResourceNames::forCampaign( $customerId, self::PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ), 'field_type' => AssetFieldType::LOGO ]) ]) ]); } else { // Creates an asset group asset to link the business name and logo assets to the asset // group. $operations[] = new MutateOperation([ 'asset_group_asset_operation' => new AssetGroupAssetOperation([ 'create' => new AssetGroupAsset([ 'asset' => ResourceNames::forAsset($customerId, $businessNameTempId), 'asset_group' => ResourceNames::forAssetGroup( $customerId, self::ASSET_GROUP_TEMPORARY_ID ), 'field_type' => AssetFieldType::BUSINESS_NAME ]) ]) ]); $operations[] = new MutateOperation([ 'asset_group_asset_operation' => new AssetGroupAssetOperation([ 'create' => new AssetGroupAsset([ 'asset' => ResourceNames::forAsset($customerId, $logoTempId), 'asset_group' => ResourceNames::forAssetGroup( $customerId, self::ASSET_GROUP_TEMPORARY_ID ), 'field_type' => AssetFieldType::LOGO ]) ]) ]); } return $operations; } /** * Sorts a list of asset and asset group asset operations. This sorts the list such that all * asset operations precede all asset group asset operations. If asset group assets are created * before assets then an error will be returned by the API. * * @param MutateOperation[] $operations a list of asset and asset group asset mutate operations * @return MutateOperation[] a sorted list of asset and asset group asset mutate operations */ private static function sortAssetAndAssetGroupAssetOperations(array $operations): array { usort( $operations, function (MutateOperation $operation1, MutateOperation $operation2) { if (!is_null($operation1->getAssetOperation())) { return -1; } elseif (!is_null($operation1->getAssetOperation())) { return 0; } else { return 1; } } ); 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(SearchGoogleAdsRequest::build($customerId, $query)); // 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; } /** * 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 typing import Dict, List, Union from uuid import uuid4 from google.api_core import protobuf_helpers from examples.utils.example_helpers import get_image_bytes_from_url 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 from google.ads.googleads.v21.enums.types.conversion_action_category import ( ConversionActionCategoryEnum, ) from google.ads.googleads.v21.enums.types.conversion_origin import ( ConversionOriginEnum, ) from google.ads.googleads.v21.enums.types.asset_field_type import ( AssetFieldTypeEnum, ) from google.ads.googleads.v21.resources.types.asset import Asset from google.ads.googleads.v21.resources.types.asset_group import AssetGroup from google.ads.googleads.v21.resources.types.asset_group_asset import ( AssetGroupAsset, ) from google.ads.googleads.v21.resources.types.asset_group_listing_group_filter import ( AssetGroupListingGroupFilter, ) from google.ads.googleads.v21.resources.types.campaign import Campaign from google.ads.googleads.v21.resources.types.campaign_asset import ( CampaignAsset, ) from google.ads.googleads.v21.resources.types.campaign_budget import ( CampaignBudget, ) from google.ads.googleads.v21.resources.types.campaign_conversion_goal import ( CampaignConversionGoal, ) from google.ads.googleads.v21.resources.types.campaign_criterion import ( CampaignCriterion, ) from google.ads.googleads.v21.services.services.asset_group_service import ( AssetGroupServiceClient, ) from google.ads.googleads.v21.services.services.asset_service import ( AssetServiceClient, ) from google.ads.googleads.v21.services.services.campaign_budget_service import ( CampaignBudgetServiceClient, ) from google.ads.googleads.v21.services.services.campaign_conversion_goal_service import ( CampaignConversionGoalServiceClient, ) from google.ads.googleads.v21.services.services.campaign_service import ( CampaignServiceClient, ) from google.ads.googleads.v21.services.services.geo_target_constant_service import ( GeoTargetConstantServiceClient, ) from google.ads.googleads.v21.services.services.google_ads_service import ( GoogleAdsServiceClient, ) from google.ads.googleads.v21.services.types.google_ads_service import ( MutateGoogleAdsResponse, MutateOperationResponse, SearchGoogleAdsRequest, SearchGoogleAdsResponse, ) from google.ads.googleads.v21.services.types.google_ads_service import ( MutateOperation, ) # 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: str = "-1" _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID: str = "-2" _ASSET_GROUP_TEMPORARY_ID: str = "-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 = int(_ASSET_GROUP_TEMPORARY_ID) - 1 def main( client: GoogleAdsClient, customer_id: str, merchant_center_account_id: int, final_url: str, brand_guidelines_enabled: bool, ) -> None: """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. final_url: the final URL. brand_guidelines_enabled: a boolean value indicating if the campaign is enabled for brand guidelines. """ googleads_service: GoogleAdsServiceClient = client.get_service( "GoogleAdsService" ) # This campaign will override the customer conversion goals. # Retrieve the current list of customer conversion goals. customer_conversion_goals: List[ Dict[ str, Union[ ConversionActionCategoryEnum.ConversionActionCategory, ConversionOriginEnum.ConversionOrigin, ], ] ] = 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: List[str] = create_multiple_text_assets( client, customer_id, [ "Travel", "Travel Reviews", "Book travel", ], ) # Create the descriptions. description_asset_resource_names: List[str] = 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: MutateOperation = ( create_campaign_budget_operation( client, customer_id, ) ) performance_max_campaign_operation: MutateOperation = ( create_performance_max_campaign_operation( client, customer_id, merchant_center_account_id, brand_guidelines_enabled, ) ) campaign_criterion_operations: List[MutateOperation] = ( create_campaign_criterion_operations( client, customer_id, ) ) asset_group_operation: MutateOperation = create_asset_group_operation( client, customer_id, final_url ) listing_group_filter_operation: MutateOperation = ( create_listing_group_filter_operation(client, customer_id) ) asset_and_asset_group_asset_operations: List[MutateOperation] = ( create_asset_and_asset_group_asset_operations( client, customer_id, headline_asset_resource_names, description_asset_resource_names, brand_guidelines_enabled, ) ) conversion_goal_operations: List[MutateOperation] = ( create_conversion_goal_operations( client, customer_id, customer_conversion_goals, ) ) # Send the operations in a single Mutate request. response: MutateGoogleAdsResponse = 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_operation, listing_group_filter_operation, *asset_and_asset_group_asset_operations, *conversion_goal_operations, ], ) print_response_details(response) def create_campaign_budget_operation( client: GoogleAdsClient, customer_id: str, ) -> MutateOperation: """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: MutateOperation = client.get_type("MutateOperation") campaign_budget_operation = mutate_operation.campaign_budget_operation campaign_budget: CampaignBudget = 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_service: CampaignBudgetServiceClient = client.get_service( "CampaignBudgetService" ) campaign_budget.resource_name = ( campaign_budget_service.campaign_budget_path( customer_id, _BUDGET_TEMPORARY_ID ) ) return mutate_operation def create_performance_max_campaign_operation( client: GoogleAdsClient, customer_id: str, merchant_center_account_id: int, brand_guidelines_enabled: bool, ) -> MutateOperation: """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. brand_guidelines_enabled: a boolean value indicating if the campaign is enabled for brand guidelines. Returns: a MutateOperation that creates a campaign. """ mutate_operation: MutateOperation = client.get_type("MutateOperation") campaign: 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_micros = 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 # Optional: To use products only from a specific feed, set # shopping_setting.feed_label to the feed label used in Merchant Center. # See: https://support.google.com/merchants/answer/12453549. # Omitting the shopping_setting.feed_label field will use products from all # feeds. # campaign.shopping_setting.feed_label = "INSERT_FEED_LABEL_HERE" # 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 # Set if the campaign is enabled for brand guidelines. For more information # on brand guidelines, see https://support.google.com/google-ads/answer/14934472. campaign.brand_guidelines_enabled = brand_guidelines_enabled # Assign the resource name with a temporary ID. campaign_service: CampaignServiceClient = 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_budget_service: CampaignBudgetServiceClient = client.get_service( "CampaignBudgetService" ) campaign.campaign_budget = campaign_budget_service.campaign_budget_path( customer_id, _BUDGET_TEMPORARY_ID ) # Declare whether or not this campaign serves political ads targeting the # EU. Valid values are: # CONTAINS_EU_POLITICAL_ADVERTISING # DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING campaign.contains_eu_political_advertising = ( client.enums.EuPoliticalAdvertisingStatusEnum.DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING ) # 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: GoogleAdsClient, customer_id: str, ) -> List[MutateOperation]: """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: CampaignServiceClient = client.get_service( "CampaignService" ) geo_target_constant_service: GeoTargetConstantServiceClient = ( client.get_service("GeoTargetConstantService") ) googleads_service: GoogleAdsServiceClient = client.get_service( "GoogleAdsService" ) operations: 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 mutate_operation_nyc: MutateOperation = client.get_type("MutateOperation") campaign_criterion_nyc: CampaignCriterion = ( mutate_operation_nyc.campaign_criterion_operation.create ) campaign_criterion_nyc.campaign = campaign_service.campaign_path( customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ) # Adds one positive location target for New York City (ID=1023191), # specifically adding the positive criteria before the negative one. campaign_criterion_nyc.location.geo_target_constant = ( geo_target_constant_service.geo_target_constant_path("1023191") ) campaign_criterion_nyc.negative = False operations.append(mutate_operation_nyc) # Next add the negative target for Brooklyn (ID=1022762). mutate_operation_brooklyn: MutateOperation = client.get_type( "MutateOperation" ) campaign_criterion_brooklyn: CampaignCriterion = ( mutate_operation_brooklyn.campaign_criterion_operation.create ) campaign_criterion_brooklyn.campaign = campaign_service.campaign_path( customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ) campaign_criterion_brooklyn.location.geo_target_constant = ( geo_target_constant_service.geo_target_constant_path("1022762") ) campaign_criterion_brooklyn.negative = True operations.append(mutate_operation_brooklyn) # Set the LANGUAGE campaign criterion. mutate_operation_lang: MutateOperation = client.get_type("MutateOperation") campaign_criterion_lang: CampaignCriterion = ( mutate_operation_lang.campaign_criterion_operation.create ) campaign_criterion_lang.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_lang.language.language_constant = ( googleads_service.language_constant_path("1000") ) # English operations.append(mutate_operation_lang) return operations def create_multiple_text_assets( client: GoogleAdsClient, customer_id: str, texts: List[str] ) -> List[str]: """Creates multiple text assets and returns the list of resource names. These repeated assets must be created in a separate request prior to creating the campaign. 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: GoogleAdsServiceClient = client.get_service( "GoogleAdsService" ) operations: List[MutateOperation] = [] for text_content in texts: mutate_operation: MutateOperation = client.get_type("MutateOperation") asset: Asset = mutate_operation.asset_operation.create asset.text_asset.text = text_content operations.append(mutate_operation) # Send the operations in a single Mutate request. response: MutateGoogleAdsResponse = googleads_service.mutate( customer_id=customer_id, mutate_operations=operations, ) asset_resource_names: List[str] = [] 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: GoogleAdsClient, customer_id: str, final_url: str ) -> MutateOperation: """Creates a MutateOperation that creates 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. Returns: a MutateOperation that creates a new asset group. """ campaign_service: CampaignServiceClient = client.get_service( "CampaignService" ) asset_group_service: AssetGroupServiceClient = client.get_service( "AssetGroupService" ) # Create the AssetGroup. mutate_operation: MutateOperation = client.get_type("MutateOperation") asset_group: AssetGroup = 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, ) return mutate_operation def create_listing_group_filter_operation( client: GoogleAdsClient, customer_id: str ) -> MutateOperation: """Creates a MutateOperation that creates a new listing group filter. A temporary ID will be assigned to this listing group filter 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 new listing group filter. """ asset_group_service: AssetGroupServiceClient = client.get_service( "AssetGroupService" ) # Creates a new ad group criterion containing the "default" listing # group (All products). mutate_operation: MutateOperation = client.get_type("MutateOperation") asset_group_listing_group: AssetGroupListingGroupFilter = ( 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 listing source. asset_group_listing_group.listing_source = ( client.enums.ListingGroupFilterListingSourceEnum.SHOPPING ) return mutate_operation def create_asset_and_asset_group_asset_operations( client: GoogleAdsClient, customer_id: str, headline_asset_resource_names: List[str], description_asset_resource_names: List[str], brand_guidelines_enabled: bool, ) -> List[MutateOperation]: """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. headline_asset_resource_names: a list of headline resource names. description_asset_resource_names: a list of description resource names. brand_guidelines_enabled: a boolean value indicating if the campaign is enabled for brand guidelines. Returns: MutateOperations that create a new asset group and related assets. """ asset_group_service: AssetGroupServiceClient = client.get_service( "AssetGroupService" ) operations: List[MutateOperation] = [] # 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: MutateOperation = client.get_type("MutateOperation") asset_group_asset: AssetGroupAsset = ( 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: MutateOperation = client.get_type("MutateOperation") asset_group_asset: AssetGroupAsset = ( 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_long_headline: List[MutateOperation] = ( create_and_link_text_asset( client, customer_id, "Travel the World", client.enums.AssetFieldTypeEnum.LONG_HEADLINE, ) ) operations.extend(mutate_operations_long_headline) # Create and link the business name and logo asset. mutate_operations_brand: List[MutateOperation] = ( create_and_link_brand_assets( client, customer_id, brand_guidelines_enabled, "Interplanetary Cruises", "https://gaagl.page.link/1Crm", "Logo Image", ) ) operations.extend(mutate_operations_brand) # Create and link the image assets. # Create and link the Marketing Image Asset. mutate_operations_marketing_image: List[MutateOperation] = ( create_and_link_image_asset( client, customer_id, "https://gaagl.page.link/Eit5", client.enums.AssetFieldTypeEnum.MARKETING_IMAGE, "Marketing Image", ) ) operations.extend(mutate_operations_marketing_image) # Create and link the Square Marketing Image Asset. mutate_operations_square_image: List[MutateOperation] = ( 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_square_image) # After being created the list must be sorted so that all asset # operations come before all the asset group asset operations, # otherwise the API will reject the request. return sort_asset_and_asset_group_asset_operations(operations) def create_and_link_text_asset( client: GoogleAdsClient, customer_id: str, text: str, field_type: AssetFieldTypeEnum.AssetFieldType, ) -> List[MutateOperation]: """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: List[MutateOperation] = [] asset_service: AssetServiceClient = client.get_service("AssetService") asset_group_service: AssetGroupServiceClient = client.get_service( "AssetGroupService" ) # Create the Text Asset. asset_temp_resource_name = asset_service.asset_path( customer_id, str(_next_temp_id) ) mutate_operation_asset: MutateOperation = client.get_type("MutateOperation") asset: Asset = mutate_operation_asset.asset_operation.create asset.resource_name = asset_temp_resource_name asset.text_asset.text = text operations.append(mutate_operation_asset) # Create an AssetGroupAsset to link the Asset to the AssetGroup. mutate_operation_group_asset: MutateOperation = client.get_type( "MutateOperation" ) asset_group_asset: AssetGroupAsset = ( mutate_operation_group_asset.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_temp_resource_name operations.append(mutate_operation_group_asset) _next_temp_id -= 1 return operations def create_and_link_image_asset( client: GoogleAdsClient, customer_id: str, url: str, field_type: AssetFieldTypeEnum.AssetFieldType, asset_name: str, ) -> List[MutateOperation]: """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: List[MutateOperation] = [] asset_service: AssetServiceClient = client.get_service("AssetService") asset_group_service: AssetGroupServiceClient = client.get_service( "AssetGroupService" ) # Create the Image Asset. asset_temp_resource_name = asset_service.asset_path( customer_id, str(_next_temp_id) ) mutate_operation_asset: MutateOperation = client.get_type("MutateOperation") asset: Asset = mutate_operation_asset.asset_operation.create asset.resource_name = asset_temp_resource_name 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_from_url(url) operations.append(mutate_operation_asset) # Create an AssetGroupAsset to link the Asset to the AssetGroup. mutate_operation_group_asset: MutateOperation = client.get_type( "MutateOperation" ) asset_group_asset: AssetGroupAsset = ( mutate_operation_group_asset.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_temp_resource_name operations.append(mutate_operation_group_asset) _next_temp_id -= 1 return operations def sort_asset_and_asset_group_asset_operations( operations: List[MutateOperation], ) -> List[MutateOperation]: """Sorts a list of asset and asset group asset operations. This sorts the list such that all asset operations precede all asset group asset operations. If asset group assets are created before assets then an error will be returned by the API. Args: operations: a list of asset and asset group asset operations. Returns: a sorted list of asset and asset group asset operations. """ def sorter(operation: MutateOperation) -> bool: """Determines whether the operation creates an asset group asset. Args: operation: a MutateOperation instance. Returns: True if the MutateOperation creates an asset group asset. """ # Check if the oneof field 'asset_group_asset_operation' is set. return ( operation.asset_group_asset_operation != type(operation.asset_group_asset_operation)() ) return sorted(operations, key=sorter) def get_customer_conversion_goals( client: GoogleAdsClient, customer_id: str ) -> List[ Dict[ str, Union[ ConversionActionCategoryEnum.ConversionActionCategory, ConversionOriginEnum.ConversionOrigin, ], ] ]: """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: GoogleAdsServiceClient = client.get_service("GoogleAdsService") customer_conversion_goals: List[ Dict[ str, Union[ ConversionActionCategoryEnum.ConversionActionCategory, ConversionOriginEnum.ConversionOrigin, ], ] ] = [] query: str = """ 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: SearchGoogleAdsRequest = client.get_type( "SearchGoogleAdsRequest" ) search_request.customer_id = customer_id search_request.query = query results: SearchGoogleAdsResponse = 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: GoogleAdsClient, customer_id: str, customer_conversion_goals: List[ Dict[ str, Union[ ConversionActionCategoryEnum.ConversionActionCategory, ConversionOriginEnum.ConversionOrigin, ], ] ], ) -> List[MutateOperation]: """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: CampaignConversionGoalServiceClient = ( client.get_service("CampaignConversionGoalService") ) operations: List[MutateOperation] = [] # 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_goal_dict in customer_conversion_goals: mutate_operation: MutateOperation = client.get_type("MutateOperation") campaign_conversion_goal: CampaignConversionGoal = ( mutate_operation.campaign_conversion_goal_operation.update ) category_enum_value: ( ConversionActionCategoryEnum.ConversionActionCategory ) = customer_goal_dict["category"] origin_enum_value: ConversionOriginEnum.ConversionOrigin = ( customer_goal_dict["origin"] ) campaign_conversion_goal.resource_name = ( campaign_conversion_goal_service.campaign_conversion_goal_path( customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID, category_enum_value.name, origin_enum_value.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 ( category_enum_value == client.enums.ConversionActionCategoryEnum.PURCHASE and origin_enum_value == 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 create_and_link_brand_assets( client: GoogleAdsClient, customer_id: str, brand_guidelines_enabled: bool, business_name: str, logo_url: str, logo_name: str, ) -> List[MutateOperation]: """Creates a list of MutateOperations that create linked brand assets. Args: client: an initialized GoogleAdsClient instance. customer_id: a client customer ID. brand_guidelines_enabled: a boolean value indicating if the campaign is enabled for brand guidelines. business_name: the business name text to be put into an asset. logo_url: the url of the logo to be retrieved and put into an asset. logo_name: the asset name of the logo. Returns: MutateOperations that create linked brand assets. """ global _next_temp_id operations: List[MutateOperation] = [] asset_service: AssetServiceClient = client.get_service("AssetService") # Create the Text Asset. text_asset_temp_id: int = _next_temp_id _next_temp_id -= 1 text_asset_resource_name = asset_service.asset_path( customer_id, str(text_asset_temp_id) ) text_mutate_operation: MutateOperation = client.get_type("MutateOperation") text_asset_obj: Asset = text_mutate_operation.asset_operation.create text_asset_obj.resource_name = text_asset_resource_name text_asset_obj.text_asset.text = business_name operations.append(text_mutate_operation) # Create the Image Asset. image_asset_temp_id: int = _next_temp_id _next_temp_id -= 1 image_asset_resource_name = asset_service.asset_path( customer_id, str(image_asset_temp_id) ) image_mutate_operation: MutateOperation = client.get_type("MutateOperation") image_asset_obj: Asset = image_mutate_operation.asset_operation.create image_asset_obj.resource_name = image_asset_resource_name # 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. image_asset_obj.name = logo_name image_asset_obj.type_ = client.enums.AssetTypeEnum.IMAGE image_asset_obj.image_asset.data = get_image_bytes_from_url(logo_url) operations.append(image_mutate_operation) if brand_guidelines_enabled: # Create CampaignAsset resources to link the Asset resources to the Campaign. campaign_service: CampaignServiceClient = client.get_service( "CampaignService" ) business_name_ca_mutate_op: MutateOperation = client.get_type( "MutateOperation" ) business_name_campaign_asset: CampaignAsset = ( business_name_ca_mutate_op.campaign_asset_operation.create ) business_name_campaign_asset.field_type = ( client.enums.AssetFieldTypeEnum.BUSINESS_NAME ) business_name_campaign_asset.campaign = campaign_service.campaign_path( customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ) business_name_campaign_asset.asset = text_asset_resource_name operations.append(business_name_ca_mutate_op) logo_ca_mutate_op: MutateOperation = client.get_type("MutateOperation") logo_campaign_asset: CampaignAsset = ( logo_ca_mutate_op.campaign_asset_operation.create ) logo_campaign_asset.field_type = client.enums.AssetFieldTypeEnum.LOGO logo_campaign_asset.campaign = campaign_service.campaign_path( customer_id, _PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ) logo_campaign_asset.asset = image_asset_resource_name operations.append(logo_ca_mutate_op) else: # Create AssetGroupAsset resources to link the Asset resources to the AssetGroup. asset_group_service: AssetGroupServiceClient = client.get_service( "AssetGroupService" ) business_name_aga_mutate_op: MutateOperation = client.get_type( "MutateOperation" ) business_name_asset_group_asset: AssetGroupAsset = ( business_name_aga_mutate_op.asset_group_asset_operation.create ) business_name_asset_group_asset.field_type = ( client.enums.AssetFieldTypeEnum.BUSINESS_NAME ) business_name_asset_group_asset.asset_group = ( asset_group_service.asset_group_path( customer_id, _ASSET_GROUP_TEMPORARY_ID, ) ) business_name_asset_group_asset.asset = text_asset_resource_name operations.append(business_name_aga_mutate_op) logo_aga_mutate_op: MutateOperation = client.get_type("MutateOperation") logo_asset_group_asset: AssetGroupAsset = ( logo_aga_mutate_op.asset_group_asset_operation.create ) logo_asset_group_asset.field_type = client.enums.AssetFieldTypeEnum.LOGO logo_asset_group_asset.asset_group = ( asset_group_service.asset_group_path( customer_id, _ASSET_GROUP_TEMPORARY_ID, ) ) logo_asset_group_asset.asset = image_asset_resource_name operations.append(logo_aga_mutate_op) return operations def print_response_details(response: MutateGoogleAdsResponse) -> None: """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: str = "_result" for result_item in response.mutate_operation_responses: # Ensure result_item is MutateOperationResponse, not just Any result_pb: MutateOperationResponse = result_item for field_descriptor, value in result_pb._pb.ListFields(): field_name_str: str = field_descriptor.name if field_name_str.endswith(suffix): name = field_name_str[: -len(suffix)] else: name = field_name_str print( f"Created a(n) {convert_snake_case_to_upper_case(name)} with " f"{str(value).strip()}." ) if __name__ == "__main__": 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( "-u", "--final_url", type=str, required=False, default="http://www.example.com", help="The final URL for the asset group of the campaign.", ) parser.add_argument( "-b", "--brand_guidelines_enabled", type=bool, default=False, help=( "A boolean value indicating if the created campaign is enabled " "for brand guidelines." ), ) args: argparse.Namespace = parser.parse_args() # GoogleAdsClient will read the google-ads.yaml configuration file in the # home directory if none is specified. googleads_client: GoogleAdsClient = GoogleAdsClient.load_from_storage( version="v21" ) try: main( googleads_client, args.customer_id, args.merchant_center_account_id, args.final_url, args.brand_guidelines_enabled, ) 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'\tError 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)
小茹
#!/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, final_url, brand_guidelines_enabled) # 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, brand_guidelines_enabled, ) campaign_criterion_operations = create_campaign_criterion_operations( client, customer_id, ) asset_group_operation = create_asset_group_operation( client, customer_id, final_url, ) listing_group_filter_operation = create_listing_group_filter_operation( client, customer_id, ) asset_and_asset_group_asset_operations = create_asset_and_asset_group_asset_operations( client, customer_id, headline_asset_resource_names, description_asset_resource_names, brand_guidelines_enabled, ) conversion_goal_operations = create_conversion_goal_operations( client, customer_id, customer_conversion_goals, ) # 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_operation, listing_group_filter_operation, asset_and_asset_group_asset_operations, conversion_goal_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, brand_guidelines_enabled) 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 # Optional: To use products only from a specific feed, set feed_label # to the feed label used in Merchant Center. # See: https://support.google.com/merchants/answer/12453549. # Omitting the feed_label field will use products from all feeds. # feed_label = "INSERT_FEED_LABEL_HERE" 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 # Set if the campaign is enabled for brand guidelines. For more # information on brand guidelines, see # https://support.google.com/google-ads/answer/14934472. c.brand_guidelines_enabled = brand_guidelines_enabled # 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) # Declare whether or not this campaign serves political ads targeting the EU # Valid values are CONTAINS_EU_POLITICAL_ADVERTISING and # DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING c.contains_eu_political_advertising = :DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING # 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 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) # Adds one positive location target for New York City (ID=1023191), # specifically adding the positive criteria before the negative one. 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 (ID=1022762). 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. # These repeated assets must be created in a separate request prior to creating # the campaign. 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 MutateOperation that creates 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) # Create the AssetGroup 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 end # Creates a MutateOperation that creates a new listing group filter. # A temporary ID will be assigned to this listing group filter so that it can # be referenced by other objects being created in the same Mutate request. def create_listing_group_filter_operation(client, customer_id) client.operation.mutate do |m| m.asset_group_listing_group_filter_operation = client.operation.create_resource.asset_group_listing_group_filter do |aglg| aglg.asset_group = client.path.asset_group( customer_id, ASSET_GROUP_TEMPORARY_ID, ) aglg.type = :UNIT_INCLUDED # Because this is a Performance Max campaign for retail, we need to # specify that this is in the shopping listing source. aglg.listing_source = :SHOPPING end end 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_and_asset_group_asset_operations( client, customer_id, headline_asset_resource_names, description_asset_resource_names, brand_guidelines_enabled) operations = [] # 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 and logo asset. operations += create_and_link_brand_assets( client, customer_id, brand_guidelines_enabled, "Interplanetary Cruises", "https://gaagl.page.link/1Crm", "Logo Image") # Create and link the image assets. # 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") # After being created the list must be sorted so that all asset # operations come before all the asset group asset operations, # otherwise the API will reject the request. sort_asset_and_asset_group_asset_operations(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 # Sorts a list of asset and asset group asset operations. This sorts the list # such that all asset operations precede all asset group asset operations. If # asset group assets are created before assets then an error will be returned # by the API. def sort_asset_and_asset_group_asset_operations(operations) operations.sort_by do |operation| if operation.asset_group_asset_operation 1 else 0 end end 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, ) # 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 # Creates a list of MutateOperations that create linked brand assets. def create_and_link_brand_assets( client, customer_id, brand_guidelines_enabled, business_name, logo_url, logo_name) operations = [] # Create the Text Asset. text_asset_temp_id = next_temp_id operations << client.operation.mutate do |m| m.asset_operation = client.operation.create_resource.asset do |a| a.resource_name = client.path.asset(customer_id, text_asset_temp_id) a.text_asset = client.resource.text_asset do |text_asset| text_asset.text = business_name end end end # Create the Image Asset. image_asset_temp_id = next_temp_id operations << client.operation.mutate do |m| m.asset_operation = client.operation.create_resource.asset do |a| a.resource_name = client.path.asset(customer_id, image_asset_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. a.name = logo_name a.type = :IMAGE a.image_asset = client.resource.image_asset do |image_asset| image_asset.data = get_image_bytes(logo_url) end end end if brand_guidelines_enabled # Create CampaignAsset resources to link the Asset resources to the Campaign. operations << client.operation.mutate do |m| m.campaign_asset_operation = client.operation.create_resource. campaign_asset do |ca| ca.field_type = :BUSINESS_NAME ca.campaign = client.path.campaign( customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID, ) ca.asset = client.path.asset(customer_id, text_asset_temp_id) end end operations << client.operation.mutate do |m| m.campaign_asset_operation = client.operation.create_resource. campaign_asset do |ca| ca.field_type = :LOGO ca.campaign = client.path.campaign( customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID, ) ca.asset = client.path.asset(customer_id, image_asset_temp_id) end end else # Create AssetGroupAsset resources to link the Asset resources 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 = :BUSINESS_NAME aga.asset_group = client.path.asset_group( customer_id, ASSET_GROUP_TEMPORARY_ID, ) aga.asset = client.path.asset(customer_id, text_asset_temp_id) end end operations << client.operation.mutate do |m| m.asset_group_asset_operation = client.operation.create_resource. asset_group_asset do |aga| aga.field_type = :LOGO aga.asset_group = client.path.asset_group( customer_id, ASSET_GROUP_TEMPORARY_ID, ) aga.asset = client.path.asset(customer_id, image_asset_temp_id) end end 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 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[:final_url] = 'INSERT_FINAL_URL_HERE' options[:brand_guidelines_enabled] = false 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('-f', '--final-url FINAL-URL', String, 'Final URL') do |v| options[:final_url] = v end opts.on('-B', '--brand-guidelines-enabled', 'Enable brand guidelines (optional)') do options[:brand_guidelines_enabled] = true 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(:final_url), options[:brand_guidelines_enabled]) 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::V21::Resources::CampaignBudget; use Google::Ads::GoogleAds::V21::Resources::Campaign; use Google::Ads::GoogleAds::V21::Resources::ShoppingSetting; use Google::Ads::GoogleAds::V21::Resources::CampaignCriterion; use Google::Ads::GoogleAds::V21::Resources::CampaignAsset; use Google::Ads::GoogleAds::V21::Resources::Asset; use Google::Ads::GoogleAds::V21::Resources::AssetGroup; use Google::Ads::GoogleAds::V21::Resources::AssetGroupAsset; use Google::Ads::GoogleAds::V21::Resources::CampaignConversionGoal; use Google::Ads::GoogleAds::V21::Resources::AssetGroupListingGroupFilter; use Google::Ads::GoogleAds::V21::Common::MaximizeConversionValue; use Google::Ads::GoogleAds::V21::Common::LocationInfo; use Google::Ads::GoogleAds::V21::Common::LanguageInfo; use Google::Ads::GoogleAds::V21::Common::TextAsset; use Google::Ads::GoogleAds::V21::Common::ImageAsset; use Google::Ads::GoogleAds::V21::Enums::BudgetDeliveryMethodEnum qw(STANDARD); use Google::Ads::GoogleAds::V21::Enums::CampaignStatusEnum; use Google::Ads::GoogleAds::V21::Enums::AdvertisingChannelTypeEnum qw(PERFORMANCE_MAX); use Google::Ads::GoogleAds::V21::Enums::AssetGroupStatusEnum; use Google::Ads::GoogleAds::V21::Enums::AssetFieldTypeEnum qw(HEADLINE DESCRIPTION LONG_HEADLINE BUSINESS_NAME LOGO MARKETING_IMAGE SQUARE_MARKETING_IMAGE); use Google::Ads::GoogleAds::V21::Enums::ConversionActionCategoryEnum qw(PURCHASE); use Google::Ads::GoogleAds::V21::Enums::ConversionOriginEnum qw(WEBSITE); use Google::Ads::GoogleAds::V21::Enums::ListingGroupFilterTypeEnum qw(UNIT_INCLUDED); use Google::Ads::GoogleAds::V21::Enums::ListingGroupFilterListingSourceEnum qw(SHOPPING); use Google::Ads::GoogleAds::V21::Enums::EuPoliticalAdvertisingStatusEnum qw(DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING); use Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation; use Google::Ads::GoogleAds::V21::Services::CampaignBudgetService::CampaignBudgetOperation; use Google::Ads::GoogleAds::V21::Services::CampaignService::CampaignOperation; use Google::Ads::GoogleAds::V21::Services::CampaignCriterionService::CampaignCriterionOperation; use Google::Ads::GoogleAds::V21::Services::AssetService::AssetOperation; use Google::Ads::GoogleAds::V21::Services::AssetGroupService::AssetGroupOperation; use Google::Ads::GoogleAds::V21::Services::AssetGroupAssetService::AssetGroupAssetOperation; use Google::Ads::GoogleAds::V21::Services::CampaignConversionGoalService::CampaignConversionGoalOperation; use Google::Ads::GoogleAds::V21::Services::AssetGroupListingGroupFilterService::AssetGroupListingGroupFilterOperation; use Google::Ads::GoogleAds::V21::Services::CampaignAssetService::CampaignAssetOperation; use Google::Ads::GoogleAds::V21::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; sub add_performance_max_retail_campaign { my ($api_client, $customer_id, $merchant_center_account_id, $final_url, $brand_guidelines_enabled) = @_; # 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, $brand_guidelines_enabled); push @$operations, @{create_campaign_criterion_operations($customer_id)}; push @$operations, create_asset_group_operation($customer_id, $final_url); push @$operations, create_listing_group_filter_operation($customer_id); push @$operations, @{ create_asset_and_asset_group_asset_operations( $customer_id, $headline_asset_resource_names, $description_asset_resource_names, $brand_guidelines_enabled )}; push @$operations, @{create_conversion_goal_operations($customer_id, $customer_conversion_goals)}; # 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::V21::Services::GoogleAdsService::MutateOperation-> new({ campaignBudgetOperation => Google::Ads::GoogleAds::V21::Services::CampaignBudgetService::CampaignBudgetOperation ->new({ create => Google::Ads::GoogleAds::V21::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::V21::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, $brand_guidelines_enabled) = @_; # Create a mutate operation that creates a campaign operation. return Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation-> new({ campaignOperation => Google::Ads::GoogleAds::V21::Services::CampaignService::CampaignOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::Campaign->new({ # Assign the resource name with a temporary ID. resourceName => Google::Ads::GoogleAds::V21::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::V21::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::V21::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. # For first time users, it's recommended not to set a target ROAS. # maximizeConversionValue => # Google::Ads::GoogleAds::V21::Common::MaximizeConversionValue-> # new({ # targetRoas => 3.5 # } # ), # Below is what you would use if you want to maximize conversions. # maximizeConversions => # Google::Ads::GoogleAds::V21::Common::MaximizeConversions-> # new({ # targetCpaMicros => 1000000 # } # ), # The target CPA is optional. This is the average amount that you would # like to spend per conversion action. # Set the shopping settings. shoppingSetting => Google::Ads::GoogleAds::V21::Resources::ShoppingSetting->new({ merchantId => $merchant_center_account_id, # Optional: To use products only from a specific feed, set feedLabel # to the feed label used in Merchant Center. # See: https://support.google.com/merchants/answer/12453549. # Omitting the feedLabel field will use products from all feeds. # feedLabel => "INSERT_FEED_LABEL_HERE" } ), # 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", # Declare whether or not this campaign serves political ads targeting the EU. # Valid values are CONTAINS_EU_POLITICAL_ADVERTISING and # DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING. containsEuPoliticalAdvertising => DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING, # Set if the campaign is enabled for brand guidelines. For more information # on brand guidelines, see https://support.google.com/google-ads/answer/14934472. brandGuidelinesEnabled => $brand_guidelines_enabled, # 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. push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation-> new({ campaignCriterionOperation => Google::Ads::GoogleAds::V21::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::CampaignCriterion->new({ campaign => Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign( $customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ), # Adds one positive location target for New York City (ID=1023191), # specifically adding the positive criteria before the negative one. location => Google::Ads::GoogleAds::V21::Common::LocationInfo->new({ geoTargetConstant => Google::Ads::GoogleAds::V21::Utils::ResourceNames::geo_target_constant( 1023191)} ), negative => "false" })})}); # Next add the negative target for Brooklyn (ID=1022762). push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation-> new({ campaignCriterionOperation => Google::Ads::GoogleAds::V21::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::CampaignCriterion->new({ campaign => Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign( $customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ), location => Google::Ads::GoogleAds::V21::Common::LocationInfo->new({ geoTargetConstant => Google::Ads::GoogleAds::V21::Utils::ResourceNames::geo_target_constant( 1022762)} ), negative => "true" })})}); # Set the LANGUAGE campaign criterion. push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation-> new({ campaignCriterionOperation => Google::Ads::GoogleAds::V21::Services::CampaignCriterionService::CampaignCriterionOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::CampaignCriterion->new({ campaign => Google::Ads::GoogleAds::V21::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::V21::Common::LanguageInfo->new({ languageConstant => Google::Ads::GoogleAds::V21::Utils::ResourceNames::language_constant( 1000) # English })})})}); return $operations; } # Creates multiple text assets and returns the list of resource names. # # These repeated assets must be created in a separate request prior to # creating the campaign. 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::V21::Services::GoogleAdsService::MutateOperation ->new({ assetOperation => Google::Ads::GoogleAds::V21::Services::AssetService::AssetOperation-> new({ create => Google::Ads::GoogleAds::V21::Resources::Asset->new({ textAsset => Google::Ads::GoogleAds::V21::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 MutateOperation that creates 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_operation { my ($customer_id, $final_url) = @_; # Create a mutate operation that creates an asset group operation. return Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation-> new({ assetGroupOperation => Google::Ads::GoogleAds::V21::Services::AssetGroupService::AssetGroupOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::AssetGroup->new({ resourceName => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset_group( $customer_id, ASSET_GROUP_TEMPORARY_ID ), name => "Performance Max retail asset group #" . uniqid(), campaign => Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign( $customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ), finalUrls => [$final_url], finalMobileUrls => [$final_url], status => Google::Ads::GoogleAds::V21::Enums::AssetGroupStatusEnum::PAUSED })})}); } # Creates a MutateOperation that creates a new listing group filter. # A temporary ID will be assigned to this listing group filter so that it # can be referenced by other objects being created in the same Mutate request. sub create_listing_group_filter_operation { my ($customer_id) = @_; # Creates a new ad group criterion containing the "default" listing group # (All products). my $listing_group_filter = Google::Ads::GoogleAds::V21::Resources::AssetGroupListingGroupFilter->new({ assetGroup => Google::Ads::GoogleAds::V21::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 listing source. listingSource => SHOPPING }); return Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation-> new({ assetGroupListingGroupFilterOperation => Google::Ads::GoogleAds::V21::Services::AssetGroupListingGroupFilterService::AssetGroupListingGroupFilterOperation ->new({ create => $listing_group_filter })}); } # 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_and_asset_group_asset_operations { my ( $customer_id, $headline_asset_resource_names, $description_asset_resource_names, $brand_guidelines_enabled ) = @_; my $operations = []; # 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::V21::Services::GoogleAdsService::MutateOperation ->new({ assetGroupAssetOperation => Google::Ads::GoogleAds::V21::Services::AssetGroupAssetService::AssetGroupAssetOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::AssetGroupAsset->new({ asset => $resource_name, assetGroup => Google::Ads::GoogleAds::V21::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::V21::Services::GoogleAdsService::MutateOperation ->new({ assetGroupAssetOperation => Google::Ads::GoogleAds::V21::Services::AssetGroupAssetService::AssetGroupAssetOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::AssetGroupAsset->new({ asset => $resource_name, assetGroup => Google::Ads::GoogleAds::V21::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 and logo asset. push @$operations, @{ create_and_link_brand_assets( $customer_id, $brand_guidelines_enabled, "Interplanetary Cruises", "https://gaagl.page.link/1Crm", "Logo Image" )}; # Create and link the image assets. # 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" )}; # After being created the list must be sorted so that all asset # operations come before all the asset group asset operations, # otherwise the API will reject the request. return sort_asset_and_asset_group_asset_operations($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::V21::Services::GoogleAdsService::MutateOperation-> new({ assetOperation => Google::Ads::GoogleAds::V21::Services::AssetService::AssetOperation-> new({ create => Google::Ads::GoogleAds::V21::Resources::Asset->new({ resourceName => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset( $customer_id, $next_temp_id ), textAsset => Google::Ads::GoogleAds::V21::Common::TextAsset->new({ text => $text })})})}); # Create an asset group asset to link the asset to the asset group. push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation-> new({ assetGroupAssetOperation => Google::Ads::GoogleAds::V21::Services::AssetGroupAssetService::AssetGroupAssetOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::AssetGroupAsset->new({ asset => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset( $customer_id, $next_temp_id ), assetGroup => Google::Ads::GoogleAds::V21::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::V21::Services::GoogleAdsService::MutateOperation-> new({ assetOperation => Google::Ads::GoogleAds::V21::Services::AssetService::AssetOperation-> new({ create => Google::Ads::GoogleAds::V21::Resources::Asset->new({ resourceName => Google::Ads::GoogleAds::V21::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::V21::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::V21::Services::GoogleAdsService::MutateOperation-> new({ assetGroupAssetOperation => Google::Ads::GoogleAds::V21::Services::AssetGroupAssetService::AssetGroupAssetOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::AssetGroupAsset->new({ asset => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset( $customer_id, $next_temp_id ), assetGroup => Google::Ads::GoogleAds::V21::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 linked brand assets. sub create_and_link_brand_assets { my ($customer_id, $brand_guidelines_enabled, $business_name, $logo_url, $logo_name) = @_; my $operations = []; # Create the text asset. my $text_asset_temp_id = $next_temp_id--; push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation-> new({ assetOperation => Google::Ads::GoogleAds::V21::Services::AssetService::AssetOperation-> new({ create => Google::Ads::GoogleAds::V21::Resources::Asset->new({ resourceName => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset( $customer_id, $text_asset_temp_id ), textAsset => Google::Ads::GoogleAds::V21::Common::TextAsset->new({ text => $business_name })})})}); # Create the image asset. my $image_asset_temp_id = $next_temp_id--; push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation-> new({ assetOperation => Google::Ads::GoogleAds::V21::Services::AssetService::AssetOperation-> new({ create => Google::Ads::GoogleAds::V21::Resources::Asset->new({ resourceName => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset( $customer_id, $image_asset_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 => $logo_name, imageAsset => Google::Ads::GoogleAds::V21::Common::ImageAsset->new({ data => get_base64_data_from_url($logo_url)})})})}); if ($brand_guidelines_enabled) { # Create CampaignAsset resources to link the Asset resources to the Campaign. push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation ->new({ campaignAssetOperation => Google::Ads::GoogleAds::V21::Services::CampaignAssetService::CampaignAssetOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::CampaignAsset->new({ fieldType => BUSINESS_NAME, campaign => Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign( $customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ), asset => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset( $customer_id, $text_asset_temp_id )})})}); push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation ->new({ campaignAssetOperation => Google::Ads::GoogleAds::V21::Services::CampaignAssetService::CampaignAssetOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::CampaignAsset->new({ fieldType => LOGO, campaign => Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign( $customer_id, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID ), asset => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset( $customer_id, $image_asset_temp_id )})})}); } else { # Create AssetGroupAsset resources to link the Asset resources to the AssetGroup. push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation ->new({ assetGroupAssetOperation => Google::Ads::GoogleAds::V21::Services::AssetGroupAssetService::AssetGroupAssetOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::AssetGroupAsset->new({ asset => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset( $customer_id, $text_asset_temp_id ), assetGroup => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset_group( $customer_id, ASSET_GROUP_TEMPORARY_ID ), fieldType => BUSINESS_NAME })})}); push @$operations, Google::Ads::GoogleAds::V21::Services::GoogleAdsService::MutateOperation ->new({ assetGroupAssetOperation => Google::Ads::GoogleAds::V21::Services::AssetGroupAssetService::AssetGroupAssetOperation ->new({ create => Google::Ads::GoogleAds::V21::Resources::AssetGroupAsset->new({ asset => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset( $customer_id, $image_asset_temp_id ), assetGroup => Google::Ads::GoogleAds::V21::Utils::ResourceNames::asset_group( $customer_id, ASSET_GROUP_TEMPORARY_ID ), fieldType => LOGO })})}); } return $operations; } # Sorts a list of asset and asset group asset operations. # # This sorts the list such that all asset operations precede # all asset group asset operations. If asset group assets are # created before assets then an error will be returned by the API. sub sort_asset_and_asset_group_asset_operations { my ($operations) = @_; sub sorter { if (defined $a->{assetOperation}) { return -1; } else { return 1; } } my @operations_sorted = sort sorter @$operations; return \@operations_sorted; } # 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 }); # 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::V21::Resources::CampaignConversionGoal->new({ resourceName => Google::Ads::GoogleAds::V21::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::V21::Services::GoogleAdsService::MutateOperation ->new({ campaignConversionGoalOperation => Google::Ads::GoogleAds::V21::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; } # 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); my $customer_id = undef; my $merchant_center_account_id = undef; my $sales_country = "US"; my $final_url = "http://www.example.com"; my $brand_guidelines_enabled = "false"; # 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, "brand_guidelines_enabled=s" => \$brand_guidelines_enabled ); # 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, $brand_guidelines_enabled); =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. -brand_guidelines_enabled [optional] A boolean value indicating if the campaign is enabled for brand guidelines. Defaults to false. =cut