Java
// Copyright 2018 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 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.v6.common.ListingGroupInfo;
import com.google.ads.googleads.v6.common.MaximizeConversionValue;
import com.google.ads.googleads.v6.common.ShoppingSmartAdInfo;
import com.google.ads.googleads.v6.enums.AdGroupCriterionStatusEnum.AdGroupCriterionStatus;
import com.google.ads.googleads.v6.enums.AdGroupStatusEnum.AdGroupStatus;
import com.google.ads.googleads.v6.enums.AdGroupTypeEnum.AdGroupType;
import com.google.ads.googleads.v6.enums.AdvertisingChannelSubTypeEnum.AdvertisingChannelSubType;
import com.google.ads.googleads.v6.enums.AdvertisingChannelTypeEnum.AdvertisingChannelType;
import com.google.ads.googleads.v6.enums.BudgetDeliveryMethodEnum.BudgetDeliveryMethod;
import com.google.ads.googleads.v6.enums.CampaignStatusEnum.CampaignStatus;
import com.google.ads.googleads.v6.enums.ListingGroupTypeEnum.ListingGroupType;
import com.google.ads.googleads.v6.errors.GoogleAdsError;
import com.google.ads.googleads.v6.errors.GoogleAdsException;
import com.google.ads.googleads.v6.resources.Ad;
import com.google.ads.googleads.v6.resources.AdGroup;
import com.google.ads.googleads.v6.resources.AdGroupAd;
import com.google.ads.googleads.v6.resources.AdGroupCriterion;
import com.google.ads.googleads.v6.resources.Campaign;
import com.google.ads.googleads.v6.resources.Campaign.ShoppingSetting;
import com.google.ads.googleads.v6.resources.CampaignBudget;
import com.google.ads.googleads.v6.services.AdGroupAdOperation;
import com.google.ads.googleads.v6.services.AdGroupAdServiceClient;
import com.google.ads.googleads.v6.services.AdGroupCriterionOperation;
import com.google.ads.googleads.v6.services.AdGroupCriterionServiceClient;
import com.google.ads.googleads.v6.services.AdGroupOperation;
import com.google.ads.googleads.v6.services.AdGroupServiceClient;
import com.google.ads.googleads.v6.services.CampaignBudgetOperation;
import com.google.ads.googleads.v6.services.CampaignBudgetServiceClient;
import com.google.ads.googleads.v6.services.CampaignOperation;
import com.google.ads.googleads.v6.services.CampaignServiceClient;
import com.google.ads.googleads.v6.services.MutateAdGroupAdResult;
import com.google.ads.googleads.v6.services.MutateAdGroupCriterionResult;
import com.google.ads.googleads.v6.services.MutateAdGroupResult;
import com.google.ads.googleads.v6.services.MutateCampaignBudgetsResponse;
import com.google.ads.googleads.v6.services.MutateCampaignResult;
import com.google.common.collect.ImmutableList;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.util.Collections;
/**
* Creates a Smart Shopping campaign, a Smart Shopping ad group, a Smart Shopping ad group ad and a
* listing group for "All products".
*
* <p>Prerequisite: 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/adwords/shopping/full-automation/articles/t15.
*/
public class AddShoppingSmartAd {
private static class AddShoppingSmartAdParams extends CodeSampleParams {
@Parameter(names = ArgumentNames.CUSTOMER_ID, required = true)
private Long customerId;
@Parameter(names = ArgumentNames.MERCHANT_CENTER_ACCOUNT_ID, required = true)
private Long merchantCenterAccountId;
@Parameter(names = ArgumentNames.CREATE_DEFAULT_LISTING_GROUP, required = true, arity = 1)
private Boolean createDefaultListingGroup;
}
public static void main(String[] args) {
AddShoppingSmartAdParams params = new AddShoppingSmartAdParams();
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.createDefaultListingGroup =
Boolean.parseBoolean("INSERT_CREATE_DEFAULT_LISTING_GROUP_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 AddShoppingSmartAd()
.runExample(
googleAdsClient,
params.customerId,
params.merchantCenterAccountId,
params.createDefaultListingGroup);
} 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 createDefaultListingGroup the boolean to indicate if a default listing group should be
* created for the ad group. Set to false if the listing group will be constructed elsewhere.
* @throws GoogleAdsException if an API request failed with one or more service errors.
*/
private void runExample(
GoogleAdsClient googleAdsClient,
long customerId,
long merchantCenterAccountId,
boolean createDefaultListingGroup) {
// Creates a budget to be used by the campaign that will be created below.
String budgetResourceName = addCampaignBudget(googleAdsClient, customerId);
// Creates a Smart Shopping campaign.
String campaignResourceName =
addSmartShoppingCampaign(
googleAdsClient, customerId, budgetResourceName, merchantCenterAccountId);
// Creates a Smart Shopping ad group.
String adGroupResourceName =
addSmartShoppingAdGroup(googleAdsClient, customerId, campaignResourceName);
// Creates a Smart Shopping ad group ad.
addSmartShoppingAdGroupAd(googleAdsClient, customerId, adGroupResourceName);
if (createDefaultListingGroup) {
// A product group is a subset of inventory. Listing groups are the equivalent of product
// groups in the API and allow you to bid on the chosen group or exclude a group from bidding.
// This method creates an ad group criterion containing a listing group.
addShoppingListingGroup(googleAdsClient, customerId, adGroupResourceName);
}
}
/**
* Creates a new campaign budget for Smart Shopping ads in the specified client account.
*
* @param googleAdsClient the Google Ads API client.
* @param customerId the client customer ID.
* @return resource name of the newly created budget.
* @throws GoogleAdsException if an API request failed with one or more service errors.
*/
private String addCampaignBudget(GoogleAdsClient googleAdsClient, long customerId) {
CampaignBudget budget =
CampaignBudget.newBuilder()
.setName("Interplanetary Cruise Budget #" + System.currentTimeMillis())
.setDeliveryMethod(BudgetDeliveryMethod.STANDARD)
// The budget is specified in the local currency of the account.
// The amount should be specified in micros, where one million is equivalent to one
// unit.
.setAmountMicros(5_000_000L)
// Budgets for Smart Shopping campaigns cannot be shared.
.setExplicitlyShared(false)
.build();
CampaignBudgetOperation op = CampaignBudgetOperation.newBuilder().setCreate(budget).build();
try (CampaignBudgetServiceClient campaignBudgetServiceClient =
googleAdsClient.getLatestVersion().createCampaignBudgetServiceClient()) {
MutateCampaignBudgetsResponse response =
campaignBudgetServiceClient.mutateCampaignBudgets(
Long.toString(customerId), ImmutableList.of(op));
String budgetResourceName = response.getResults(0).getResourceName();
System.out.printf("Added a budget with resource name: '%s'%n", budgetResourceName);
return budgetResourceName;
}
}
/**
* Creates a new shopping campaign for Smart Shopping ads in the specified client account.
*
* @param googleAdsClient the Google Ads API client.
* @param customerId the client customer ID.
* @param budgetResourceName the resource name of the budget for the campaign.
* @param merchantCenterAccountId the Merchant Center account ID.
* @return resource name of the newly created campaign.
* @throws GoogleAdsException if an API request failed with one or more service errors.
*/
private String addSmartShoppingCampaign(
GoogleAdsClient googleAdsClient,
long customerId,
String budgetResourceName,
long merchantCenterAccountId) {
// Configures the shopping settings for Smart Shopping campaigns.
ShoppingSetting shoppingSetting =
ShoppingSetting.newBuilder()
// Sets the sales country of products to include in the campaign.
// Only products from Merchant Center targeting this country will appear in the
// campaign.
.setSalesCountry("US")
.setMerchantId(merchantCenterAccountId)
.build();
// Creates the campaign.
Campaign campaign =
Campaign.newBuilder()
.setName("Interplanetary Cruise #" + System.currentTimeMillis())
// Configures settings related to shopping campaigns including advertising channel type,
// advertising sub-type and shopping setting.
.setAdvertisingChannelType(AdvertisingChannelType.SHOPPING)
.setAdvertisingChannelSubType(AdvertisingChannelSubType.SHOPPING_SMART_ADS)
.setShoppingSetting(shoppingSetting)
// Recommendation: Sets the campaign to PAUSED when creating it to prevent
// the ads from immediately serving. Set to ENABLED once you've added
// targeting and the ads are ready to serve.
.setStatus(CampaignStatus.PAUSED)
// Bidding strategy must be set directly on the campaign.
// Setting a portfolio bidding strategy by resourceName is not supported.
// Maximize conversion value is the only strategy supported for Smart Shopping
// 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 maximize conversion value, see the support article:
// http://support.google.com/google-ads/answer/7684216)
.setMaximizeConversionValue(
MaximizeConversionValue.newBuilder().setTargetRoas(3.5).build())
// Sets the budget.
.setCampaignBudget(budgetResourceName)
.build();
// Creates a campaign operation.
CampaignOperation operation = CampaignOperation.newBuilder().setCreate(campaign).build();
// Issues a mutate request to add the campaign.
try (CampaignServiceClient campaignServiceClient =
googleAdsClient.getLatestVersion().createCampaignServiceClient()) {
MutateCampaignResult result =
campaignServiceClient
.mutateCampaigns(Long.toString(customerId), Collections.singletonList(operation))
.getResults(0);
System.out.printf(
"Added a Smart Shopping campaign with resource name: '%s'%n", result.getResourceName());
return result.getResourceName();
}
}
/**
* Creates a new ad group in the specified Smart Shopping campaign.
*
* @param googleAdsClient the Google Ads API client.
* @param customerId the client customer ID.
* @param campaignResourceName the resource name of the campaign that the new ad group will belong
* to.
* @return resource name of the newly created ad group.
* @throws GoogleAdsException if an API request failed with one or more service errors.
*/
private String addSmartShoppingAdGroup(
GoogleAdsClient googleAdsClient, long customerId, String campaignResourceName) {
// Creates an ad group.
AdGroup adGroup =
AdGroup.newBuilder()
.setName("Earth to Mars Cruises #" + System.currentTimeMillis())
.setCampaign(campaignResourceName)
// Sets the ad group type to SHOPPING_SMART_ADS. This cannot be set to other types.
.setType(AdGroupType.SHOPPING_SMART_ADS)
.setStatus(AdGroupStatus.ENABLED)
.build();
// Creates an ad group operation.
AdGroupOperation operation = AdGroupOperation.newBuilder().setCreate(adGroup).build();
// Issues a mutate request to add an ad group.
try (AdGroupServiceClient adGroupServiceClient =
googleAdsClient.getLatestVersion().createAdGroupServiceClient()) {
MutateAdGroupResult mutateAdGroupResult =
adGroupServiceClient
.mutateAdGroups(Long.toString(customerId), Collections.singletonList(operation))
.getResults(0);
System.out.printf(
"Added a Smart Shopping ad group with resource name: '%s'%n",
mutateAdGroupResult.getResourceName());
return mutateAdGroupResult.getResourceName();
}
}
/**
* Creates a new ad group ad in the specified Smart Shopping ad group.
*
* @param googleAdsClient the Google Ads API client.
* @param customerId the client customer ID.
* @param adGroupResourceName the resource name of the ad group that the new ad group ad will
* belong to.
* @return resource name of the newly created ad group ad.
* @throws GoogleAdsException if an API request failed with one or more service errors.
*/
private String addSmartShoppingAdGroupAd(
GoogleAdsClient googleAdsClient, long customerId, String adGroupResourceName) {
// Creates a new Smart Shopping ad.
Ad ad = Ad.newBuilder().setShoppingSmartAd(ShoppingSmartAdInfo.newBuilder().build()).build();
// Creates a new ad group ad and sets the Smart Shopping ad to it.
AdGroupAd adGroupAd =
AdGroupAd.newBuilder()
// Sets the ad to the ad created above.
.setAd(ad)
// Sets the ad group.
.setAdGroup(adGroupResourceName)
.build();
// Creates an ad group ad operation.
AdGroupAdOperation operation = AdGroupAdOperation.newBuilder().setCreate(adGroupAd).build();
// Issues a mutate request to add an ad group ad.
try (AdGroupAdServiceClient adGroupAdServiceClient =
googleAdsClient.getLatestVersion().createAdGroupAdServiceClient()) {
MutateAdGroupAdResult mutateAdGroupAdResult =
adGroupAdServiceClient
.mutateAdGroupAds(Long.toString(customerId), Collections.singletonList(operation))
.getResults(0);
System.out.printf(
"Added a Smart Shopping ad group ad with resource name: '%s'%n",
mutateAdGroupAdResult.getResourceName());
return mutateAdGroupAdResult.getResourceName();
}
}
/**
* Creates a new Shopping listing group for the specified ad group. This is known as a "product
* group" in the Google Ads user interface. The listing group will be added to the ad group using
* an "ad group criterion". For more information on listing groups see the Google Ads API Shopping
* guide: https://developers.google.com/google-ads/api/docs/shopping-ads/overview
*
* @param googleAdsClient the Google Ads API client.
* @param customerId the client customer ID.
* @param adGroupResourceName the resource name of the ad group that the new listing group will
* belong to.
* @return resource name of the newly created ad group criterion containing the listing group.
* @throws GoogleAdsException if an API request failed with one or more service errors.
*/
private String addShoppingListingGroup(
GoogleAdsClient googleAdsClient, long customerId, String adGroupResourceName) {
// Creates a new ad group criterion. This will contain a listing group.
// This will be the listing group for 'All products' and will contain a single root node.
AdGroupCriterion adGroupCriterion =
AdGroupCriterion.newBuilder()
.setAdGroup(adGroupResourceName)
.setStatus(AdGroupCriterionStatus.ENABLED)
// Creates a new listing group. This will be the top level listing group (root node)
// Set the type of the listing group to be a unit.
.setListingGroup(ListingGroupInfo.newBuilder().setType(ListingGroupType.UNIT).build())
// Note: Listing groups do not require bids for Smart Shopping campaigns.
.build();
AdGroupCriterionOperation operation =
AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterion).build();
try (AdGroupCriterionServiceClient adGroupCriterionServiceClient =
googleAdsClient.getLatestVersion().createAdGroupCriterionServiceClient()) {
MutateAdGroupCriterionResult mutateAdGroupCriteriaResult =
adGroupCriterionServiceClient
.mutateAdGroupCriteria(
Long.toString(customerId), Collections.singletonList(operation))
.getResults(0);
System.out.printf(
"Added an ad group criterion containing a listing group with resource name: '%s'%n",
mutateAdGroupCriteriaResult.getResourceName());
return mutateAdGroupCriteriaResult.getResourceName();
}
}
}
C#
// Copyright 2020 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 Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V6.Errors;
using Google.Ads.GoogleAds.V6.Common;
using Google.Ads.GoogleAds.V6.Resources;
using Google.Ads.GoogleAds.V6.Services;
using System;
using static Google.Ads.GoogleAds.V6.Enums.AdGroupAdStatusEnum.Types;
using static Google.Ads.GoogleAds.V6.Enums.AdGroupCriterionStatusEnum.Types;
using static Google.Ads.GoogleAds.V6.Enums.AdGroupStatusEnum.Types;
using static Google.Ads.GoogleAds.V6.Enums.AdGroupTypeEnum.Types;
using static Google.Ads.GoogleAds.V6.Enums.AdvertisingChannelTypeEnum.Types;
using static Google.Ads.GoogleAds.V6.Enums.BudgetDeliveryMethodEnum.Types;
using static Google.Ads.GoogleAds.V6.Enums.CampaignStatusEnum.Types;
using static Google.Ads.GoogleAds.V6.Enums.ListingGroupTypeEnum.Types;
using static Google.Ads.GoogleAds.V6.Resources.Campaign.Types;
using static Google.Ads.GoogleAds.V6.Enums.AdvertisingChannelSubTypeEnum.Types;
namespace Google.Ads.GoogleAds.Examples.V6
{
/// <summary>
/// This code example creates a Smart Shopping campaign, a Smart Shopping ad group, a Smart
/// Shopping ad group ad and a listing group for "All products".
///
/// Prerequisite: 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/adwords/shopping/full-automation/articles/t15.
/// </summary>
public class AddShoppingSmartAd : ExampleBase
{
/// <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)
{
AddShoppingSmartAd codeExample = new AddShoppingSmartAd();
Console.WriteLine(codeExample.Description);
// The Google Ads customer ID for which the call is made.
long customerId = long.Parse("INSERT_CUSTOMER_ID_HERE");
// The Merchant Center account ID.
long merchantCenterAccountId = long.Parse("INSERT_MERCHANT_CENTER_ACCOUNT_ID_HERE");
// The boolean to indicate if a default listing group should be created for the
// ad group. Set to false if the listing group will be constructed elsewhere.
//
// See AddShoppingListingGroupTree for a more comprehensive example.
bool createDefaultListingGroup =
bool.Parse("INSERT_CREATE_DEFAULT_LISTING_GROUP_HERE");
codeExample.Run(new GoogleAdsClient(), customerId, merchantCenterAccountId,
createDefaultListingGroup);
}
/// <summary>
/// Returns a description about the code example.
/// </summary>
public override string Description =>
"This code example creates a Smart Shopping campaign, a Smart Shopping ad group, a " +
"Smart Shopping ad group ad and a listing group for \"All products\"." +
"\nPrerequisite: 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.\nThis account must be linked to " +
"your Google Ads account.The integration instructions can be found at: " +
"https://developers.google.com/adwords/shopping/full-automation/articles/t15.";
/// <summary>
/// Runs the code example.
/// </summary>
/// <param name="client">The Google Ads client.</param>
/// <param name="customerId">The Google Ads customer ID for which the call is made.</param>
/// <param name="merchantCenterAccountId">The Merchant Center account ID.</param>
/// <param name="createDefaultListingGroup">The boolean to indicate if a default listing
/// group should be created for the ad group. Set to false if the listing group will be
/// constructed elsewhere.
///
/// See AddShoppingListingGroupTree for a more comprehensive example.</param>
public void Run(GoogleAdsClient client, long customerId, long merchantCenterAccountId,
bool createDefaultListingGroup)
{
try
{
// Creates a budget to be used by the campaign that will be created below.
string budgetResourceName = AddCampaignBudget(client, customerId);
// Creates a Smart Shopping campaign.
string campaignResourceName = AddSmartShoppingCampaign(
client, customerId, budgetResourceName, merchantCenterAccountId);
// Creates a Smart Shopping ad group.
string adGroupResourceName = AddSmartShoppingAdGroup(
client, customerId, campaignResourceName);
// Creates a Smart Shopping ad group ad.
AddSmartShoppingAdGroupAd(client, customerId, adGroupResourceName);
if (createDefaultListingGroup)
{
// A product group is a subset of inventory. Listing groups are the equivalent
// of product groups in the API and allow you to bid on the chosen group or
// exclude a group from bidding. This method creates an ad group criterion
// containing a listing group.
AddDefaultShoppingListingGroup(client, customerId, adGroupResourceName);
}
}
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 new campaign budget in the specified client account.
/// </summary>
/// <param name="client">The Google Ads API client.</param>
/// <param name="customerId">The client customer ID.</param>
/// <returns>Resource name of the newly created budget.</returns>
/// <exception cref="GoogleAdsException">Thrown if an API request failed with one or more
/// service errors.</exception>
private string AddCampaignBudget(GoogleAdsClient client, long customerId)
{
// Get the CampaignBudgetService.
CampaignBudgetServiceClient campaignBudgetService =
client.GetService(Services.V6.CampaignBudgetService);
CampaignBudget budget = new CampaignBudget()
{
Name = "Interplanetary Cruise Budget #" + ExampleUtilities.GetRandomString(),
DeliveryMethod = BudgetDeliveryMethod.Standard,
AmountMicros = 5_000_000L,
// Budgets for Smart Shopping campaigns cannot be shared.
ExplicitlyShared = false
};
CampaignBudgetOperation operation = new CampaignBudgetOperation()
{
Create = budget
};
MutateCampaignBudgetsResponse response =
campaignBudgetService.MutateCampaignBudgets(customerId.ToString(),
new CampaignBudgetOperation[] { operation });
string budgetResourceName = response.Results[0].ResourceName;
Console.WriteLine("Added a budget with resource name: '{0}'.", budgetResourceName);
return budgetResourceName;
}
/// <summary>
/// Creates a new shopping campaign for Smart Shopping ads in the specified client account.
/// </summary>
/// <param name="client">The Google Ads API client.</param>
/// <param name="customerId">The client customer ID.</param>
/// <param name="budgetResourceName">The resource name of the budget for the campaign.
/// </param>
/// <param name="merchantCenterAccountId">The Merchant Center account ID.</param>
/// <returns>Resource name of the newly created campaign.</returns>
/// <exception cref="GoogleAdsException">Thrown if an API request failed with one or more
/// service errors.</exception>
private string AddSmartShoppingCampaign(GoogleAdsClient client, long customerId,
string budgetResourceName, long merchantCenterAccountId)
{
// Get the CampaignService.
CampaignServiceClient campaignService =
client.GetService(Services.V6.CampaignService);
// Configures the shopping settings.
ShoppingSetting shoppingSetting = new ShoppingSetting()
{
// Sets the sales country of products to include in the campaign.
SalesCountry = "US",
MerchantId = merchantCenterAccountId,
};
// Create the standard shopping campaign.
Campaign campaign = new Campaign()
{
Name = "Interplanetary Cruise #" + ExampleUtilities.GetRandomString(),
// Configures settings related to shopping campaigns including advertising channel
// type, sub-type and shopping setting.
AdvertisingChannelType = AdvertisingChannelType.Shopping,
AdvertisingChannelSubType = AdvertisingChannelSubType.ShoppingSmartAds,
ShoppingSetting = shoppingSetting,
// Recommendation: Set the campaign to PAUSED when creating it to prevent
// the ads from immediately serving. Set to ENABLED once you've added
// targeting and the ads are ready to serve
Status = CampaignStatus.Paused,
// Bidding strategy must be set directly on the campaign.
// Setting a portfolio bidding strategy by resourceName is not supported.
// Maximize conversion value is the only strategy supported for Smart Shopping
// 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
// dividingW "total value" by "total spend".
// For more information on maximize conversion value, see the support article:
// http://support.google.com/google-ads/answer/7684216)
MaximizeConversionValue = new MaximizeConversionValue()
{
TargetRoas = 3.5
},
// Sets the budget.
CampaignBudget = budgetResourceName
};
// Creates a campaign operation.
CampaignOperation operation = new CampaignOperation()
{
Create = campaign
};
// Issues a mutate request to add the campaign.
MutateCampaignsResponse response =
campaignService.MutateCampaigns(customerId.ToString(),
new CampaignOperation[] { operation });
MutateCampaignResult result = response.Results[0];
Console.WriteLine("Added a Smart Shopping campaign with resource name: '{0}'.",
result.ResourceName);
return result.ResourceName;
}
/// <summary>
/// Creates a new ad group in the specified Smart Shopping campaign.
/// </summary>
/// <param name="client">The Google Ads API client.</param>
/// <param name="customerId">The client customer ID.</param>
/// <param name="campaignResourceName">Resource name of the shopping campaign that the
/// new ad group will belong to.</param>
/// <returns>Resource name of the newly created ad group.</returns>
/// <exception cref="GoogleAdsException">Thrown if an API request failed with one or more
/// service errors.</exception>
private string AddSmartShoppingAdGroup(GoogleAdsClient client, long customerId,
string campaignResourceName)
{
// Get the AdGroupService.
AdGroupServiceClient adGroupService = client.GetService(Services.V6.AdGroupService);
// Creates an ad group.
AdGroup adGroup = new AdGroup()
{
Name = "Earth to Mars Cruises #" + ExampleUtilities.GetRandomString(),
Campaign = campaignResourceName,
// Sets the ad group type to SHOPPING_SMART_ADS. This cannot be set to
// other types.
Type = AdGroupType.ShoppingSmartAds,
CpcBidMicros = 1_000_000L,
Status = AdGroupStatus.Enabled
};
// Creates an ad group operation.
AdGroupOperation operation = new AdGroupOperation()
{
Create = adGroup
};
// Issues a mutate request to add an ad group.
MutateAdGroupResult mutateAdGroupResult =
adGroupService
.MutateAdGroups(customerId.ToString(), new AdGroupOperation[] { operation })
.Results[0];
Console.WriteLine("Added a Smart Shopping ad group with resource name: '{0}'.",
mutateAdGroupResult.ResourceName);
return mutateAdGroupResult.ResourceName;
}
/// <summary>
/// Creates a new ad group ad in the specified Smart Shopping ad group.
/// </summary>
/// <param name="client">The Google Ads API client.</param>
/// <param name="customerId">The client customer ID.</param>
/// <param name="adGroupResourceName">The resource name of the ad group that the new ad
/// group ad will belong to.</param>
/// <returns>Resource name of the newly created ad group ad.</returns>
/// <exception cref="GoogleAdsException">Thrown if an API request failed with one or more
/// service errors.</exception>
private string AddSmartShoppingAdGroupAd(GoogleAdsClient client, long customerId,
string adGroupResourceName)
{
// Get the AdGroupAdService.
AdGroupAdServiceClient adGroupAdService = client.GetService(
Services.V6.AdGroupAdService);
// Creates a new shopping product ad.
Ad ad = new Ad()
{
ShoppingSmartAd = new ShoppingSmartAdInfo()
{
}
};
// Creates a new ad group ad and sets the shopping product ad to it.
AdGroupAd adGroupAd = new AdGroupAd()
{
// Sets the ad to the ad created above.
Ad = ad,
Status = AdGroupAdStatus.Paused,
// Sets the ad group.
AdGroup = adGroupResourceName
};
// Creates an ad group ad operation.
AdGroupAdOperation operation = new AdGroupAdOperation()
{
Create = adGroupAd
};
// Issues a mutate request to add an ad group ad.
MutateAdGroupAdResult mutateAdGroupAdResult = adGroupAdService.MutateAdGroupAds(
customerId.ToString(), new AdGroupAdOperation[] { operation }).Results[0];
Console.WriteLine("Added a Smart Shopping ad group ad with resource name: '{0}'.",
mutateAdGroupAdResult.ResourceName);
return mutateAdGroupAdResult.ResourceName;
}
/// <summary>
/// Creates a new Shopping listing group for the specified ad group. This is known as a
/// "product group" in the Google Ads user interface. The listing group will be added to
/// the ad group using an "ad group criterion". For more information on listing groups see
/// the Google Ads API Shopping guide: https://developers.google.com/google-ads/api/docs/shopping-ads/overview
/// </summary>
/// <param name="client">The Google Ads API client.</param>
/// <param name="customerId">The client customer ID.</param>
/// <param name="adGroupResourceName">The resource name of the ad group that the new
/// listing group will belong to.</param>
/// <returns>Resource name of the newly created ad group criterion containing the
/// listing group.</returns>
/// <exception cref="GoogleAdsException">Thrown if an API request failed with one or more
/// service errors.</exception>
private string AddDefaultShoppingListingGroup(GoogleAdsClient client, long customerId,
string adGroupResourceName)
{
// Get the AdGroupCriterionService.
AdGroupCriterionServiceClient adGroupCriterionService = client.GetService(
Services.V6.AdGroupCriterionService);
// Creates a new ad group criterion. This will contain the "default" listing group (All
// products).
AdGroupCriterion adGroupCriterion = new AdGroupCriterion()
{
AdGroup = adGroupResourceName,
Status = AdGroupCriterionStatus.Enabled,
// Creates a new listing group. This will be the top-level "root" node.
// Set the type of the listing group to be a biddable unit.
ListingGroup = new ListingGroupInfo()
{
Type = ListingGroupType.Unit
},
// Note: Listing groups do not require bids for Smart Shopping campaigns.
};
AdGroupCriterionOperation operation = new AdGroupCriterionOperation()
{
Create = adGroupCriterion
};
MutateAdGroupCriterionResult mutateAdGroupCriteriaResult =
adGroupCriterionService.MutateAdGroupCriteria(customerId.ToString(),
new AdGroupCriterionOperation[] { operation }).Results[0];
Console.WriteLine("Added an ad group criterion containing a listing group with " +
"resource name: '{0}'.", mutateAdGroupCriteriaResult.ResourceName);
return mutateAdGroupCriteriaResult.ResourceName;
}
}
}
PHP
<?php
/**
* Copyright 2019 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\Lib\V6\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V6\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V6\GoogleAdsException;
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\V6\Common\ListingGroupInfo;
use Google\Ads\GoogleAds\V6\Common\MaximizeConversionValue;
use Google\Ads\GoogleAds\V6\Common\ShoppingSmartAdInfo;
use Google\Ads\GoogleAds\V6\Enums\AdGroupAdStatusEnum\AdGroupAdStatus;
use Google\Ads\GoogleAds\V6\Enums\AdGroupStatusEnum\AdGroupStatus;
use Google\Ads\GoogleAds\V6\Enums\AdGroupTypeEnum\AdGroupType;
use Google\Ads\GoogleAds\V6\Enums\AdvertisingChannelSubTypeEnum\AdvertisingChannelSubType;
use Google\Ads\GoogleAds\V6\Enums\AdvertisingChannelTypeEnum\AdvertisingChannelType;
use Google\Ads\GoogleAds\V6\Enums\BudgetDeliveryMethodEnum\BudgetDeliveryMethod;
use Google\Ads\GoogleAds\V6\Enums\CampaignStatusEnum\CampaignStatus;
use Google\Ads\GoogleAds\V6\Enums\ListingGroupTypeEnum\ListingGroupType;
use Google\Ads\GoogleAds\V6\Errors\GoogleAdsError;
use Google\Ads\GoogleAds\V6\Resources\Ad;
use Google\Ads\GoogleAds\V6\Resources\AdGroup;
use Google\Ads\GoogleAds\V6\Resources\AdGroupAd;
use Google\Ads\GoogleAds\V6\Resources\AdGroupCriterion;
use Google\Ads\GoogleAds\V6\Resources\Campaign;
use Google\Ads\GoogleAds\V6\Resources\Campaign\ShoppingSetting;
use Google\Ads\GoogleAds\V6\Resources\CampaignBudget;
use Google\Ads\GoogleAds\V6\Services\AdGroupAdOperation;
use Google\Ads\GoogleAds\V6\Services\AdGroupCriterionOperation;
use Google\Ads\GoogleAds\V6\Services\AdGroupOperation;
use Google\Ads\GoogleAds\V6\Services\CampaignBudgetOperation;
use Google\Ads\GoogleAds\V6\Services\CampaignOperation;
use Google\ApiCore\ApiException;
/**
* This example creates a Smart Shopping campaign, a Smart Shopping ad group, a Smart Shopping ad
* group ad and a listing group for "All products".
*
* 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/adwords/shopping/full-automation/articles/t15.
* - 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.
*/
class AddShoppingSmartAd
{
private const CUSTOMER_ID = 'INSERT_CUSTOMER_ID_HERE';
private const MERCHANT_CENTER_ACCOUNT_ID = 'INSERT_MERCHANT_CENTER_ACCOUNT_ID_HERE';
private const SHOULD_CREATE_DEFAULT_LISTING_GROUP = 'INSERT_BOOLEAN_TRUE_OR_FALSE_HERE';
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::SHOULD_CREATE_DEFAULT_LISTING_GROUP => GetOpt::REQUIRED_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,
filter_var(
$options[ArgumentNames::SHOULD_CREATE_DEFAULT_LISTING_GROUP]
?: self::SHOULD_CREATE_DEFAULT_LISTING_GROUP,
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 bool $shouldCreateDefaultListingGroup indicates if a default listing
* group should be created for the ad group. Set to false if the listing group will be
* constructed elsewhere.
*/
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId,
int $merchantCenterAccountId,
bool $shouldCreateDefaultListingGroup
) {
// Creates a budget to be used by the campaign that will be created below.
$budgetResourceName = self::addCampaignBudget($googleAdsClient, $customerId);
// Creates a Smart Shopping campaign.
$campaignResourceName = self::addSmartShoppingCampaign(
$googleAdsClient,
$customerId,
$budgetResourceName,
$merchantCenterAccountId
);
// Creates a Smart Shopping ad group.
$adGroupResourceName =
self::addSmartShoppingAdGroup($googleAdsClient, $customerId, $campaignResourceName);
// Creates a Smart Shopping ad group ad.
self::addSmartShoppingAdGroupAd($googleAdsClient, $customerId, $adGroupResourceName);
if ($shouldCreateDefaultListingGroup) {
// A product group is a subset of inventory. Listing groups are the equivalent
// of product groups in the API and allow you to bid on the chosen group or
// exclude a group from bidding.
// This method creates an ad group criterion containing a listing group.
self::addShoppingListingGroup(
$googleAdsClient,
$customerId,
$adGroupResourceName
);
}
}
/**
* Creates a new campaign budget for Smart Shopping ads in the specified client account.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @return string the resource name of the newly created budget
*/
private static function addCampaignBudget(GoogleAdsClient $googleAdsClient, int $customerId)
{
// Creates a campaign budget.
$budget = new CampaignBudget([
'name' => 'Interplanetary Cruise Budget #' . uniqid(),
'delivery_method' => BudgetDeliveryMethod::STANDARD,
// The budget is specified in the local currency of the account.
// The amount should be specified in micros, where one million is equivalent to one
// unit.
'amount_micros' => 50000000,
// Budgets for Smart Shopping campaigns cannot be shared.
'explicitly_shared' => false
]);
// Creates a campaign budget operation.
$campaignBudgetOperation = new CampaignBudgetOperation();
$campaignBudgetOperation->setCreate($budget);
// Issues a mutate request.
$campaignBudgetServiceClient = $googleAdsClient->getCampaignBudgetServiceClient();
$response = $campaignBudgetServiceClient->mutateCampaignBudgets(
$customerId,
[$campaignBudgetOperation]
);
/** @var CampaignBudget $addedBudget */
$addedBudget = $response->getResults()[0];
printf(
"Added a budget with resource name '%s'.%s",
$addedBudget->getResourceName(),
PHP_EOL
);
return $addedBudget->getResourceName();
}
/**
* Creates a new shopping campaign for Smart Shopping ads in the specified client account.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @param string $budgetResourceName the resource name of budget for a new campaign
* @param int $merchantCenterAccountId the Merchant Center account ID
* @return string the resource name of the newly created campaign
*/
private static function addSmartShoppingCampaign(
GoogleAdsClient $googleAdsClient,
int $customerId,
string $budgetResourceName,
int $merchantCenterAccountId
) {
// Configures the shopping settings for Smart Shopping campaigns.
$shoppingSettings = new ShoppingSetting([
// Sets the sales country of products to include in the campaign.
// Only products from Merchant Center targeting this country will appear in the
// campaign.
'sales_country' => 'US',
'merchant_id' => $merchantCenterAccountId
]);
// Creates the campaign.
$campaign = new Campaign([
'name' => 'Interplanetary Cruise Campaign #' . uniqid(),
// Configures settings related to shopping campaigns including
// advertising channel type, advertising sub-type and shopping setting.
'advertising_channel_type' => AdvertisingChannelType::SHOPPING,
'advertising_channel_sub_type' => AdvertisingChannelSubType::SHOPPING_SMART_ADS,
'shopping_setting' => $shoppingSettings,
// Recommendation: Set the campaign to PAUSED when creating it to prevent
// the ads from immediately serving. Set to ENABLED once you've added
// targeting and the ads are ready to serve.
'status' => CampaignStatus::PAUSED,
// Bidding strategy must be set directly on the campaign.
// Setting a portfolio bidding strategy by resource name is not supported.
// Maximize conversion value is the only strategy supported for Smart Shopping
// 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 maximize conversion value, see the support article:
// http://support.google.com/google-ads/answer/7684216.
'maximize_conversion_value' => new MaximizeConversionValue(['target_roas' => 3.5]),
// Sets the budget.
'campaign_budget' => $budgetResourceName
]);
// Creates a campaign operation.
$campaignOperation = new CampaignOperation();
$campaignOperation->setCreate($campaign);
// Issues a mutate request to add the campaign.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);
/** @var Campaign $addedCampaign */
$addedCampaign = $response->getResults()[0];
$addedCampaignResourceName = $addedCampaign->getResourceName();
printf(
"Added a Smart Shopping campaign with resource name: '%s'.%s",
$addedCampaignResourceName,
PHP_EOL
);
return $addedCampaignResourceName;
}
/**
* Creates a new ad group in the specified Smart Shopping campaign.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @param string $campaignResourceName the resource name of the campaign that
* the new ad group will belong to
* @return string the resource name of the newly created ad group
*/
private static function addSmartShoppingAdGroup(
GoogleAdsClient $googleAdsClient,
int $customerId,
string $campaignResourceName
) {
// Creates an ad group.
$adGroup = new AdGroup([
'name' => 'Earth to Mars Cruise #' . uniqid(),
'campaign' => $campaignResourceName,
// Sets the ad group type to SHOPPING_SMART_ADS. This cannot be set to other types.
'type' => AdGroupType::SHOPPING_SMART_ADS,
'status' => AdGroupStatus::ENABLED
]);
// Creates an ad group operation.
$adGroupOperation = new AdGroupOperation();
$adGroupOperation->setCreate($adGroup);
// Issues a mutate request to add the ad group.
$adGroupServiceClient = $googleAdsClient->getAdGroupServiceClient();
$response = $adGroupServiceClient->mutateAdGroups($customerId, [$adGroupOperation]);
/** @var AdGroup $addedAdGroup */
$addedAdGroup = $response->getResults()[0];
$addedAdGroupResourceName = $addedAdGroup->getResourceName();
printf(
"Added a Smart Shopping ad group with resource name: '%s'.%s",
$addedAdGroupResourceName,
PHP_EOL
);
return $addedAdGroupResourceName;
}
/**
* Creates a new ad group ad in the specified Smart Shopping ad group.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @param string $adGroupResourceName the resource name of the ad group that
* the new ad group ad will belong to
*/
private static function addSmartShoppingAdGroupAd(
GoogleAdsClient $googleAdsClient,
int $customerId,
string $adGroupResourceName
) {
// Creates a new ad group ad.
$adGroupAd = new AdGroupAd([
// Sets a new Smart Shopping ad.
'ad' => new Ad(['shopping_smart_ad' => new ShoppingSmartAdInfo()]),
// Sets the ad group.
'ad_group' => $adGroupResourceName
]);
// Creates an ad group ad operation.
$adGroupAdOperation = new AdGroupAdOperation();
$adGroupAdOperation->setCreate($adGroupAd);
// Issues a mutate request to add the ad group ad.
$adGroupAdServiceClient = $googleAdsClient->getAdGroupAdServiceClient();
$response = $adGroupAdServiceClient->mutateAdGroupAds($customerId, [$adGroupAdOperation]);
/** @var AdGroupAd $addedAdGroupAd */
$addedAdGroupAd = $response->getResults()[0];
printf(
"Added a Smart Shopping ad group ad with resource name: '%s'.%s",
$addedAdGroupAd->getResourceName(),
PHP_EOL
);
}
/**
* Creates a new Shopping listing group for the specified ad group. This is known as a "product
* group" in the Google Ads user interface. The listing group will be added to the ad group
* using an "ad group criterion". For more information on listing groups see the Google Ads
* API Shopping guide: https://developers.google.com/google-ads/api/docs/shopping-ads/overview.
*
* @param GoogleAdsClient $googleAdsClient the Google Ads API client
* @param int $customerId the customer ID
* @param string $adGroupResourceName the resource name of the ad group that
* the new listing group will belong to
*/
private static function addShoppingListingGroup(
GoogleAdsClient $googleAdsClient,
int $customerId,
string $adGroupResourceName
) {
// Creates a new ad group criterion. This will contain a listing group.
// This will be the listing group for 'All products' and will contain a single root node.
$adGroupCriterion = new AdGroupCriterion([
'ad_group' => $adGroupResourceName,
'status' => AdGroupAdStatus::ENABLED,
// Creates a new listing group. This will be the top-level "root" node.
// Sets the type of the listing group to be a biddable unit.
'listing_group' => new ListingGroupInfo(['type' => ListingGroupType::UNIT])
// Note: Listing groups do not require bids for Smart Shopping campaigns.
]);
// Creates an ad group criterion operation.
$adGroupCriterionOperation = new AdGroupCriterionOperation();
$adGroupCriterionOperation->setCreate($adGroupCriterion);
// Issues a mutate request to add the ad group criterion.
$adGroupCriterionServiceClient = $googleAdsClient->getAdGroupCriterionServiceClient();
$response = $adGroupCriterionServiceClient->mutateAdGroupCriteria(
$customerId,
[$adGroupCriterionOperation]
);
/** @var AdGroupCriterion $addedAdGroupCriterion */
$addedAdGroupCriterion = $response->getResults()[0];
printf(
"Added an ad group criterion containing a listing group with resource name: '%s'.%s",
$addedAdGroupCriterion->getResourceName(),
PHP_EOL
);
}
}
AddShoppingSmartAd::main();
Ruby
#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright 2019 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 creates a standard shopping product campaign, ad group, and ad.
#
# Prerequisite: 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 example creates a Smart Shopping campaign, a Smart Shopping ad group,
# a Smart Shopping ad group ad and a listing group for "All products".
#
# 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/adwords/shopping/full-automation/articles/t15.
# - 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.
require 'optparse'
require 'google/ads/google_ads'
require 'date'
def add_shopping_smart_ad(
customer_id, merchant_center_id, create_default_listing_group)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
budget_name = add_campaign_budget(client, customer_id)
campaign_name = add_smart_shopping_campaign(
client,
customer_id,
budget_name,
merchant_center_id,
)
ad_group_name = add_smart_shopping_ad_group(
client,
customer_id,
campaign_name,
)
add_smart_shopping_ad_group_ad(client, customer_id, ad_group_name)
if create_default_listing_group
# A product group is a subset of inventory. Listing groups are the equivalent
# of product groups in the API and allow you to bid on the chosen group or
# exclude a group from bidding.
# This method creates an ad group criterion containing a listing group.
add_default_shopping_listing_group(client, customer_id, ad_group_name)
end
end
def add_campaign_budget(client, customer_id)
operation = client.operation.create_resource.campaign_budget do |budget|
budget.name = "Interplanetary Budget ##{(Time.new.to_f * 1000).to_i}"
budget.delivery_method = :STANDARD
budget.amount_micros = 500_000
# Budgets for Smart Shopping campaigns cannot be shared.
budget.explicitly_shared = false
end
service = client.service.campaign_budget
response = service.mutate_campaign_budgets(
customer_id: customer_id,
operations: [operation],
)
budget_name = response.results.first.resource_name
puts "Added a budget with resource name: #{budget_name}"
budget_name
end
def add_smart_shopping_campaign(
client, customer_id, budget_name, merchant_center_id)
operation = client.operation.create_resource.campaign do |campaign|
campaign.name = "Interplanetary Cruise Campaign ##{(Time.new.to_f * 1000).to_i}"
# Configures settings related to shopping campaigns including
# advertising channel type, advertising sub-type and shopping setting.
campaign.advertising_channel_type = :SHOPPING
campaign.advertising_channel_sub_type = :SHOPPING_SMART_ADS
campaign.shopping_setting = client.resource.shopping_setting do |shopping_setting|
shopping_setting.merchant_id = merchant_center_id
# Sets the sales country of products to include in the campaign.
# Only products from Merchant Center targeting this country will appear in the
# campaign.
shopping_setting.sales_country = "US"
end
# Recommendation: Set the campaign to PAUSED when creating it to prevent
# the ads from immediately serving. Set to ENABLED once you've added
# targeting and the ads are ready to serve.
campaign.status = :PAUSED
# Bidding strategy must be set directly on the campaign.
# Setting a portfolio bidding strategy by resource name is not supported.
# Maximize conversion value is the only strategy supported for Smart Shopping
# 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 maximize conversion value, see the support article:
# http://support.google.com/google-ads/answer/7684216.
campaign.maximize_conversion_value = client.resource.maximize_conversion_value do |m|
m.target_roas = 3.5
end
campaign.campaign_budget = budget_name
end
response = client.service.campaign.mutate_campaigns(
customer_id: customer_id,
operations: [operation],
)
campaign_name = response.results.first.resource_name
puts "Added a Smart Shopping Campaign with resource name #{campaign_name}."
campaign_name
end
def add_smart_shopping_ad_group(client, customer_id, campaign_name)
operation = client.operation.create_resource.ad_group do |ad_group|
ad_group.name = "Earth to Mars cruise ##{(Time.new.to_f * 1000).to_i}"
ad_group.status = :ENABLED
ad_group.campaign = campaign_name
# Sets the ad group type to SHOPPING_SMART_ADS.
# This cannot be set to other types.
ad_group.type = :SHOPPING_SMART_ADS
end
service = client.service.ad_group
response = service.mutate_ad_groups(
customer_id: customer_id,
operations: [operation],
)
ad_group_name = response.results.first.resource_name
puts "Added a Smart Shopping ad group with resource name #{ad_group_name}."
ad_group_name
end
def add_smart_shopping_ad_group_ad(client, customer_id, ad_group_name)
operation = client.operation.create_resource.ad_group_ad do |ad_group_ad|
ad_group_ad.ad_group = ad_group_name
ad_group_ad.ad = client.resource.ad do |ad|
ad.shopping_smart_ad = client.resource.shopping_smart_ad_info
end
end
service = client.service.ad_group_ad
response = service.mutate_ad_group_ads(
customer_id: customer_id,
operations: [operation],
)
puts "Created a Smart Shopping ad group ad " \
"#{response.results.first.resource_name}"
end
def add_default_shopping_listing_group(client, customer_id, ad_group_name)
operation = client.operation.create_resource.ad_group_criterion do |criterion|
criterion.ad_group = ad_group_name
criterion.status = :ENABLED
criterion.listing_group = client.resource.listing_group_info do |lgi|
lgi.type = :UNIT
end
criterion.cpc_bid_micros = 500_000
end
service = client.service.ad_group_criterion
response = service.mutate_ad_group_criteria(customer_id, [operation])
puts "Added an ad group criterion containing a listing group with resource " \
"name #{response.results.first.resource_name}."
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_id] = 'INSERT_MERCHANT_CENTER_ID_HERE'
# Specifying any value for this field on the command line will override this
# to true.
options[:create_default_listing_group] = false
OptionParser.new do |opts|
opts.banner = sprintf("Usage: #{File.basename(__FILE__)} [options]")
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-id MERCHANT-CENTER-ID', Integer,
'Merchant Center ID') do |v|
options[:merchant_center_id] = v
end
opts.on('-d', '--create-default-listing-group CREATE-DEFAULT-LISTING-GROUP',
String, 'Create Default Listing Group') do |v|
options[:create_default_listing_group] = true if v
end
opts.separator ''
opts.separator 'Help:'
opts.on_tail('-h', '--help', 'Show this message') do
puts opts
exit
end
end.parse!
begin
add_shopping_smart_ad(
options.fetch(:customer_id).tr("-", ""),
options.fetch(:merchant_center_id),
options.fetch(:create_default_listing_group),
)
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 2019, 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 creates a smart shopping campaign, a smart shopping ad group,
# a smart shopping ad group ad and a listing group for "All products".
#
# Prerequisite:
# - 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/adwords/shopping/full-automation/articles/t15.
# - 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.
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::V6::Resources::CampaignBudget;
use Google::Ads::GoogleAds::V6::Resources::Campaign;
use Google::Ads::GoogleAds::V6::Resources::ShoppingSetting;
use Google::Ads::GoogleAds::V6::Resources::AdGroup;
use Google::Ads::GoogleAds::V6::Resources::AdGroupAd;
use Google::Ads::GoogleAds::V6::Resources::Ad;
use Google::Ads::GoogleAds::V6::Resources::AdGroupCriterion;
use Google::Ads::GoogleAds::V6::Common::MaximizeConversionValue;
use Google::Ads::GoogleAds::V6::Common::ShoppingSmartAdInfo;
use Google::Ads::GoogleAds::V6::Common::ListingGroupInfo;
use Google::Ads::GoogleAds::V6::Enums::BudgetDeliveryMethodEnum qw(STANDARD);
use Google::Ads::GoogleAds::V6::Enums::AdvertisingChannelTypeEnum qw(SHOPPING);
use Google::Ads::GoogleAds::V6::Enums::AdvertisingChannelSubTypeEnum
qw(SHOPPING_SMART_ADS);
use Google::Ads::GoogleAds::V6::Enums::AdGroupTypeEnum;
use Google::Ads::GoogleAds::V6::Enums::CampaignStatusEnum;
use Google::Ads::GoogleAds::V6::Enums::AdGroupStatusEnum;
use Google::Ads::GoogleAds::V6::Enums::AdGroupAdStatusEnum;
use Google::Ads::GoogleAds::V6::Enums::ListingGroupTypeEnum qw(UNIT);
use Google::Ads::GoogleAds::V6::Enums::AdGroupCriterionStatusEnum;
use
Google::Ads::GoogleAds::V6::Services::CampaignBudgetService::CampaignBudgetOperation;
use Google::Ads::GoogleAds::V6::Services::CampaignService::CampaignOperation;
use Google::Ads::GoogleAds::V6::Services::AdGroupService::AdGroupOperation;
use Google::Ads::GoogleAds::V6::Services::AdGroupAdService::AdGroupAdOperation;
use
Google::Ads::GoogleAds::V6::Services::AdGroupCriterionService::AdGroupCriterionOperation;
use Getopt::Long qw(:config auto_help);
use Pod::Usage;
use Cwd qw(abs_path);
use Data::Uniqid qw(uniqid);
# The following parameter(s) should be provided to run the example. You can
# either specify these by changing the INSERT_XXX_ID_HERE values below, or on
# the command line.
#
# Parameters passed on the command line will override any parameters set in
# code.
#
# Running the example with -h will print the command line usage.
my $customer_id = "INSERT_CUSTOMER_ID_HERE";
my $merchant_center_account_id = "INSERT_MERCHANT_CENTER_ACCOUNT_ID_HERE";
my $create_default_listing_group = undef;
sub add_shopping_smart_ad {
my ($api_client, $customer_id, $merchant_center_account_id,
$create_default_listing_group)
= @_;
# Create a budget to be used by the campaign that will be created below.
my $budget_resource_name = add_campaign_budget($api_client, $customer_id);
# Create a smart shopping campaign.
my $campaign_resource_name =
add_smart_shopping_campaign($api_client, $customer_id,
$budget_resource_name, $merchant_center_account_id);
# Create a smart shopping ad group.
my $ad_group_resource_name =
add_smart_shopping_ad_group($api_client, $customer_id,
$campaign_resource_name);
# Creates a smart shopping ad group ad.
add_smart_shopping_ad_group_ad($api_client, $customer_id,
$ad_group_resource_name);
if ($create_default_listing_group) {
# A product group is a subset of inventory. Listing groups are the equivalent
# of product groups in the API and allow you to bid on the chosen group or
# exclude a group from bidding.
# This method creates an ad group criterion containing a listing group.
add_shopping_listing_group($api_client, $customer_id,
$ad_group_resource_name);
}
return 1;
}
# Creates a new campaign budget for smart shopping ads in the specified
# client account.
sub add_campaign_budget {
my ($api_client, $customer_id) = @_;
# Create a campaign budget.
my $campaign_budget =
Google::Ads::GoogleAds::V6::Resources::CampaignBudget->new({
name => "Interplanetary Cruise Budget #" . uniqid(),
deliveryMethod => STANDARD,
# The budget is specified in the local currency of the account.
# The amount should be specified in micros, where one million is
# equivalent to one unit.
amountMicros => 5000000,
# Budgets for smart shopping campaigns cannot be shared.
explicitlyShared => "false"
});
# Create a campaign budget operation.
my $campaign_budget_operation =
Google::Ads::GoogleAds::V6::Services::CampaignBudgetService::CampaignBudgetOperation
->new({create => $campaign_budget});
# Add the budget.
my $campaign_budget_resource_name =
$api_client->CampaignBudgetService()->mutate({
customerId => $customer_id,
operations => [$campaign_budget_operation]})->{results}[0]{resourceName};
printf "Added a budget with resource name: '%s'.\n",
$campaign_budget_resource_name;
return $campaign_budget_resource_name;
}
# Creates a new shopping campaign for smart shopping ads in the specified
# client account.
sub add_smart_shopping_campaign {
my ($api_client, $customer_id, $budget_resource_name,
$merchant_center_account_id)
= @_;
# Create a smart shopping campaign.
my $campaign = Google::Ads::GoogleAds::V6::Resources::Campaign->new({
name => "Interplanetary Cruise Campaign #" . uniqid(),
# Configure settings related to shopping campaigns including advertising
# channel type, advertising channel sub-type and shopping setting.
advertisingChannelType => SHOPPING,
advertisingChannelSubType => SHOPPING_SMART_ADS,
shoppingSetting =>
Google::Ads::GoogleAds::V6::Resources::ShoppingSetting->new({
merchantId => $merchant_center_account_id,
# Set the sales country of products to include in the campaign.
# Only products from Merchant Center targeting this country will
# appear in the campaign.
salesCountry => "US"
}
),
# Recommendation: Set the campaign to PAUSED when creating it to prevent
# the ads from immediately serving. Set to ENABLED once you've added
# targeting and the ads are ready to serve.
status => Google::Ads::GoogleAds::V6::Enums::CampaignStatusEnum::PAUSED,
# Bidding strategy must be set directly on the campaign.
# Setting a portfolio bidding strategy by resource name is not supported.
# Maximize conversion value is the only strategy supported for smart shopping
# 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 maximize conversion value, see the support article:
# http://support.google.com/google-ads/answer/7684216.
maximizeConversionValue =>
Google::Ads::GoogleAds::V6::Common::MaximizeConversionValue->new(
{targetRoas => 3.5}
),
# Set the budget.
campaignBudget => $budget_resource_name
});
# Create a campaign operation.
my $campaign_operation =
Google::Ads::GoogleAds::V6::Services::CampaignService::CampaignOperation->
new({create => $campaign});
# Add the campaign.
my $campaign_resource_name = $api_client->CampaignService()->mutate({
customerId => $customer_id,
operations => [$campaign_operation]})->{results}[0]{resourceName};
printf "Added a smart shopping campaign with resource name: '%s'.\n",
$campaign_resource_name;
return $campaign_resource_name;
}
# Creates a new ad group in the specified smart shopping campaign.
sub add_smart_shopping_ad_group {
my ($api_client, $customer_id, $campaign_resource_name) = @_;
# Create an ad group.
my $ad_group = Google::Ads::GoogleAds::V6::Resources::AdGroup->new({
name => "Earth to Mars Cruises #" . uniqid(),
campaign => $campaign_resource_name,
# Set the ad group type to SHOPPING_SMART_ADS. This cannot be set to
# other types
type =>
Google::Ads::GoogleAds::V6::Enums::AdGroupTypeEnum::SHOPPING_SMART_ADS,
status => Google::Ads::GoogleAds::V6::Enums::AdGroupStatusEnum::ENABLED
});
# Create an ad group operation.
my $ad_group_operation =
Google::Ads::GoogleAds::V6::Services::AdGroupService::AdGroupOperation->
new({create => $ad_group});
# Add the ad group.
my $ad_group_resource_name = $api_client->AdGroupService()->mutate({
customerId => $customer_id,
operations => [$ad_group_operation]})->{results}[0]{resourceName};
printf "Added a smart shopping ad group with resource name: '%s'.\n",
$ad_group_resource_name;
return $ad_group_resource_name;
}
# Creates a new ad group ad in the specified smart hopping ad group.
sub add_smart_shopping_ad_group_ad {
my ($api_client, $customer_id, $ad_group_resource_name) = @_;
# Create an ad group ad and set a shopping smart ad to it.
my $ad_group_ad = Google::Ads::GoogleAds::V6::Resources::AdGroupAd->new({
# Set the ad group.
adGroup => $ad_group_resource_name,
# Set a new smart shopping ad.
ad => Google::Ads::GoogleAds::V6::Resources::Ad->new({
shoppingSmartAd =>
Google::Ads::GoogleAds::V6::Common::ShoppingSmartAdInfo->new()}
),
status => Google::Ads::GoogleAds::V6::Enums::AdGroupAdStatusEnum::PAUSED
});
# Create an ad group ad operation.
my $ad_group_ad_operation =
Google::Ads::GoogleAds::V6::Services::AdGroupAdService::AdGroupAdOperation
->new({create => $ad_group_ad});
# Add the ad group ad.
my $ad_group_ad_resource_name = $api_client->AdGroupAdService()->mutate({
customerId => $customer_id,
operations => [$ad_group_ad_operation]})->{results}[0]{resourceName};
printf "Added a smart shopping ad group ad with resource name: '%s'.\n",
$ad_group_ad_resource_name;
return $ad_group_ad_resource_name;
}
# Creates a new Shopping listing group for the specified ad group. This is known
# as a "product group" in the Google Ads user interface. The listing group will be
# added to the ad group using an "ad group criterion". For more information on
# listing groups see the Google Ads API Shopping guide:
# https://developers.google.com/google-ads/api/docs/shopping-ads/overview.
sub add_shopping_listing_group {
my ($api_client, $customer_id, $ad_group_resource_name) = @_;
# Creates a new ad group criterion. This will contain a listing group.
# This will be the listing group for 'All products' and will contain a
# single root node.
my $ad_group_criterion =
Google::Ads::GoogleAds::V6::Resources::AdGroupCriterion->new({
# Set the ad group.
adGroup => $ad_group_resource_name,
# Create a new listing group. This will be the top-level "root" node.
# Set the type of the listing group to be a biddable unit.
listingGroup => Google::Ads::GoogleAds::V6::Common::ListingGroupInfo->new(
{
type => UNIT
}
),
status =>
Google::Ads::GoogleAds::V6::Enums::AdGroupCriterionStatusEnum::ENABLED
});
# Create an ad group criterion operation.
my $ad_group_criterion_operation =
Google::Ads::GoogleAds::V6::Services::AdGroupCriterionService::AdGroupCriterionOperation
->new({create => $ad_group_criterion});
# Add the listing group criterion.
my $ad_group_criterion_resource_name =
$api_client->AdGroupCriterionService()->mutate({
customerId => $customer_id,
operations => [$ad_group_criterion_operation]}
)->{results}[0]{resourceName};
printf "Added an ad group criterion containing a listing group " .
"with resource name: '%s'.\n", $ad_group_criterion_resource_name;
return $ad_group_criterion_resource_name;
}
# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
return 1;
}
# Get Google Ads Client, credentials will be read from ~/googleads.properties.
my $api_client = Google::Ads::GoogleAds::Client->new();
# By default examples are set to die on any server returned fault.
$api_client->set_die_on_faults(1);
# Parameters passed on the command line will override any parameters set in code.
GetOptions(
"customer_id=s" => \$customer_id,
"merchant_center_account_id=i" => \$merchant_center_account_id,
"create_default_listing_group=s" => \$create_default_listing_group
);
# 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);
# Call the example.
add_shopping_smart_ad($api_client, $customer_id =~ s/-//gr,
$merchant_center_account_id, $create_default_listing_group);
=pod
=head1 NAME
add_shopping_smart_ad
=head1 DESCRIPTION
This example creates a smart shopping campaign, a smart shopping ad group, a smart shopping
ad group ad and a listing group for "All products".
Prerequisite:
- 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/adwords/shopping/full-automation/articles/t15.
- 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.
=head1 SYNOPSIS
add_shopping_smart_ad.pl [options]
-help Show the help message.
-customer_id The Google Ads customer ID.
-merchant_center_account_id The Merchant Center account ID.
-create_default_listing_group [optional] Create default listing group.
=cut
