Responsive Ads for Display

The responsive ad for Display is an ad that automatically adjusts its size, appearance, and format to fit available ad spaces on the Google Display Network.

ResponsiveDisplayAd contains a marketing image, a short headline, a long headline, a description, and optional name and logo fields, which are all described here.

Example

You create responsive ads in two phases:

  1. Upload the marketing image using the MediaService with the upload() method. Keep track of the ID that comes back. You'll need that later when adding your ad. You can optionally upload a logo image the same way. Once an image is uploaded through the media service, it can be reused for multiple ads later on.

  2. Create a ResponsiveDisplayAd using the AdGroupAdService. For the marketingImage and the logoImage, make sure to reference the media IDs that were returned in the first phase.

Now, let's walk through an example of adding an image to a campaign targeting the display network. Here's an example image for Interplanetary Cruises, that meets the specifications for images in responsive ads.

Java

public static void runExample(
    AdWordsServicesInterface adWordsServices, AdWordsSession session, long adGroupId)
    throws Exception {
  // Get the MediaService.
  MediaServiceInterface mediaService = adWordsServices.get(session, MediaServiceInterface.class);

  // Create image.
  Image image = new Image();
  image.setType(MediaMediaType.IMAGE);
  image.setData(
      com.google.api.ads.common.lib.utils.Media.getMediaDataFromUrl("https://goo.gl/3b9Wfh"));

  // Upload image.
  image = (Image) mediaService.upload(new Media[] {image})[0];

  // Get the AdGroupAdService.
  AdGroupAdServiceInterface adGroupAdService =
      adWordsServices.get(session, AdGroupAdServiceInterface.class);

  // Create a responsive display ad.
  ResponsiveDisplayAd responsiveDisplayAd = new ResponsiveDisplayAd();

  // This ad format does not allow the creation of an image using the
  // Image.data field. An image must first be created using the MediaService,
  // and Image.mediaId must be populated when creating the ad.
  Image marketingImage = new Image();
  marketingImage.setMediaId(image.getMediaId());
  responsiveDisplayAd.setMarketingImage(marketingImage);

  responsiveDisplayAd.setShortHeadline("Travel");
  responsiveDisplayAd.setLongHeadline("Travel the World");
  responsiveDisplayAd.setDescription("Take to the air!");
  responsiveDisplayAd.setBusinessName("Interplanetary Cruises");
  responsiveDisplayAd.setFinalUrls(new String[] {"http://www.example.com/"});

  // Create ad group ad for the responsive display ad.
  AdGroupAd expandedTextAdGroupAd = new AdGroupAd();
  expandedTextAdGroupAd.setAdGroupId(adGroupId);
  expandedTextAdGroupAd.setAd(responsiveDisplayAd);

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

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

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

  // Display ads.
  for (AdGroupAd adGroupAdResult : result.getValue()) {
    ResponsiveDisplayAd newAd = (ResponsiveDisplayAd) adGroupAdResult.getAd();
    System.out.printf(
        "Responsive display ad with ID %d and short headline '%s' was added.%n",
        newAd.getId(), newAd.getShortHeadline());
  }
}

Visual Basic

' Get the AdGroupAdService.
Dim adGroupAdService As AdGroupAdService = CType(user.GetService( _
    AdWordsService.v201705.AdGroupAdService), AdGroupAdService)

' Get the MediaService.
Dim mediaService As MediaService = CType(user.GetService( _
    AdWordsService.v201705.MediaService), MediaService)

Try
  ' Create the image.
  Dim image As New Image()
  image.data = MediaUtilities.GetAssetDataFromUrl("https://goo.gl/3b9Wfh", user.Config)
  image.type = MediaMediaType.IMAGE

  ' Upload the image.
  Dim newImage As Image = CType(mediaService.upload(New Media() {image})(0), Image)

  ' Create a responsive display ad.
  Dim responsiveDisplayAd As New ResponsiveDisplayAd()

  ' This ad format does not allow the creation of an image using the
  ' Image.data field. An image must first be created using the MediaService,
  ' and Image.mediaId must be populated when creating the ad.
  responsiveDisplayAd.marketingImage = New Image()
  responsiveDisplayAd.marketingImage.mediaId = newImage.mediaId

  responsiveDisplayAd.shortHeadline = "Travel"
  responsiveDisplayAd.longHeadline = "Travel the World"
  responsiveDisplayAd.description = "Take to the air!"
  responsiveDisplayAd.businessName = "Google"
  responsiveDisplayAd.finalUrls = New String() {"http://www.example.com"}

  ' Create ad group ad.
  Dim adGroupAd As New AdGroupAd()
  adGroupAd.adGroupId = adGroupId
  adGroupAd.ad = responsiveDisplayAd
  adGroupAd.status = AdGroupAdStatus.PAUSED

  ' Create 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 ResponsiveDisplayAd = CType(newAdGroupAd.ad, ResponsiveDisplayAd)
      Console.WriteLine("Responsive display ad with ID '{0}' and short headline '{1}'" & _
          " was added.", newAd.id, newAd.shortHeadline)
    Next
  Else
    Console.WriteLine("No responsive display ads were created.")
  End If
