Interstitial ads custom events

Through custom events, you can also monetize your application with ad networks not directly supported by mediation. A custom event is implemented through the GADCustomEventInterstitial protocol.

Prerequisites

Before you can create custom events, you need to integrate the interstitial ad format into your app.

You may also want to first read about loading an interstitial ad and how mediation works.

Sample Ad Network

This guide demonstrates how to serve interstitials from the Sample Ad Network using the SampleCustomEventInterstital custom event class. The Sample Ad Network SDK is a mock SDK developed to illustrate what a real-life implementation of a custom event would look like. The SDK contains classes that are representative of the classes offered by most ad networks. See the complete sample SDK implementation for more information.

See the sample implementation of a custom event banner for more information.

Note: To import Objective-C files into your Swift project, you must create an Objective-C bridging header.

Interstitial custom event

The implementation of an interstitial custom event is similar to that of a banner custom event. The main difference is that the interstitial custom event class you create should implement the GADCustomEventInterstitial protocol instead of the GADCustomEventBanner protocol.

Define a custom event

Custom events must be defined in the Ad Manager UI. You can find instructions for setting up an Ad Manager yield group for mediation in this Help Center article.

Here's a screenshot showing some sample custom event settings:

The following table provides guidance on how to fill out these parameters.

Class Name	Enter the fully qualified name of the class that implements the custom event. If your class is implemented in Swift, you need to prefix the class name with the name of its app / framework module (for example, appName.className). Target name is required if you have multiple targets in your project or if the project name is different from the target name. With the target name, it would look like this: appName_targetName.className. In addition, remember to replace any non-alphanumeric characters such as dashes with underscores. For more details, see this example.
Label	Enter a unique name for the event.
Parameter	If you wish to pass an argument to your custom event, enter the appropriate string.

Request an interstitial

For custom event interstitial requests, the requestInterstitialAdWithParameter:label:request: method is called immediately after the custom event class is instantiated. This method does not return anything. The assumption is that the custom event will start an asynchronous ad fetch over the network.

Your custom event should act as a delegate to your SDK to listen to callbacks. The serverParameter and serverLabel parameters correspond to the parameter and label fields defined when creating a custom event in the Ad Manager UI.

Here is an example implementation of requestInterstitialAdWithParameter:label:request:using the Sample Ad Network:

Swift

func requestInterstitialAdWithParameter(serverParameter: String!,
    label serverLabel: String!, request: GADCustomEventRequest!) {
  interstitial = SampleInterstitial()
  interstitial.delegate = self
  interstitial.adUnit = serverParameter
  let adRequest = SampleAdRequest()
  adRequest.testMode = request.isTesting
  adRequest.keywords = request.userKeywords
  interstitial.fetchAd(adRequest)
}

Objective-C

- (void)requestInterstitialAdWithParameter:(NSString *)serverParameter
                                     label:(NSString *)serverLabel
                                   request:(GADCustomEventRequest *)request {
  self.interstitial = [[SampleInterstitial alloc] init];
  self.interstitial.delegate = self;
  self.interstitial.adUnit = serverParameter;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = request.isTesting;
  adRequest.keywords = request.userKeywords;
  [self.interstitial fetchAd:adRequest];
}

The GADCustomEventInterstitial custom event protocol requires you to implement the presentFromRootViewController: method. Mediation invokes this method when you tell the Mobile Ads SDK to show the interstitial as follows:

Swift

func presentFromRootViewController(rootViewController: UIViewController!) {
  if interstitial.interstitialLoaded {
    interstitial.show()
  }
}

Objective-C

- (void)presentFromRootViewController:(UIViewController *)rootViewController {
  if ([self.interstitial isInterstitialLoaded]) {
    [self.interstitial show];
  }
}

Send ad network extras for custom event requests

In order to send ad network extras with the request for your custom event to handle, you use the GADRequest registerAdNetworkExtras: function. You must create an instance of GADCustomEventExtras (which conforms to the GADAdNetworkExtras protocol) in order for a GADCustomEventRequest.additionalParameters property to be populated. To pass in your extras, call GADCustomEventExtras setExtras:forLabel:, passing in your extras as a dictionary and the label of your custom event that you defined in the Ad Manager UI.

Here is a code snippet which shows how to pass a SampleExtra parameter for our SampleCustomEvent label defined earlier:

Swift

let request = GAMRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)

Objective-C

GAMRequest *request = [GAMRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:@{@"SampleExtra": @(YES)} forLabel:@"SampleCustomEvent"];
[request registerAdNetworkExtras:extras];

If you don't register an instance of GADCustomEventExtras for a custom event request, the additionalParameters property of the GADCustomEventRequest will be nil.

Notify Ad Manager mediation

Just as with the banner custom event, implement your network's ad listener to send messages back to mediation. The following example shows the implementation of the Sample Ad Network's SampleInterstitialAdDelegate interface:

Swift

/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"

// Sent when an interstitial ad has loaded.
func interstitialDidLoad(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidReceiveAd(self)
}

// Sent when interstitial ad has failed to load.
func interstitial(interstitial: SampleInterstitial!,
    didFailToLoadAdWithErrorCode errorCode: SampleErrorCode) {
  let nsError = NSError(domain: SampleCustomEventInterstitial.customEventErrorDomain,
      code: errorCode.rawValue, userInfo: nil)
  delegate.customEventInterstitial(self, didFailAd: nsError)
}

// Sent when an interstitial is about to be shown.
func interstitialWillPresentScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillPresent(self)
}

// Sent when an interstitial is about to be dismissed.
func interstitialWillDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillDismiss(self)
}

// Sent when an interstitial has been dismissed.
func interstitialDidDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidDismiss(self)
}

// Sent when an interstitial is clicked and an external application is launched.
func interstitialWillLeaveApplication(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWasClicked(self)
  delegate.customEventInterstitialWillLeaveApplication(self)
}

Objective-C

/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";

// Sent when an interstitial ad has loaded.
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidReceiveAd:self];
}

// Sent when an interstitial ad has failed to load.
- (void)interstitial:(SampleInterstitial *)interstitial
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                       code:errorCode
                                   userInfo:nil];
  [self.delegate customEventInterstitial:self didFailAd:error];
}

// Sent when an interstitial is about to be shown.
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillPresent:self];
}

// Sent when an interstitial is about to be dismissed.
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillDismiss:self];
}

// Sent when an interstitial has been dismissed.
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidDismiss:self];
}

// Sent when an interstitial is clicked and an external application is launched.
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWasClicked:self];
  [self.delegate customEventInterstitialWillLeaveApplication:self];
}

Sending messages back to mediation allows it to continue the mediation flow.

To import Objective-C files into your Swift project, you must create an Objective-C bridging header.

See the sample implementation of an interstitial custom event for more information.

Mediation callbacks

Ad Manager mediation supports the following callbacks:

Method	When to call
customEventInterstitial:DidReceiveAd:	The interstitial request succeeded.
customEventInterstitial:didFailAd:	The interstitial request failed.
customEventInterstitialWillPresent:	The interstitial will be shown, presenting a full screen modal view.
customEventInterstitialWillDismiss:	The interstitial will dismiss a full screen modal view.
customEventInterstitialDidDismiss:	The interstitial did dismiss a full screen modal view.
customEventInterstitialWillLeaveApplication:	The interstitial caused the user to leave the app.
customEventInterstitialWasClicked:	The interstitial was clicked.