Multi-Asset Responsive Display Ads

Important:

Multi-asset responsive display ads are in beta and may not be available to all Google Ads advertisers.

Per the Google Ads Terms & Conditions for features in beta, you may not disclose any non-public information.

MultiAssetResponsiveDisplayAd is an enhanced form of ResponsiveDisplayAd. Use this ad format to promote products on the Google Display Network.

Similar to ResponsiveDisplayAd, the MultiAssetResponsiveDisplayAd also contains the following elements:

• short headline(s)
• long headline
• description(s)
• business name
• marketing, and square marketing image(s)
• call-to-action text (optional)
• logo (optional), landscape logo (optional)
• promotion text (optional)
• price prefix (optional)
• main, accent, and flexible color support (optional).
• format setting.

The main difference between this ad format and ResponsiveDisplayAd is that, as the name indicates, MultiAssetResponsiveDisplayAd is a multi-asset ad format. This means that you can specify multiple values (called Assets) for short headlines, descriptions, and various image formats. AdWords uses machine learning models to optimize for every ad impression and select the best asset and rendering combinations for each request.

Example

You create responsive ads in two steps:

1. Create ImageAssets by uploading images (marketing images, square marketing images, optional logos, and optional landscape logos) using the AssetService.mutate() method. Keep track of the Asset ID that is returned. You'll need that later when adding your ad. Once an image asset is uploaded through the asset service, it can be reused for multiple ads later on.

2. Create a MultiAssetResponsiveDisplayAd using AdGroupAdService. For the marketingImages, logoImages, landscapeLogoImages, and squareMarketingImages, be sure to reference the Asset IDs that were returned in Step 1. TextAsset fields such as descriptions and longHeadLine can be specified directly in the ad field, and needn't be created using AssetService.mutate().

Note: Both text and image assets are deduplicated within a given customer account, so if you use the same text or images in two different ads, the two ads will share the corresponding assets. Text assets are deduped by text comparison, and image assets are deduped by exact byte comparison.

Note: Assets are reviewed individually for policy violations, which allows greater flexibility if only some of the assets are disapproved.

The following code snippet shows how to create a responsive display ad. Image assets are uploaded as needed.

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 adwords.axis.v201809.advancedoperations;

import static com.google.api.ads.common.lib.utils.Builder.DEFAULT_CONFIGURATION_FILENAME;

import com.beust.jcommander.Parameter;
import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201809.cm.AdGroupAd;
import com.google.api.ads.adwords.axis.v201809.cm.AdGroupAdOperation;
import com.google.api.ads.adwords.axis.v201809.cm.AdGroupAdReturnValue;
import com.google.api.ads.adwords.axis.v201809.cm.AdGroupAdServiceInterface;
import com.google.api.ads.adwords.axis.v201809.cm.AdGroupAdStatus;
import com.google.api.ads.adwords.axis.v201809.cm.ApiError;
import com.google.api.ads.adwords.axis.v201809.cm.ApiException;
import com.google.api.ads.adwords.axis.v201809.cm.AssetLink;
import com.google.api.ads.adwords.axis.v201809.cm.AssetOperation;
import com.google.api.ads.adwords.axis.v201809.cm.AssetServiceInterface;
import com.google.api.ads.adwords.axis.v201809.cm.DisplayAdFormatSetting;
import com.google.api.ads.adwords.axis.v201809.cm.ImageAsset;
import com.google.api.ads.adwords.axis.v201809.cm.MultiAssetResponsiveDisplayAd;
import com.google.api.ads.adwords.axis.v201809.cm.Operator;
import com.google.api.ads.adwords.axis.v201809.cm.TextAsset;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.adwords.lib.utils.examples.ArgumentNames;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.ads.common.lib.conf.ConfigurationLoadException;
import com.google.api.ads.common.lib.exception.OAuthException;
import com.google.api.ads.common.lib.exception.ValidationException;
import com.google.api.ads.common.lib.utils.examples.CodeSampleParams;
import com.google.api.client.auth.oauth2.Credential;
import java.io.IOException;
import java.rmi.RemoteException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

/**
 * This example adds a responsive display ad (MultiAssetResponsiveDisplayAd) to an ad group. Image
 * assets are uploaded using AssetService. To get ad groups, run GetAdGroups.java.
 *
 * <p>Credentials and properties in {@code fromFile()} are pulled from the "ads.properties" file.
 * See README for more info.
 */
public class AddMultiAssetResponsiveDisplayAd {

  private static class AddMultiAssetResponsiveDisplayAdParams extends CodeSampleParams {
    @Parameter(names = ArgumentNames.AD_GROUP_ID, required = true)
    private Long adGroupId;
  }

  public static void main(String[] args) {
    AdWordsSession session;
    try {
      // Generate a refreshable OAuth2 credential.
      Credential oAuth2Credential =
          new OfflineCredentials.Builder()
              .forApi(Api.ADWORDS)
              .fromFile()
              .build()
              .generateCredential();

      // Construct an AdWordsSession.
      session =
          new AdWordsSession.Builder().fromFile().withOAuth2Credential(oAuth2Credential).build();
    } catch (ConfigurationLoadException cle) {
      System.err.printf(
          "Failed to load configuration from the %s file. Exception: %s%n",
          DEFAULT_CONFIGURATION_FILENAME, cle);
      return;
    } catch (ValidationException ve) {
      System.err.printf(
          "Invalid configuration in the %s file. Exception: %s%n",
          DEFAULT_CONFIGURATION_FILENAME, ve);
      return;
    } catch (OAuthException oe) {
      System.err.printf(
          "Failed to create OAuth credentials. Check OAuth settings in the %s file. "
              + "Exception: %s%n",
          DEFAULT_CONFIGURATION_FILENAME, oe);
      return;
    }

    AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

    AddMultiAssetResponsiveDisplayAdParams params = new AddMultiAssetResponsiveDisplayAdParams();
    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.adGroupId = Long.parseLong("INSERT_AD_GROUP_ID_HERE");
    }