Catch e As Exception
  Throw New System.ApplicationException("Failed to create responsive display ads.", e)
End Try

Python

def main(client, ad_group_id):
  # Initialize appropriate services.
  ad_group_ad_service = client.GetService('AdGroupAdService', version='v201705')
  media_service = client.GetService('MediaService', version='v201705')

  try:
    # Create image.
    opener = urllib2.build_opener(*client.proxy_config.GetHandlers())
    image_data = base64.b64encode(opener.open('https://goo.gl/3b9Wfh').read())
    image = {
        'type': 'IMAGE',
        'data': image_data,
        'xsi_type': 'Image'
    }

    # Make the upload request
    image = media_service.upload(image)[0]

    # Create a responsive display ad.
    operations = [{
        'operator': 'ADD',
        'operand': {
            'xsi_type': 'AdGroupAd',
            'adGroupId': ad_group_id,
            'ad': {
                'xsi_type': 'ResponsiveDisplayAd',
                'marketingImage': {'mediaId': image['mediaId']},
                'shortHeadline': 'Travel',
                'longHeadline': 'Travel the World',
                'description': 'Take to the air!',
                'businessName': 'Interplanetary Cruises',
                'finalUrls': ['http://www.example.com']
            },
            # Optional fields.
            'status': 'PAUSED'
        }
    }]

    # Make the mutate request.
    ads = ad_group_ad_service.mutate(operations)

    # Display results.
    for ad in ads['value']:
      print ('ResponsiveDisplayAd with id "%d" and short headline "%s" was '
             'added.' % (ad['ad']['id'], ad['ad']['shortHeadline']))

  except:
    raise Exception('Failed to create responsive display ad.')

PHP

public static function runExample(AdWordsServices $adWordsServices,
    AdWordsSession $session, $adGroupId) {
  $mediaService = $adWordsServices->get($session, MediaService::class);

  // Create an image and add it to the images list.
  $image = new Image();
  $image->setData(file_get_contents('http://goo.gl/3b9Wfh'));
  $image->setType(MediaMediaType::IMAGE);
  $images = [$image];

  // Upload the image to the server.
  $image = $mediaService->upload($images)[0];

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

  $operations = [];
  // Create a responsive display ad.
  $responsiveDisplayAd = new ResponsiveDisplayAd();

  // This ad format does not allow the creation of an image using the
  // Image.data field. An image must first be created using the MediaService,
  // and Image.mediaId must be populated when creating the ad.
  $marketingImage = new Image();
  $marketingImage->setMediaId($image->getMediaId());

  $responsiveDisplayAd->setMarketingImage($marketingImage);
  $responsiveDisplayAd->setShortHeadline('Travel');
  $responsiveDisplayAd->setLongHeadline('Travel the World');
  $responsiveDisplayAd->setDescription('Take to the air!');
  $responsiveDisplayAd->setBusinessName('Google');
  $responsiveDisplayAd->setFinalUrls(['http://www.example.com']);

  // Create ad group ad.
  $adGroupAd = new AdGroupAd();
  $adGroupAd->setAdGroupId($adGroupId);
  $adGroupAd->setAd($responsiveDisplayAd);
  // Optional: Set additional settings.
  $adGroupAd->setStatus(AdGroupAdStatus::PAUSED);

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

  // Add a responsive display ad on the server.
  $result = $adGroupAdService->mutate($operations);

  // Create the responsive display ad on the server and print out some
  // information for each created responsive display ad.
  foreach ($result->getValue() as $adGroupAd) {
    printf(
        "Responsive display ad with ID %d and short headline '%s'"
            . " was added.\n",
        $adGroupAd->getAd()->getId(),
        $adGroupAd->getAd()->getShortHeadline()
    );
  }
}

Perl

