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. Google Ads 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:
Create
ImageAssets
by uploading images (marketing images, square marketing images, optional logos, and optional landscape logos) using theAssetService.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.Create a
MultiAssetResponsiveDisplayAd
usingAdGroupAdService
. For themarketingImages
,logoImages
,landscapeLogoImages
, andsquareMarketingImages
, be sure to reference the Asset IDs that were returned in Step 1.TextAsset
fields such asdescriptions
andlongHeadLine
can be specified directly in the ad field, and needn't be created usingAssetService.mutate()
.
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; 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 Google Ads 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 adGet all images assets
Upload image asset
PHP
Add a multi-asset responsive adGet all images assets
Upload image asset
Python
Add a multi-asset responsive adGet all images assets
Upload image asset
Ruby
Add a multi-asset responsive adGet all images assets
Upload image asset
Perl
Add a multi-asset responsive adGet all images assets
Upload image asset
C#
Add a multi-asset responsive adGet all images assets
Upload image asset
VB
Add a multi-asset responsive adGet all images assets
Upload image asset