    try {
      runExample(adWordsServices, session, params.adGroupId);
    } catch (ApiException apiException) {
      // ApiException is the base class for most exceptions thrown by an API request. Instances
      // of this exception have a message and a collection of ApiErrors that indicate the
      // type and underlying cause of the exception. Every exception object in the adwords.axis
      // packages will return a meaningful value from toString
      //
      // ApiException extends RemoteException, so this catch block must appear before the
      // catch block for RemoteException.
      System.err.println("Request failed due to ApiException. Underlying ApiErrors:");
      if (apiException.getErrors() != null) {
        int i = 0;
        for (ApiError apiError : apiException.getErrors()) {
          System.err.printf("  Error %d: %s%n", i++, apiError);
        }
      }
    } catch (RemoteException re) {
      System.err.printf("Request failed unexpectedly due to RemoteException: %s%n", re);
    } catch (IOException ioe) {
      System.err.printf("Example failed unexpectedly due to IOException: %s%n", ioe);
    }
  }

  /**
   * Runs the example.
   *
   * @param adWordsServices the services factory.
   * @param session the session.
   * @param adGroupId the ID of the ad group where the ad will be created.
   * @throws ApiException if the API request failed with one or more service errors.
   * @throws RemoteException if the API request failed due to other errors.
   * @throws IOException if unable to retrieve an image from a URL.
   */
  public static void runExample(
      AdWordsServicesInterface adWordsServices, AdWordsSession session, long adGroupId)
      throws IOException {
    // Get the AdGroupAdService.
    AdGroupAdServiceInterface adGroupAdService =
        adWordsServices.get(session, AdGroupAdServiceInterface.class);

    List<AdGroupAdOperation> operations = new ArrayList<>();

    MultiAssetResponsiveDisplayAd ad = new MultiAssetResponsiveDisplayAd();
    List<AssetLink> headlines = new ArrayList<>();
    headlines.add(createAssetLinkForText("Travel to Mars"));
    headlines.add(createAssetLinkForText("Travel to Jupiter"));
    headlines.add(createAssetLinkForText("Travel to Pluto"));
    headlines.add(createAssetLinkForText("Experience the Stars"));
    ad.setHeadlines(headlines.toArray(new AssetLink[0]));

    List<AssetLink> descriptions = new ArrayList<>();
    descriptions.add(createAssetLinkForText("Visit the planet in a luxury spaceship."));
    descriptions.add(createAssetLinkForText("See the planet in style."));
    ad.setDescriptions(descriptions.toArray(new AssetLink[0]));

    ad.setBusinessName("Galactic Luxury Cruises");
    ad.setLongHeadline(createAssetLinkForText("Visit the planet in a luxury spaceship."));

    // This ad format does not allow the creation of an image asset by setting the asset.imageData
    // field. An image asset must first be created using the AssetService, and asset.assetId must be
    // populated when creating the ad.
    ad.setMarketingImages(
        new AssetLink[] {
          createAssetLinkForImageAsset(
              uploadImageAsset(adWordsServices, session, "https://goo.gl/3b9Wfh"))
        });
    ad.setSquareMarketingImages(
        new AssetLink[] {
          createAssetLinkForImageAsset(
              uploadImageAsset(adWordsServices, session, "https://goo.gl/mtt54n"))
        });

    ad.setFinalUrls(new String[] {"http://www.example.com"});

    // Optional: set call to action text.
    ad.setCallToActionText("Shop Now");

    // Set color settings using hexadecimal values. Set allowFlexibleColor to false if you want
    // your ads to render by always using your colors strictly.
    ad.setMainColor("#0000ff");
    ad.setAccentColor("#ffff00");
    ad.setAllowFlexibleColor(false);

    // Set the format setting that the ad will be served in.
    ad.setFormatSetting(DisplayAdFormatSetting.NON_NATIVE);

    // Optional: Set dynamic display ad settings, composed of landscape logo image, promotion text,
    // and price prefix.
    ad.setDynamicSettingsPricePrefix("as low as");
    ad.setDynamicSettingsPromoText("Free shipping!");
    ad.setLogoImages(
        new AssetLink[] {
          createAssetLinkForImageAsset(
              uploadImageAsset(adWordsServices, session, "https://goo.gl/mtt54n"))
        });

    // Create ad group ad.
    AdGroupAd adGroupAd = new AdGroupAd();
    adGroupAd.setAdGroupId(adGroupId);
    adGroupAd.setAd(ad);

    // Optional: set the status.
    adGroupAd.setStatus(AdGroupAdStatus.PAUSED);

    // Create the operation.
    AdGroupAdOperation adGroupAdOperation = new AdGroupAdOperation();
    adGroupAdOperation.setOperand(adGroupAd);
    adGroupAdOperation.setOperator(Operator.ADD);

    operations.add(adGroupAdOperation);

    // Add ad.
    AdGroupAdReturnValue result =
        adGroupAdService.mutate(operations.toArray(new AdGroupAdOperation[operations.size()]));

    Arrays.stream(result.getValue())
        .map(adGroupAdResult -> (MultiAssetResponsiveDisplayAd) adGroupAdResult.getAd())
        .forEach(
            newAd ->
                System.out.printf(
                    "New responsive display ad with ID %d and long headline '%s' was added.%n",
                    newAd.getId(),
                    ((TextAsset) newAd.getLongHeadline().getAsset()).getAssetText()));
  }

  /**
   * Creates an {@link AssetLink} containing a {@link TextAsset} with the specified string.
   *
   * @param text the text for the text asset.
   * @return a new {@link AssetLink}
   */
  private static AssetLink createAssetLinkForText(String text) {
    AssetLink assetLink = new AssetLink();
    TextAsset textAsset = new TextAsset();
    textAsset.setAssetText(text);
    assetLink.setAsset(textAsset);
    return assetLink;
  }

  /**
   * Creates an {@link AssetLink} containing a {@link ImageAsset} with the specified asset ID.
   *
   * @param assetId ID of the image asset.
   * @return a new {@link AssetLink}
   */
  private static AssetLink createAssetLinkForImageAsset(long assetId) {
    AssetLink assetLink = new AssetLink();
    ImageAsset imageAsset = new ImageAsset();
    imageAsset.setAssetId(assetId);
    assetLink.setAsset(imageAsset);
    return assetLink;
  }

  /**
   * Creates and uploads an {@link ImageAsset} for the specified URL.
   *
   * @return the ID of the {@link ImageAsset}.
   * @throws IOException if unable to read the image from the specified URL.
   */
  private static long uploadImageAsset(
      AdWordsServicesInterface adWordsServices, AdWordsSession session, String url)
      throws IOException {

    AssetServiceInterface assetService = adWordsServices.get(session, AssetServiceInterface.class);

    // Create the image asset.
    ImageAsset image = new ImageAsset();
    // Optional: Provide a unique friendly name to identify your asset. If you specify the assetName
    // field, then both the asset name and the image being uploaded should be unique, and should not
    // match another ACTIVE asset in this customer account.
    // image.setAssetName("Image asset #" + System.currentTimeMillis());
    image.setImageData(com.google.api.ads.common.lib.utils.Media.getMediaDataFromUrl(url));

    // Create the operation.
    AssetOperation operation = new AssetOperation();
    operation.setOperator(Operator.ADD);
    operation.setOperand(image);

    // Create the asset and return the ID.
    return assetService.mutate(new AssetOperation[] {operation}).getValue(0).getAssetId();
  }
}

