iOS App

Prerequisites

This implementation guide assumes you are familiar with the following:

Overview

This document outlines the process to integrate AdSense for Shopping for Mobile Apps (AFShMA) ads in your iOS mobile app. To request and render AFShMA ads on iOS, use the following:

GADSearchBannerView

  • This class inherits from the iOS UIView class and displays the AFShMA ads. The GADSearchBannerView makes the request for an ad with a GADDynamicHeightSearchRequest and renders the returned ads. The GADSearchBannerView should be added to any of the app's existing views; typically a reference to the GADSearchBannerView is added in the parent view controller, as that holds the view to which the GADSearchBannerView is added. The appropriate delegates should be set on the GADSearchBannerView.
  • The GADSearchBannerView must be instantiated with initWithAdSize:kGADAdSizeFluid to request AFShMA ads. Instantiating GADSearchBannerView with initWithAdSize:kGADAdSizeBanner requests legacy AFShMA ads.
  • The adUnitID property on this object needs to be set to the property code (such as vert-pla-test1-srp) of the partner.

GADDynamicHeightSearchRequest

  • This object encapsulates the ad request parameters. This is analogous to setting parameters in the JavaScript ad request options (page options, unit options) for AFSh desktop and mobile web.

(void)adView:(GADBannerView *)bannerView willChangeAdSizeTo:(GADAdSize)size

  • This callback is called when the ad request returns. Since the returned ad unit could contain a number of ads, the exact size of the ad unit is unknown when the ad request is made. Once the ad unit is returned, the banner view needs to be updated to accommodate the new size of the ad unit. Code to resize the GADSearchBannerView in its parent view should be implemented here.

Example implementation

The example below demonstrates using a GBannerViewController to create a GADSearchBannerView as a subview of a UIScrollView. To properly request AFShMA ads, the GADSearchBannerView object must be instantiated with initWithAdSize:kGADAdSizeFluid.

//  GBannerViewController.m implementation.

@interface GBannerViewController () <GADAdSizeDelegate, GADBannerViewDelegate>
@property(nonatomic, strong) UIScrollView *scrollView;
@property(nonatomic, strong) GADSearchBannerView *searchBannerView;
@end

@implementation GBannerViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // Create the scroll view.
  ....

  // Create the banner.
  self.searchBannerView =
      [[GADSearchBannerView alloc] initWithAdSize:kGADAdSizeFluid];

  // Replace with your pub ID (such as vert-pla-mobile-app-test1-srp).
  self.searchBannerView.adUnitID = @"vert-pla-mobile-app-################";

  // Set the initial location and size of the banner.
  self.searchBannerView.frame = CGRectMake(0, 0, CGRectGetWidth(self.view.bounds), 0);
  self.searchBannerView.autoresizingMask = UIViewAutoresizingFlexibleWidth;

  // Set the delegate properties.
  self.searchBannerView.adSizeDelegate = self;
  self.searchBannerView.delegate = self;

  // Add the new search banner into the parent scrollView.
  [self.scrollView addSubview:self.searchBannerView];

Within the same GBannerViewController, create a GADDynamicHeightSearchRequest that dictates the parameters of the ad that will be rendered in the GADSearchView. AFShMA ads are configured in the same way as AFSh for web; details are available on the AdSense for Shopping reference.

  // Create a search request and load the banner.
  GADDynamicHeightSearchRequest *searchRequest = [[GADDynamicHeightSearchRequest alloc] init];

  // Ad request options (set using GADDynamicHeightSearchRequest properties).
  searchRequest.query = @"running shoes";
  searchRequest.adTestEnabled = YES;      // Remove when launching to production.

To request for AFShMA ads, set adType to plas using the setAdvancedOptionValue() method. You must also specify a height and width.

  // Set adType to "plas" to request for AFShMA ads.
  [searchRequest setAdvancedOptionValue:@"plas" forKey:@"adType"];

  // Set height and width for AFShMA ad block.
  [searchRequest setAdvancedOptionValue:@"400" forKey:@"height"];
  [searchRequest setAdvancedOptionValue:@"400" forKey:@"width"];

Other customization options are possible by setting additional properties on the GADDynamicHeightSearchRequest object (searchRequest here).

To make an ad request, call loadRequest with the GADDynamicHeightSearchRequest object from the GADSearchBannerView object:

  [self.searchBannerView loadRequest:searchRequest];

To have the parent view properly accommodate the GADSearchBannerView once the ads return, you must implement the following callback:

// Callback to update the parent view height.
- (void)adView:(GADBannerView *)bannerView willChangeAdSizeTo:(GADAdSize)size {
  // Update the banner view based on the ad size.
  CGRect newFrame = self.searchBannerView.frame;
  newFrame.size.height = size.size.height;
  self.searchBannerView.frame = newFrame;

  // Any time the ad size changes, trigger a relayout of the view.
  [self.view setNeedsLayout];
}

Advanced options

Most of the ad request parameters can be set via properties on the GADDynamicHeightSearchRequest object (searchRequest above). Any parameters that don't have a setter method in GADDynamicHeightSearchRequest can be set using key-value pairs with the setAdvancedOptionValue method. A complete listing of settings that can to be set with the setAdvancedOptionValue() method is provided in the AdSense Custom Search Ads Reference.

  // Advanced customization options (set using key-value pair).

  // Set a parameter (parameter_name) and its value (parameter_value):
  // [searchRequest setAdvancedOptionValue:@"parameter_value" forKey:@"parameter_name"];

  // Customize color for merchant name.
  [searchRequest setAdvancedOptionValue:@"007f00" forKey:@"textColorPalette"];

If you use a parameter's setter method and also set it using setAdvancedOptionValue(), the second call overrides the value from the first call.

Investigating errors

The GADBannerViewDelegate contains a callback to help you investigate errors:

- (void)adView:(GADBannerView *)bannerView
      didFailToReceiveAdWithError:(GADRequestError *)error {

  // This callback is triggered when the ad request fails.
  // Add code here to debug the error object to discover causes of failure.
  NSLog(@"Ad call failed due to %@", error.userInfo[@"NSUnderlyingError"]);
}

If an ad request fails, you can use this callback to handle the error properly and investigate the error through the error object.