Friday, December 14, 2012

Using DFP App Events with the Google AdMob SDK

App Events, a feature introduced in v6.1.0 of the AdMob SDK, provides DFP developers the ability to create ads that can send messages to their application code. The application can listen for and react to these messages by executing custom code.

This powerful feature lets you do some pretty cool things, such as sending the entire creative code to the app, or telling the app what ad is running. In this example, we’ll show how the app can change background colors when it receives an app event.

The first step is to set up your creative in DFP. The sample below is a 320x50 creative which sends a color=red event when the ad is first displayed, and a color=green event when the ad is clicked.

<html>
<head>
  <script src="//media.admob.com/api/v1/google_mobile_app_ads.js"></script>
  <script>
    // Send a color=red event when ad loads.
    admob.events.dispatchAppEvent("color", "red");
    
    handleClick = function() {
      // Send a color=green event when ad is clicked.
      admob.events.dispatchAppEvent("color", "green");
    };
  </script>
  <style>
    #ad {
      width: 320px;
      height: 50px;
      top: 0px;
      left: 0px;
      font-size: 24pt;
      font-weight: bold;
      position: absolute;
      background: green;
      color: red;
      text-align: center;
    }
  </style>
</head>
<body>
  <div id="ad" onClick="handleClick()">Happy Holidays!</div>
</body>
</html>

The creative above references the AdMob API for Ads JavaScript, and calls admob.events.dispatchAppEvent to send app events. You can check out an example of the creative below, and view the developer console to see logging statements when the app events are being fired.


The next step is to have the application code listen for these app events. Here are the iOS and Android versions of this method, respectively:

// iOS
- (void)adView:(DFPBannerView *)banner
    didReceiveAppEvent:(NSString *)name
    withInfo:(NSString *)info {
  NSLog(@"Received app event (%@, %@)", name, info);
  // Checking for a "color" event name with information being a color.
  if ([name isEqualToString:@"color"]) {
    if ([info isEqualToString:@"red"]) {
      self.view.backgroundColor = [UIColor redColor];
    } else if ([info isEqualToString:@"green"]) {
      self.view.backgroundColor = [UIColor greenColor];
    }
  }
}

// Android
@Override
public void onAppEvent(Ad ad, String name, String info) {
  String message = String.format("Received app event (%s, %s)", name, info);
  Log.d(LOG_TAG, message);
  if ("color".equals(name)) {
    LinearLayout layout = (LinearLayout) findViewById(R.id.mainLayout);
    if ("red".equals(info)) {
      layout.setBackgroundColor(Color.RED);
    } else if ("green".equals(info)) {
      layout.setBackgroundColor(Color.GREEN);
    }
  }
}

Remember to register this callback on the banner view:

// iOS
[bannerView_ setAppEventDelegate:self];

// Android
adView.setAppEventListener(this);

That’s it! If you load this ad into your banner view, your application will change its background color to red when the ad is loaded, and green when the ad is clicked. This example can be extended to change the implementation of the app event listener or to fire app events at any point during the creative’s lifecycle.

Let us know on the forum if you have any questions about app events specifically or the Google AdMob SDK in general. You can also follow us on our plus page for AdMob-related updates.

Edit: Fixed plus page link.