C#

// 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
//
//     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.Api.Ads.AdWords.Lib;
using Google.Api.Ads.AdWords.v201809;
using Google.Api.Ads.Common.Util;

using System;

namespace Google.Api.Ads.AdWords.Examples.CSharp.v201809
{
    /// <summary>
    /// This code example adds a responsive display ad (MultiAssetResponsiveDisplayAd)
    /// to an ad group. Image assets are uploaded using AssetService. To get ad groups,
    /// run GetAdGroups.cs.
    /// </summary>
    public class AddMultiAssetResponsiveDisplayAd : 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)
        {
            AddMultiAssetResponsiveDisplayAd codeExample = new AddMultiAssetResponsiveDisplayAd();
            Console.WriteLine(codeExample.Description);
            try
            {
                long adGroupId = long.Parse("INSERT_ADGROUP_ID_HERE");
                codeExample.Run(new AdWordsUser(), adGroupId);
            }
            catch (Exception e)
            {
                Console.WriteLine("An exception occurred while running this code example. {0}",
                    ExampleUtilities.FormatException(e));
            }
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description
        {
            get
            {
                return "This code example adds a responsive display ad " +
                    "(MultiAssetResponsiveDisplayAd) to an ad group. Image assets are uploaded " +
                    "using AssetService. To get ad groups, run GetAdGroups.cs.";
            }
        }

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="user">The AdWords user.</param>
        /// <param name="adGroupId">Id of the ad group to which ads are added.
        /// </param>
        public void Run(AdWordsUser user, long adGroupId)
        {
            using (AdGroupAdService adGroupAdService =
                (AdGroupAdService) user.GetService(AdWordsService.v201809.AdGroupAdService))
            {
                try
                {
                    // Create the ad.
                    MultiAssetResponsiveDisplayAd ad = new MultiAssetResponsiveDisplayAd()
                    {
                        headlines = new AssetLink[]
                        {
                            new AssetLink()
                            {
                                // Text assets can be specified directly in the asset field when
                                // creating the ad.
                                asset = new TextAsset()
                                {
                                    assetText = "Travel to Mars",
                                },
                            },
                            new AssetLink()
                            {
                                asset = new TextAsset()
                                {
                                    assetText = "Travel to Jupiter",
                                },
                            },
                            new AssetLink()
                            {
                                asset = new TextAsset()
                                {
                                    assetText = "Travel to Pluto",
                                },
                            },
                        },
                        descriptions = new AssetLink[]
                        {
                            new AssetLink()
                            {
                                asset = new TextAsset()
                                {
                                    assetText = "Visit the planet in a luxury spaceship.",
                                },
                            },
                            new AssetLink()
                            {
                                asset = new TextAsset()
                                {
                                    assetText = "See the planet in style.",
                                },
                            },
                        },
                        businessName = "Galactic Luxury Cruises",
                        longHeadline = new AssetLink()
                        {
                            asset = new TextAsset()
                            {
                                assetText = "Visit the planet in a luxury spaceship.",
                            },
                        },

                        // This ad format does not allow the creation of an image asset by setting
                        // the asset.imageData field. An image asset must first be created using the
                        // AssetService, and asset.assetId must be populated when creating the ad.
                        marketingImages = new AssetLink[]
                        {
                            new AssetLink()
                            {
                                asset = new ImageAsset()
                                {
                                    assetId = UploadImageAsset(user, "https://goo.gl/3b9Wfh")
                                },
                            }
                        },
                        squareMarketingImages = new AssetLink[]
                        {
                            new AssetLink()
                            {
                                asset = new ImageAsset()
                                {
                                    assetId = UploadImageAsset(user, "https://goo.gl/mtt54n")
                                },
                            }
                        },
                        finalUrls = new string[]
                        {
                            "http://www.example.com"
                        },

                        // Optional: set call to action text.
                        callToActionText = "Shop Now",

                        // Set color settings using hexadecimal values. Set allowFlexibleColor to
                        // false if you want your ads to render by always using your colors
                        // strictly.
                        mainColor = "#0000ff",
                        accentColor = "#ffff00",
                        allowFlexibleColor = false,

                        // Set the format setting that the ad will be served in.
                        formatSetting = DisplayAdFormatSetting.NON_NATIVE,

                        // Optional: Set dynamic display ad settings, composed of landscape logo
                        // image, promotion text, and price prefix.
                        dynamicSettingsPricePrefix = "as low as",
                        dynamicSettingsPromoText = "Free shipping!",
                        logoImages = new AssetLink[]
                        {
                            new AssetLink()
                            {
                                asset = new ImageAsset()
                                {
                                    assetId = UploadImageAsset(user, "https://goo.gl/mtt54n")
                                },
                            }
                        }
                    };

                    // Create the ad group ad.
                    AdGroupAd adGroupAd = new AdGroupAd()
                    {
                        ad = ad,
                        adGroupId = adGroupId
                    };

                    // Create the operation.
                    AdGroupAdOperation operation = new AdGroupAdOperation()
                    {
                        operand = adGroupAd,
                        @operator = Operator.ADD
                    };

                    // Make the mutate request.
                    AdGroupAdReturnValue result = adGroupAdService.mutate(new AdGroupAdOperation[]
                    {
                        operation
                    });

                    // Display results.
                    if (result != null && result.value != null)
                    {
                        foreach (AdGroupAd newAdGroupAd in result.value)
                        {
                            MultiAssetResponsiveDisplayAd newAd =
                                newAdGroupAd.ad as MultiAssetResponsiveDisplayAd;
                            Console.WriteLine(
                                "Responsive display ad with ID '{0}' and long headline '{1}'" +
                                " was added.", newAd.id,
                                (newAd.longHeadline.asset as TextAsset).assetText);
                        }
                    }
                    else
                    {
                        Console.WriteLine("No responsive display ads were created.");
                    }
                }
                catch (Exception e)
                {
                    throw new System.ApplicationException("Failed to create responsive display ad.",
                        e);
                }
            }
        }

        /// <summary>
        /// Uploads the image from the specified <paramref name="url"/>.
        /// </summary>
        /// <param name="user">The AdWords user.</param>
        /// <param name="url">The image URL.</param>
        /// <returns>ID of the uploaded image.</returns>
        private static long UploadImageAsset(AdWordsUser user, string url)
        {
            using (AssetService assetService =
                (AssetService) user.GetService(AdWordsService.v201809.AssetService))
            {
                // Create the image asset.
                ImageAsset imageAsset = new ImageAsset()
                {
                    // Optional: Provide a unique friendly name to identify your asset. If you
                    // specify the assetName field, then both the asset name and the image being
                    // uploaded should be unique, and should not match another ACTIVE asset in this
                    // customer account.
                    // assetName = "Image asset " + ExampleUtilities.GetRandomString(),
                    imageData = MediaUtilities.GetAssetDataFromUrl(url, user.Config),
                };

                // Create the operation.
                AssetOperation operation = new AssetOperation()
                {
                    @operator = Operator.ADD,
                    operand = imageAsset
                };

                // Create the asset and return the ID.
                return assetService.mutate(new AssetOperation[]
                {
                    operation
                }).value[0].assetId;
            }
        }
    }
}

