Google Ads API is returning to beta status. Please read our blog post for more details.

Add Shopping Smart Ad

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.v3.common.ListingGroupInfo;
import com.google.ads.googleads.v3.common.MaximizeConversionValue;
import com.google.ads.googleads.v3.common.ShoppingSmartAdInfo;
import com.google.ads.googleads.v3.enums.AdGroupCriterionStatusEnum.AdGroupCriterionStatus;
import com.google.ads.googleads.v3.enums.AdGroupStatusEnum.AdGroupStatus;
import com.google.ads.googleads.v3.enums.AdGroupTypeEnum.AdGroupType;
import com.google.ads.googleads.v3.enums.AdvertisingChannelSubTypeEnum.AdvertisingChannelSubType;
import com.google.ads.googleads.v3.enums.AdvertisingChannelTypeEnum.AdvertisingChannelType;
import com.google.ads.googleads.v3.enums.BudgetDeliveryMethodEnum.BudgetDeliveryMethod;
import com.google.ads.googleads.v3.enums.CampaignStatusEnum.CampaignStatus;
import com.google.ads.googleads.v3.enums.ListingGroupTypeEnum.ListingGroupType;
import com.google.ads.googleads.v3.errors.GoogleAdsError;
import com.google.ads.googleads.v3.errors.GoogleAdsException;
import com.google.ads.googleads.v3.resources.Ad;
import com.google.ads.googleads.v3.resources.AdGroup;
import com.google.ads.googleads.v3.resources.AdGroupAd;
import com.google.ads.googleads.v3.resources.AdGroupCriterion;
import com.google.ads.googleads.v3.resources.Campaign;
import com.google.ads.googleads.v3.resources.Campaign.ShoppingSetting;
import com.google.ads.googleads.v3.resources.CampaignBudget;
import com.google.ads.googleads.v3.services.AdGroupAdOperation;
import com.google.ads.googleads.v3.services.AdGroupAdServiceClient;
import com.google.ads.googleads.v3.services.AdGroupCriterionOperation;
import com.google.ads.googleads.v3.services.AdGroupCriterionServiceClient;
import com.google.ads.googleads.v3.services.AdGroupOperation;
import com.google.ads.googleads.v3.services.AdGroupServiceClient;
import com.google.ads.googleads.v3.services.CampaignBudgetOperation;
import com.google.ads.googleads.v3.services.CampaignBudgetServiceClient;
import com.google.ads.googleads.v3.services.CampaignOperation;
import com.google.ads.googleads.v3.services.CampaignServiceClient;
import com.google.ads.googleads.v3.services.MutateAdGroupAdResult;
import com.google.ads.googleads.v3.services.MutateAdGroupCriterionResult;
import com.google.ads.googleads.v3.services.MutateAdGroupResult;
import com.google.ads.googleads.v3.services.MutateCampaignBudgetsResponse;
import com.google.ads.googleads.v3.services.MutateCampaignResult;
import com.google.common.collect.ImmutableList;
import com.google.protobuf.BoolValue;
import com.google.protobuf.DoubleValue;
import com.google.protobuf.Int64Value;
import com.google.protobuf.StringValue;
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;
    try {
      googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
    } catch (FileNotFoundException fnfe) {
      System.err.printf(
          "Failed to load GoogleAdsClient configuration from file. Exception: %s%n", fnfe);
      return;
    } catch (IOException ioe) {
      System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
      return;
    }

    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);
      }
    }
  }

  /**
   * 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(StringValue.of("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(Int64Value.of(5_000_000L))
            // Budgets for Smart Shopping campaigns cannot be shared.
            .setExplicitlyShared(BoolValue.of(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(StringValue.of("US"))
            .setMerchantId(Int64Value.of(merchantCenterAccountId))
            .build();

    // Creates the campaign.
    Campaign campaign =
        Campaign.newBuilder()
            .setName(StringValue.of("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(DoubleValue.of(3.5)).build())
            // Sets the budget.
            .setCampaignBudget(StringValue.of(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(StringValue.of("Earth to Mars Cruises #" + System.currentTimeMillis()))
            .setCampaign(StringValue.of(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(StringValue.of(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(StringValue.of(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.V3.Errors;
using Google.Ads.GoogleAds.V3.Common;
using Google.Ads.GoogleAds.V3.Resources;
using Google.Ads.GoogleAds.V3.Services;

using System;
using static Google.Ads.GoogleAds.V3.Enums.AdGroupAdStatusEnum.Types;
using static Google.Ads.GoogleAds.V3.Enums.AdGroupCriterionStatusEnum.Types;
using static Google.Ads.GoogleAds.V3.Enums.AdGroupStatusEnum.Types;
using static Google.Ads.GoogleAds.V3.Enums.AdGroupTypeEnum.Types;
using static Google.Ads.GoogleAds.V3.Enums.AdvertisingChannelTypeEnum.Types;
using static Google.Ads.GoogleAds.V3.Enums.BudgetDeliveryMethodEnum.Types;
using static Google.Ads.GoogleAds.V3.Enums.CampaignStatusEnum.Types;
using static Google.Ads.GoogleAds.V3.Enums.ListingGroupTypeEnum.Types;
using static Google.Ads.GoogleAds.V3.Resources.Campaign.Types;
using static Google.Ads.GoogleAds.V3.Enums.AdvertisingChannelSubTypeEnum.Types;

namespace Google.Ads.GoogleAds.Examples.V3
{
    /// <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
        {
            get
            {
                return "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\".\n 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.\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.V3.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.V3.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.V3.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.V3.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.V3.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\V3\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V3\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V3\GoogleAdsException;
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\V3\Common\ListingGroupInfo;
use Google\Ads\GoogleAds\V3\Common\MaximizeConversionValue;
use Google\Ads\GoogleAds\V3\Common\ShoppingSmartAdInfo;
use Google\Ads\GoogleAds\V3\Enums\AdGroupAdStatusEnum\AdGroupAdStatus;
use Google\Ads\GoogleAds\V3\Enums\AdGroupStatusEnum\AdGroupStatus;
use Google\Ads\GoogleAds\V3\Enums\AdGroupTypeEnum\AdGroupType;
use Google\Ads\GoogleAds\V3\Enums\AdvertisingChannelSubTypeEnum\AdvertisingChannelSubType;
use Google\Ads\GoogleAds\V3\Enums\AdvertisingChannelTypeEnum\AdvertisingChannelType;
use Google\Ads\GoogleAds\V3\Enums\BudgetDeliveryMethodEnum\BudgetDeliveryMethod;
use Google\Ads\GoogleAds\V3\Enums\CampaignStatusEnum\CampaignStatus;
use Google\Ads\GoogleAds\V3\Enums\ListingGroupTypeEnum\ListingGroupType;
use Google\Ads\GoogleAds\V3\Errors\GoogleAdsError;
use Google\Ads\GoogleAds\V3\Resources\Ad;
use Google\Ads\GoogleAds\V3\Resources\AdGroup;
use Google\Ads\GoogleAds\V3\Resources\AdGroupAd;
use Google\Ads\GoogleAds\V3\Resources\AdGroupCriterion;
use Google\Ads\GoogleAds\V3\Resources\Campaign;
use Google\Ads\GoogleAds\V3\Resources\Campaign\ShoppingSetting;
use Google\Ads\GoogleAds\V3\Resources\CampaignBudget;
use Google\Ads\GoogleAds\V3\Services\AdGroupAdOperation;
use Google\Ads\GoogleAds\V3\Services\AdGroupCriterionOperation;
use Google\Ads\GoogleAds\V3\Services\AdGroupOperation;
use Google\Ads\GoogleAds\V3\Services\CampaignBudgetOperation;
use Google\Ads\GoogleAds\V3\Services\CampaignOperation;
use Google\ApiCore\ApiException;
use Google\Protobuf\BoolValue;
use Google\Protobuf\DoubleValue;
use Google\Protobuf\Int64Value;
use Google\Protobuf\StringValue;

/**
 * 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' => new StringValue(['value' => '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' => new Int64Value(['value' => 50000000]),
            // Budgets for Smart Shopping campaigns cannot be shared.
            'explicitly_shared' => new BoolValue(['value' => 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' => new StringValue(['value' => 'US']),
            'merchant_id' => new Int64Value(['value' => $merchantCenterAccountId])
        ]);

        // Creates the campaign.
        $campaign = new Campaign([
            'name' => new StringValue(['value' => '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' => new DoubleValue(['value' => 3.5])
            ]),
            // Sets the budget.
            'campaign_budget' => new StringValue(['value' => $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' => new StringValue(['value' => 'Earth to Mars Cruise #' . uniqid()]),
            'campaign' => new StringValue(['value' => $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' => new StringValue(['value' => $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' => new StringValue(['value' => $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();
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::V3::Resources::CampaignBudget;
use Google::Ads::GoogleAds::V3::Resources::Campaign;
use Google::Ads::GoogleAds::V3::Resources::ShoppingSetting;
use Google::Ads::GoogleAds::V3::Resources::AdGroup;
use Google::Ads::GoogleAds::V3::Resources::AdGroupAd;
use Google::Ads::GoogleAds::V3::Resources::Ad;
use Google::Ads::GoogleAds::V3::Resources::AdGroupCriterion;
use Google::Ads::GoogleAds::V3::Common::MaximizeConversionValue;
use Google::Ads::GoogleAds::V3::Common::ShoppingSmartAdInfo;
use Google::Ads::GoogleAds::V3::Common::ListingGroupInfo;
use Google::Ads::GoogleAds::V3::Enums::BudgetDeliveryMethodEnum qw(STANDARD);
use Google::Ads::GoogleAds::V3::Enums::AdvertisingChannelTypeEnum qw(SHOPPING);
use Google::Ads::GoogleAds::V3::Enums::AdvertisingChannelSubTypeEnum
  qw(SHOPPING_SMART_ADS);
use Google::Ads::GoogleAds::V3::Enums::AdGroupTypeEnum;
use Google::Ads::GoogleAds::V3::Enums::CampaignStatusEnum;
use Google::Ads::GoogleAds::V3::Enums::AdGroupStatusEnum;
use Google::Ads::GoogleAds::V3::Enums::AdGroupAdStatusEnum;
use Google::Ads::GoogleAds::V3::Enums::ListingGroupTypeEnum qw(UNIT);
use Google::Ads::GoogleAds::V3::Enums::AdGroupCriterionStatusEnum;
use
  Google::Ads::GoogleAds::V3::Services::CampaignBudgetService::CampaignBudgetOperation;
use Google::Ads::GoogleAds::V3::Services::CampaignService::CampaignOperation;
use Google::Ads::GoogleAds::V3::Services::AdGroupService::AdGroupOperation;
use Google::Ads::GoogleAds::V3::Services::AdGroupAdService::AdGroupAdOperation;
use
  Google::Ads::GoogleAds::V3::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::V3::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::V3::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::V3::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::V3::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::V3::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::V3::Common::MaximizeConversionValue->new(
        {targetRoas => 3.5}
        ),
      # Set the budget.
      campaignBudget => $budget_resource_name
    });

  # Create a campaign operation.
  my $campaign_operation =
    Google::Ads::GoogleAds::V3::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::V3::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::V3::Enums::AdGroupTypeEnum::SHOPPING_SMART_ADS,
    status => Google::Ads::GoogleAds::V3::Enums::AdGroupStatusEnum::ENABLED
  });

  # Create an ad group operation.
  my $ad_group_operation =
    Google::Ads::GoogleAds::V3::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::V3::Resources::AdGroupAd->new({
      # Set the ad group.
      adGroup => $ad_group_resource_name,
      # Set a new smart shopping ad.
      ad => Google::Ads::GoogleAds::V3::Resources::Ad->new({
          shoppingSmartAd =>
            Google::Ads::GoogleAds::V3::Common::ShoppingSmartAdInfo->new()}
      ),
      status => Google::Ads::GoogleAds::V3::Enums::AdGroupAdStatusEnum::PAUSED
    });

  # Create an ad group ad operation.
  my $ad_group_ad_operation =
    Google::Ads::GoogleAds::V3::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::V3::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::V3::Common::ListingGroupInfo->new(
        {
          type => UNIT
        }
      ),
      status =>
        Google::Ads::GoogleAds::V3::Enums::AdGroupCriterionStatusEnum::ENABLED
    });

  # Create an ad group criterion operation.
  my $ad_group_criterion_operation =
    Google::Ads::GoogleAds::V3::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({version => "V3"});

# 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