sub add_responsive_display_ad {
  my $client      = shift;
  my $ad_group_id = shift;

  # Create image.
  my $image_data = Google::Ads::Common::MediaUtils::get_base64_data_from_url(
    "https://goo.gl/3b9Wfh");
  my $image = Google::Ads::AdWords::v201705::Image->new({
      data => $image_data,
      type => "IMAGE"
  });

  # Upload image.
  $image = $client->MediaService()->upload({media => [$image]});

  # This ad format does not allow the creation of an image using the
  # Image.data field. An image must first be created using the MediaService,
  # and Image.mediaId must be populated when creating the ad.
  my $marketing_image = Google::Ads::AdWords::v201705::Image->new(
    {mediaId => $image->get_mediaId()});

  # Create the responsive display ad.
  my $responsive_display_ad =
    Google::Ads::AdWords::v201705::ResponsiveDisplayAd->new({
      marketingImage => $marketing_image,
      shortHeadline  => "Travel",
      longHeadline   => "Travel the World",
      description    => "Take to the air!",
      businessName   => "Interplanetary Cruises",
      finalUrls      => ["http://www.example.com/"],
    });

  # Create ad group ad for the responsive display ad.
  my $responsive_display_ad_group_ad =
    Google::Ads::AdWords::v201705::AdGroupAd->new({
      adGroupId => $ad_group_id,
      ad        => $responsive_display_ad,
      # Additional properties (non-required).
      status => "PAUSED"
    });

  # Create operation.
  my $responsive_display_ad_group_ad_operation =
    Google::Ads::AdWords::v201705::AdGroupAdOperation->new({
      operator => "ADD",
      operand  => $responsive_display_ad_group_ad
    });

  # Add responsive display ad.
  my $result =
    $client->AdGroupAdService()
    ->mutate({operations => [$responsive_display_ad_group_ad_operation]});

  # Display results.
  if ($result->get_value()) {
    foreach my $ad_group_ad (@{$result->get_value()}) {
      printf "New responsive display ad with id \"%d\" and " .
        "short headline \"%s\" was added.\n",
        $ad_group_ad->get_ad()->get_id(),
        $ad_group_ad->get_ad()->get_shortHeadline();
    }
  } else {
    print "No responsive display ads were added.\n";
  }

  return 1;
}

Ruby

ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
media_srv = adwords.service(:MediaService, API_VERSION)

# Create an image.
image_url = 'https://goo.gl/3b9Wfh'
raw_image_data = AdsCommon::Http.get(image_url, adwords.config)
image = {
  :xsi_type => 'Image',
  :data => Base64.encode64(raw_image_data),
  :type => 'IMAGE'
}

# Upload the image.
response = media_srv.upload([image])
if response and !response.empty?
  image = response.first
else
  raise StandardError, "Could not upload image. Aborting before creating ad."
end

# Create the responsive display ad.
responsive_display_ad = {
  :xsi_type => 'ResponsiveDisplayAd',
  # This ad format does not allow the creation of an image using the
  # Image.data field. An image must first be created using the MediaService,
  # and Image.mediaId must be populated when creating the ad.
  :marketing_image => {
    :media_id => image[:media_id]
  },
  :short_headline => 'Travel',
  :long_headline => 'Traver the World',
  :description => 'Take to the air!',
  :business_name => 'Interplanetary Cruises',
  :final_urls => ['http://www.example.com/']
}

# Create an ad group ad for the responsive display ad.
responsive_display_ad_group_ad = {
  :ad_group_id => ad_group_id,
  :ad => responsive_display_ad,
  # Additional propertires (non-required).
  :status => 'PAUSED'
}

# Create operation.
responsive_display_ad_group_ad_operations = {
  :operator => 'ADD',
  :operand => responsive_display_ad_group_ad
}

# Add the responsive display ad.
result = ad_group_ad_srv.mutate([responsive_display_ad_group_ad_operations])

# Display results.
if result && result[:value]
  result[:value].each do |ad_group_ad|
    puts ('New responsive display ad with id %d and short headline %s was ' +
        'added.') % [ad_group_ad[:ad][:id], ad_group_ad[:ad][:short_headline]]
  end
else
  puts "No responsive display ads were added."
end

Responsive ads can run only in campaigns targeting the Google Display Network. Make sure you have an advertisingChannelType of DISPLAY set on the campaign. In the AdWords user interface, the campaign will be described as Display Network Only -- All Features.

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: 1MB (1,048,576 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: 1MB (1,048,576 bytes)

Reporting

The AdType in reports for responsive ads is RESPONSIVE_DISPLAY_AD.

The AD_PERFORMANCE_REPORT contains the following fields specific to responsive ads:

Upgrade tips

You can test the new ad format in test accounts today. Perform the following steps if you're upgrading from standard text ads to responsive ads for Display:

  1. Create the new responsive ad in a PAUSED state.

  2. Wait for the new responsive ad's approvalStatus to become APPROVED.

  3. Send an AdGroupAdService.mutate() request with two operations:

    • Set the new responsive ad status to ENABLED.
    • Set the old standard text ad status to DISABLED.

Check out the Generate custom display ads based on your text ads section under Tips for creating effective display ads for more general tips.

Code examples

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.