Python

#!/usr/bin/python
#
# 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.

"""This example adds a responsive display ad to an ad group.

Image assets are uploaded using AssetService. To get ad groups, run
get_ad_groups.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

import google3

from googleads import adwords
import requests


AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE'


def UploadImageAsset(client, url):
  """Uploads the image from the specified url.

  Args:
    client: An AdWordsClient instance.
    url: The image URL.

  Returns:
    The ID of the uploaded image.
  """
  # Initialize appropriate service.
  asset_service = client.GetService('AssetService', version='v201809')

  # Download the image.
  image_request = requests.get(url)

  # Create the image asset.
  image_asset = {
      'xsi_type': 'ImageAsset',
      'imageData': image_request.content,
      # This field is optional, and if provided should be unique.
      # 'assetName': 'Image asset ' + str(uuid.uuid4()),
  }

  # Create the operation.
  operation = {
      'operator': 'ADD',
      'operand': image_asset
  }

  # Create the asset and return the ID.
  result = asset_service.mutate([operation])

  return result['value'][0]['assetId']


def main(client, ad_group_id):
  # Initialize appropriate service.
  ad_group_ad_service = client.GetService('AdGroupAdService', version='v201809')

  # Create the ad.
  multi_asset_responsive_display_ad = {
      'xsi_type': 'MultiAssetResponsiveDisplayAd',
      'headlines': [{
          'asset': {
              'xsi_type': 'TextAsset',
              'assetText': 'Travel to Mars'
          }
      }, {
          'asset': {
              'xsi_type': 'TextAsset',
              'assetText': 'Travel to Jupiter',
          }
      }, {
          'asset': {
              'xsi_type': 'TextAsset',
              'assetText': 'Travel to Pluto'
          }
      }],
      'descriptions': [{
          'asset': {
              'xsi_type': 'TextAsset',
              'assetText': 'Visit the planet in a luxury spaceship.',
          }
      }, {
          'asset': {
              'xsi_type': 'TextAsset',
              'assetText': 'See the planet in style.',
          }
      }],
      'businessName': 'Galactic Luxury Cruises',
      'longHeadline': {
          'asset': {
              'xsi_type': 'TextAsset',
              'assetText': 'Visit the planet in a luxury spaceship.',
          }
      },
      # This ad format does not allow the creation of an image asset by setting
      # the asset.imageData field. An image asset must first be created using
      # the AssetService, and asset.assetId must be populated when creating
      # the ad.
      'marketingImages': [{
          'asset': {
              'xsi_type': 'ImageAsset',
              'assetId': UploadImageAsset(client, 'https://goo.gl/3b9Wfh')
          }
      }],
      'squareMarketingImages': [{
          'asset': {
              'xsi_type': 'ImageAsset',
              'assetId': UploadImageAsset(client, 'https://goo.gl/mtt54n')
          }
      }],
      # Optional values
      'finalUrls': ['http://www.example.com'],
      'callToActionText': 'Shop Now',
      # Set color settings using hexadecimal values. Set allowFlexibleColor to
      # false if you want your ads to render by always using your colors
      # strictly.
      'mainColor': '#0000ff',
      'accentColor': '#ffff00',
      'allowFlexibleColor': False,
      'formatSetting': 'NON_NATIVE',
      # Set dynamic display ad settings, composed of landscape logo image,
      # promotion text, and price prefix.
      'dynamicSettingsPricePrefix': 'as low as',
      'dynamicSettingsPromoText': 'Free shipping!',
      'logoImages': [{
          'asset': {
              'xsi_type': 'ImageAsset',
              'assetId': UploadImageAsset(client, 'https://goo.gl/mtt54n')
          }
      }]
  }

  # Create ad group ad.
  ad_group_ad = {
      'adGroupId': ad_group_id,
      'ad': multi_asset_responsive_display_ad,
      # Optional.
      'status': 'PAUSED'
  }

  # Add ad.
  ads = ad_group_ad_service.mutate([
      {'operator': 'ADD', 'operand': ad_group_ad}
  ])
  # Display results.
  if 'value' in ads:
    for ad in ads['value']:
      print ('Added new responsive display ad ad with ID "%d" '
             'and long headline "%s".'
             % (ad['ad']['id'], ad['ad']['longHeadline']['asset']['assetText']))
  else:
    print 'No ads were added.'


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()
  main(adwords_client, AD_GROUP_ID)

PHP

<?php
/**
 * 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
 *
 *     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.
 */

namespace Google\AdsApi\Examples\AdWords\v201809\AdvancedOperations;

// MOE:begin_strip
require_once 'googleads_googleads_php_lib/autoload.php';

// MOE:end_strip_and_replace require __DIR__ . '/../../../../vendor/autoload.php';

use Google\AdsApi\AdWords\AdWordsServices;
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\v201809\cm\AdGroupAd;
use Google\AdsApi\AdWords\v201809\cm\AdGroupAdOperation;
use Google\AdsApi\AdWords\v201809\cm\AdGroupAdService;
use Google\AdsApi\AdWords\v201809\cm\AssetLink;
use Google\AdsApi\AdWords\v201809\cm\AssetOperation;
use Google\AdsApi\AdWords\v201809\cm\AssetService;
use Google\AdsApi\AdWords\v201809\cm\DisplayAdFormatSetting;
use Google\AdsApi\AdWords\v201809\cm\ImageAsset;
use Google\AdsApi\AdWords\v201809\cm\MultiAssetResponsiveDisplayAd;
use Google\AdsApi\AdWords\v201809\cm\Operator;
use Google\AdsApi\AdWords\v201809\cm\TextAsset;
use Google\AdsApi\Common\OAuth2TokenBuilder;

/**
 * This code example adds a multi-asset responsive display ad
 * (MultiAssetResponsiveDisplayAd) to an ad group. Image assets are uploaded
 * using AssetService. To get ad groups, run GetAdGroups.php.
 */
class AddMultiAssetResponsiveDisplayAd
{

    const AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE';

    public static function runExample(
        AdWordsServices $adWordsServices,
        AdWordsSession $session,
        $adGroupId
    ) {

        $assetService = $adWordsServices->get($session, AssetService::class);
        $adGroupAdService =
            $adWordsServices->get($session, AdGroupAdService::class);

        // Create a multi-asset responsive display ad.
        $multiAssetResponsiveDisplayAd = new MultiAssetResponsiveDisplayAd();
        $headlineTextAsset1 = new TextAsset();
        $headlineTextAsset1->setAssetText('Travel to Mars');
        $headlineTextAsset2 = new TextAsset();
        $headlineTextAsset2->setAssetText('Travel to Jupiter');
        $headlineTextAsset3 = new TextAsset();
        $headlineTextAsset3->setAssetText('Travel to Pluto');
        // Text assets can be specified directly in the asset field when
        // creating the ad.
        $multiAssetResponsiveDisplayAd->setHeadlines([
            new AssetLink($headlineTextAsset1),
            new AssetLink($headlineTextAsset2),
            new AssetLink($headlineTextAsset3)
        ]);

        // Set business name and long headline.
        $multiAssetResponsiveDisplayAd->setBusinessName(
            'Galactic Luxury Cruises'
        );
        $longHeadlineTextAsset = new TextAsset();
        $longHeadlineTextAsset->setAssetText(
            'Visit the planet in a luxury spaceship.'
        );
        $multiAssetResponsiveDisplayAd->setLongHeadline(
            new AssetLink($longHeadlineTextAsset)
        );

        // Set description.
        $descriptionTextAsset1 = new TextAsset();
        $descriptionTextAsset1->setAssetText(
            'Visit the planet in a luxury spaceship.'
        );
        $descriptionTextAsset2 = new TextAsset();
        $descriptionTextAsset2->setAssetText('See the planet in style.');
        $multiAssetResponsiveDisplayAd->setDescriptions([
            new AssetLink($descriptionTextAsset1),
            new AssetLink($descriptionTextAsset2)
        ]);

        // Set a marketing image.
        $marketingImageAsset = new ImageAsset();
        // This ad format does not allow the creation of an image asset by
        // setting the Asset.imageData field. An image asset must first be
        // created using the AssetService, and Asset.assetId must be populated
        // when creating the ad.
        $marketingImageAsset->setAssetId(
            self::uploadImageAsset($assetService, 'https://goo.gl/3b9Wfh')
        );
        $multiAssetResponsiveDisplayAd->setMarketingImages([
            new AssetLink(
                $marketingImageAsset
            )
        ]);

        // Set a square image.
        $squareImageAsset = new ImageAsset();
        $squareImageAsset->setAssetId(
            self::uploadImageAsset($assetService, 'https://goo.gl/mtt54n')
        );
        $multiAssetResponsiveDisplayAd->setSquareMarketingImages([
            new AssetLink(
                $squareImageAsset
            )
        ]);

        $multiAssetResponsiveDisplayAd->setFinalUrls(
            ['http://www.example.com']
        );

        // Optional: Set call to action text.
        $multiAssetResponsiveDisplayAd->setCallToActionText('Shop Now');

        // Optional: Set color settings using hexadecimal values.
        // Set allowFlexibleColor to false if you want your ads to render by
        // always using your colors strictly.
        $multiAssetResponsiveDisplayAd->setMainColor('#0000ff');
        $multiAssetResponsiveDisplayAd->setAccentColor('#ffff00');
        $multiAssetResponsiveDisplayAd->setAllowFlexibleColor(false);

        // Optional: Set the format setting that the ad will be served in.
        $multiAssetResponsiveDisplayAd->setFormatSetting(
            DisplayAdFormatSetting::NON_NATIVE
        );

        // Optional: Set dynamic display ad settings, composed of landscape logo
        // image, promotion text, and price prefix.
        $multiAssetResponsiveDisplayAd->setDynamicSettingsPricePrefix(
            'as low as'
        );
        $multiAssetResponsiveDisplayAd->setDynamicSettingsPromoText(
            'Free shipping!'
        );

        // Set a logo image.
        $logoImageAsset = new ImageAsset();
        $logoImageAsset->setAssetId(
            self::uploadImageAsset($assetService, 'https://goo.gl/mtt54n')
        );
        $multiAssetResponsiveDisplayAd->setLogoImages([
            new AssetLink(
                $logoImageAsset
            )
        ]);

        // Create ad group ad.
        $adGroupAd = new AdGroupAd();
        $adGroupAd->setAdGroupId($adGroupId);
        $adGroupAd->setAd($multiAssetResponsiveDisplayAd);

        // Create ad group ad operation and add it to the list.
        $operation = new AdGroupAdOperation();
        $operation->setOperand($adGroupAd);
        $operation->setOperator(Operator::ADD);

        // Add a multi-asset responsive display ad on the server.
        $result = $adGroupAdService->mutate([$operation]);

        // Print out some information for each created ad.
        foreach ($result->getValue() as $adGroupAd) {
            $ad = $adGroupAd->getAd();
            printf(
                "Responsive display ad with ID %d and long "
                . "headline '%s' was added.%s",
                $ad->getId(),
                $ad->getLongHeadline()->getAsset()->getAssetText(),
                PHP_EOL
            );
        }
    }

    /**
     * Upload an image asset using AssetService and provided URL.
     */
    private static function uploadImageAsset(AssetService $assetService, $url)
    {
        // Creates an image asset and upload it to the server.
        $imageAsset = new ImageAsset();
        // Optional: Provide a unique friendly name to identify your asset. If
        // you specify the assetName field, then both the asset name and the
        // image being uploaded should be unique, and should not match another
        // ACTIVE asset in this customer account.
        // $imageAsset->setAssetName('Image asset #' . uniqid());
        $imageAsset->setImageData(file_get_contents($url));

        // Create an asset operation.
        $operation = new AssetOperation();
        $operation->setOperand($imageAsset);
        $operation->setOperator(Operator::ADD);

        return $assetService->mutate([$operation])->getValue()[0]->getAssetId();
    }

    public static function main()
    {
        // Generate a refreshable OAuth2 credential for authentication.
        $oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();

        // Construct an API session configured from a properties file and the
        // OAuth2 credentials above.
        $session = (new AdWordsSessionBuilder())->fromFile()
            ->withOAuth2Credential($oAuth2Credential)
            ->build();
        self::runExample(
            new AdWordsServices(),
            $session,
            intval(self::AD_GROUP_ID)
        );
    }
}

AddMultiAssetResponsiveDisplayAd::main();

Perl

Ruby

#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright 2018 Google LLC
#
# License:: 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 code example adds a responsive display ad (MultiAssetResponsiveDisplayAd)
# to an ad group. Image assets are uploaded using AssetService. To get
# ad groups, run get_ad_groups.rb.


require 'adwords_api'

def add_multi_asset_responsive_display_ad(ad_group_id)
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
  # when called without parameters.
  adwords = AdwordsApi::Api.new

  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
  # the configuration file or provide your own logger:
  # adwords.logger = Logger.new('adwords_xml.log')

  ad_group_srv = adwords.service(:AdGroupAdService, API_VERSION)

  # Create the ad.
  ad = {
    :xsi_type => 'MultiAssetResponsiveDisplayAd',
    :headlines => [
      {
        # Text assets can be specified directly in the asset field
        # when creating the ad.
        :asset => {
          :xsi_type => 'TextAsset',
          :asset_text => 'Travel to Mars'
        }
      },
      {
        :asset => {
          :xsi_type => 'TextAsset',
          :asset_text => 'Travel to Jupiter'
        }
      },
      {
        :asset => {
          :xsi_type => 'TextAsset',
          :asset_text => 'Travel to Pluto'
        }
      }
    ],
    :descriptions => [
      {
        :asset => {
          :xsi_type => 'TextAsset',
          :asset_text => 'Visit the planet in a luxury spaceship.'
        }
      },
      {
        :asset => {
          :xsi_type => 'TextAsset',
          :asset_text => 'See the planet in style.'
        }
      }
    ],
    :business_name => 'Galactic Luxury Cruises',
    :long_headline => {
      :asset => {
        :xsi_type => 'TextAsset',
        :asset_text => 'Visit the planet in a luxury spaceship.'
      }
    },
    # This ad format does not allow the creation of an image asset by setting
    # the asset.imageData field. An image asset must first be created using the
    # AssetService, and asset.assetId must be populated when creating the ad.
    :marketing_images => [
      {
        :asset => {
          :xsi_type => 'ImageAsset',
          :asset_id => upload_image_asset('https://goo.gl/3b9Wfh')
        }
      }
    ],
    :square_marketing_images => [
      {
        :asset => {
          :xsi_type => 'ImageAsset',
          :asset_id => upload_image_asset('https://goo.gl/mtt54n')
        }
      }
    ],
    :final_urls => [
      'http://www.example.com'
    ],
    :call_to_action_text => 'Shop Now',
    :main_color => '#0000ff',
    :accent_color => '#ffff00',
    :allow_flexible_color => false,
    :format_setting => 'NON_NATIVE',
    :dynamic_settings_price_prefix => 'as low as',
    :dynamic_settings_promo_text => 'Free shipping!',
    :logo_images => [
      {
        :asset => {
          :xsi_type => 'ImageAsset',
          :asset_id => upload_image_asset('https://goo.gl/mtt54n')
        }
      }
    ],
  }

  # Create the ad group ad.
  ad_group_ad = {
    :xsi_type => 'AdGroupAd',
    :ad => ad,
    :ad_group_id => ad_group_id
  };

  # Create the operation.
  ad_group_operation = {:operator => 'ADD', :operand => ad_group_ad}

  begin
    # Make the mutate request.
    result = ad_group_srv.mutate([ad_group_operation])

    # Display the results
    if result[:value].length > 0
      result[:value].each do |entry|
        new_ad = entry[:ad]
        puts ('Responsive display ad v2 with ID "%s" ' +
            'and short headline "%s" was added.') %
            [new_ad[:id], new_ad[:long_headline][:asset][:asset_text]]
      end
    else
      puts 'No responsive display ad v2 were created.'
    end
  rescue Exception => e
    puts 'Failed to create responsive display ad v2.'
  end
end

def upload_image_asset(image_url, adwords_api_instance)

  asset_srv = adwords_api_instance.service(:AssetService, API_VERSION)

  # The image needs to be in a BASE64 encoded form
  image_data = AdsCommon::Http.get(image_url, adwords_api_instance.config)
  image_data_base64 = Base64.encode64(image_data)

  # Create the image asset
  image_asset = {
    :xsi_type => 'ImageAsset',
    # Optional: Provide a unique friendly name to identify your asset. If you
    # specify the assetName field, then both the asset name and the image being
    # uploaded should be unique, and should not match another ACTIVE asset in
    # this customer account.
    # :asset_name => 'Image asset %s' % (Time.new.to_f * 1000).to_i,
    :image_data => image_data_base64
  }

  # Create the operation.
  asset_operation = {:operator => 'ADD', :operand => image_asset}

  # Make the mutate request.
  result = asset_srv.mutate([asset_operation])

  # return the generated Id
  result[:value].first[:asset_id]
end

if __FILE__ == $0
  API_VERSION = :v201809

  begin
    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i

    add_multi_asset_responsive_display_ad(ad_group_id)

  # Authorization error.
  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
        "to retrieve and store OAuth2 tokens."
    puts "See this wiki page for more details:\n\n  " +
        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'

  # HTTP errors.
  rescue AdsCommon::Errors::HttpError => e
    puts "HTTP Error: %s" % e

  # API errors.
  rescue AdwordsApi::Errors::ApiException => e
    puts "Message: %s" % e.message
    puts 'Errors:'
    e.errors.each_with_index do |error, index|
      puts "\tError [%d]:" % (index + 1)
      error.each do |field, value|
        puts "\t\t%s: %s" % [field, value]
      end
    end
  end
end

VB.NET

' 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
'
'     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.

Imports Google.Api.Ads.AdWords.Lib
Imports Google.Api.Ads.AdWords.v201809
Imports Google.Api.Ads.Common.Util

Namespace Google.Api.Ads.AdWords.Examples.VB.v201809

  ''' <summary>
  ''' This code example adds a responsive display ad (MultiAssetResponsiveDisplayAd)
  ''' to an ad group. Image assets are uploaded using AssetService. To get ad groups,
  ''' run GetAdGroups.vb.
  ''' </summary>
  Public Class AddMultiAssetResponsiveDisplayAd
    Inherits ExampleBase

    ''' <summary>
    ''' Main method, to run this code example as a standalone application.
    ''' </summary>
    ''' <param name="args">The command line arguments.</param>
    Public Shared Sub Main(ByVal args As String())
      Dim codeExample As New AddMultiAssetResponsiveDisplayAd
      Console.WriteLine(codeExample.Description)
      Try
        Dim adGroupId As Long = Long.Parse("INSERT_ADGROUP_ID_HERE")
        codeExample.Run(New AdWordsUser, adGroupId)
      Catch e As Exception
        Console.WriteLine("An exception occurred while running this code example. {0}",
            ExampleUtilities.FormatException(e))
      End Try
    End Sub

    ''' <summary>
    ''' Returns a description about the code example.
    ''' </summary>
    Public Overrides ReadOnly Property Description() As String
      Get
        Return "This code example adds a responsive display ad " +
            "(MultiAssetResponsiveDisplayAd) to an ad group. Image assets are uploaded using " +
            "AssetService. To get ad groups, run GetAdGroups.vb."
      End Get
    End Property

    ''' <summary>
    ''' Runs the code example.
    ''' </summary>
    ''' <param name="user">The AdWords user.</param>
    ''' <param name="adGroupId">ID of the adgroup to which ad is added.</param>
    Public Sub Run(ByVal user As AdWordsUser, ByVal adGroupId As Long)
      Using adGroupAdService As AdGroupAdService = CType(user.GetService(
          AdWordsService.v201809.AdGroupAdService), AdGroupAdService)
        Try
          ' Create the ad.
          Dim ad As New MultiAssetResponsiveDisplayAd()

          ' Text assets can be specified directly in the asset field when
          ' creating the ad.
          Dim textAsset1 As New TextAsset
          textAsset1.assetText = "Travel to Mars"
          Dim headline1 As New AssetLink
          headline1.asset = textAsset1

          Dim textAsset2 As New TextAsset
          textAsset2.assetText = "Travel to Jupiter"
          Dim headline2 As New AssetLink
          headline2.asset = textAsset2

          Dim textAsset3 As New TextAsset
          textAsset3.assetText = "Travel to Pluto"
          Dim headline3 As New AssetLink
          headline3.asset = textAsset3

          ad.headlines = New AssetLink() {headline1, headline2, headline3}

          Dim textAsset4 As New TextAsset
          textAsset4.assetText = "Visit the planet in a luxury spaceship."
          Dim description1 As New AssetLink
          description1.asset = textAsset1

          Dim textAsset5 As New TextAsset
          textAsset5.assetText = "Travel to Jupiter"
          Dim description2 As New AssetLink
          description2.asset = textAsset5

          Dim textAsset6 As New TextAsset
          textAsset6.assetText = "Travel to Pluto"
          Dim description3 As New AssetLink
          description3.asset = textAsset6

          ad.descriptions = New AssetLink() {description1, description2, description3}
          ad.businessName = "Galactic Luxury Cruises"

          Dim textAsset7 As New TextAsset
          textAsset7.assetText = "Travel to Pluto"
          Dim longHeadline As New AssetLink
          longHeadline.asset = textAsset7

          ad.longHeadline = longHeadline

          ' This ad format does not allow the creation of an image asset by setting
          ' the asset.imageData field. An image asset must first be created using the
          ' AssetService, and asset.assetId must be populated when creating the ad.

          Dim imageAsset1 As New ImageAsset
          imageAsset1.assetId = UploadImageAsset(user, "https://goo.gl/3b9Wfh")
          Dim marketingImage As New AssetLink
          marketingImage.asset = imageAsset1
          ad.marketingImages = New AssetLink() {marketingImage}

          Dim imageAsset2 As New ImageAsset
          imageAsset2.assetId = UploadImageAsset(user, "https://goo.gl/mtt54n")
          Dim squareMarketingImage As New AssetLink
          squareMarketingImage.asset = imageAsset2
          ad.squareMarketingImages = New AssetLink() {squareMarketingImage}

          ad.finalUrls = New String() {"http://www.example.com"}

          ' Optional: set call to action text.
          ad.callToActionText = "Shop Now"

          ' Set color settings using hexadecimal values. Set allowFlexibleColor to false
          ' if you want your ads to render by always using your colors strictly.
          ad.mainColor = "#0000ff"
          ad.accentColor = "#ffff00"
          ad.allowFlexibleColor = False

          ' Set the format setting that the ad will be served in.
          ad.formatSetting = DisplayAdFormatSetting.NON_NATIVE

          ' Optional: set dynamic display ad settings, composed of landscape logo
          ' image, promotion text, And price prefix.
          ad.dynamicSettingsPricePrefix = "as low as"
          ad.dynamicSettingsPromoText = "Free shipping!"

          Dim imageAsset3 As New ImageAsset
          imageAsset3.assetId = UploadImageAsset(user, "https://goo.gl/mtt54n")
          Dim logoImages As New AssetLink
          logoImages.asset = imageAsset3
          ad.logoImages = New AssetLink() {logoImages}

          ' Create the ad group ad.
          Dim adGroupAd As New AdGroupAd()
          adGroupAd.ad = ad
          adGroupAd.adGroupId = adGroupId

          ' Create the operation.
          Dim operation As New AdGroupAdOperation()
          operation.operand = adGroupAd
          operation.operator = [Operator].ADD

          ' Make the mutate request.
          Dim result As AdGroupAdReturnValue = adGroupAdService.mutate(
              New AdGroupAdOperation() {operation})

          ' Display results.
          If Not (result Is Nothing) AndAlso Not (result.value Is Nothing) Then
            For Each newAdGroupAd As AdGroupAd In result.value
              Dim newAd As MultiAssetResponsiveDisplayAd =
                  CType(newAdGroupAd.ad, MultiAssetResponsiveDisplayAd)
              Console.WriteLine("Responsive display ad with ID '{0}' and long headline '{1}'" +
                  " was added.", newAd.id, CType(newAd.longHeadline.asset, TextAsset).assetText)
            Next
          End If
        Catch e As Exception
          Throw New System.ApplicationException("Failed to add expanded text ad to adgroup.", e)
        End Try
      End Using
    End Sub

    ''' <summary>
    ''' Uploads the image from the specified <paramref name="url"/>.
    ''' </summary>
    ''' <param name="user">The AdWords user.</param>
    ''' <param name="url">The image URL.</param>
    ''' <returns>ID of the uploaded image.</returns>
    Private Shared Function UploadImageAsset(ByVal user As AdWordsUser, ByVal url As String) _
        As Long
      Using assetService As AssetService = CType(user.GetService(
          AdWordsService.v201809.AssetService), AssetService)

        ' Create the image asset.
        Dim imageAsset = New ImageAsset()
        ' Optional: Provide a unique friendly name to identify your asset. If you specify
        ' the assetName field, then both the asset name and the image being uploaded should be
        ' unique, and should not match another ACTIVE asset in this customer account.
        ' imageAsset.assetName = "Image asset " + ExampleUtilities.GetRandomString()
        imageAsset.imageData = MediaUtilities.GetAssetDataFromUrl(url, user.Config)

        ' Create the operation.
        Dim operation As New AssetOperation()
        operation.operator = [Operator].ADD
        operation.operand = imageAsset

        ' Create the asset And return the ID.
        Return assetService.mutate(New AssetOperation() {operation}).value(0).assetId
      End Using
    End Function

  End Class

End Namespace

Responsive Display ads can run on campaigns targeting the Google Display Network. Make sure you have an advertisingChannelType of SEARCH or DISPLAY set on the campaign. In the AdWords UI, this corresponds to Search Network campaigns with Display Expansion and Display Network Campaigns respectively.

Specifications

The marketing image and the logo image must meet the following dimension and size specifications:

• Marketing image

  • Minimum dimensions: 600x314 pixels

  • Greater than minimum dimensions: Within 1% of the 1.91:1 ratio

  • Suggested dimensions: 1200x628 pixels

  • Maximum size: 5MB (5,242,880 bytes)

• Logo image (Optional)

  • Minimum dimensions: 128x128 pixels

  • Greater than minimum dimensions: Within 1% of the 1:1 ratio

  • Suggested dimensions: 1200x1200 pixels

  • Maximum size: 5MB (5,242,880 bytes)

• Landscape logo image

  • Minimum dimensions: 512x128 pixels

  • Greater than minimum dimensions: Within 1% of the 4:1 ratio

  • Suggested dimensions: 1200x300 pixels

  • Maximum size: 5MB (5,242,880 bytes)

• Square marketing image

  • Minimum dimensions: 300x300 pixels

  • Greater than minimum dimensions: Within 1% of the 1:1 ratio

  • Suggested dimensions: 1200x1200 pixels

  • Maximum size: 5MB (5,242,880 bytes)

Reporting

The enumeration value for responsive ads for the AdType field is MULTI_ASSET_RESPONSIVE_DISPLAY_AD.

The AD_PERFORMANCE_REPORT contains the following fields specific to multi-asset responsive display ads:

• MultiAssetResponsiveDisplayAdAccentColor
• MultiAssetResponsiveDisplayAdAllowFlexibleColor
• MultiAssetResponsiveDisplayAdBusinessName
• MultiAssetResponsiveDisplayAdCallToActionText
• MultiAssetResponsiveDisplayAdDescriptions
• MultiAssetResponsiveDisplayAdDynamicSettingsPricePrefix
• MultiAssetResponsiveDisplayAdDynamicSettingsPromoText
• MultiAssetResponsiveDisplayAdFormatSetting
• MultiAssetResponsiveDisplayAdHeadlines
• MultiAssetResponsiveDisplayAdLandscapeLogoImages
• MultiAssetResponsiveDisplayAdLogoImages
• MultiAssetResponsiveDisplayAdLongHeadline
• MultiAssetResponsiveDisplayAdMainColor
• MultiAssetResponsiveDisplayAdMarketingImages
• MultiAssetResponsiveDisplayAdSquareMarketingImages

All the asset field columns will be returned either as JSON objects or JSON lists depending on whether the corresponding field supports a single AssetLink (e.g. longHeadline) or multiple AssetLinks (e.g. descriptions). You can obtain additional details such as the asset's performance label and its approval status by deserializing the JSON object. For example, the MultiAssetResponsiveDisplayAdDescriptions field for the ad created by the example above would look like this:

[
  {
    "assetText":"Visit the planet in a luxury spaceship.",
    "assetId":1234,
    "assetPerformanceLabel":"PENDING",
    "assetApprovalStatus":"UNDER_REVIEW"
  },
  {
    "assetText":"See the planet in style.",
    "assetId":5678,
    "assetPerformanceLabel":"PENDING",
    "assetApprovalStatus":"UNDER_REVIEW"
  }
]

Code examples

Java

Add a multi-asset responsive ad
Get all images assets
Upload image asset

PHP

Add a multi-asset responsive ad
Get all images assets
Upload image asset

Python

Add a multi-asset responsive ad
Get all images assets
Upload image asset

Ruby

Add a multi-asset responsive ad
Get all images assets
Upload image asset

Perl

Add a multi-asset responsive ad
Get all images assets
Upload image asset

C#

Add a multi-asset responsive ad
Get all images assets
Upload image asset

VB

Add a multi-asset responsive ad
Get all images assets
Upload image asset