This guide is intended for publishers looking to add support for banner and interstitial custom events within Ad Manager mediation.
Custom events allow you to put any view you want into your ad space.
Through custom events, you can also monetize your application
with ad networks not directly supported by mediation.
A custom event is implemented through either the GADCustomEventBanner
or the GADCustomEventInterstitial
protocol.
Prerequisites
Before you can integrate custom events for banner or interstitial ads, you need to integrate that ad format into your app. Here are the relevant guides:
Sample Ad Network
This guide demonstrates how to serve banners and interstitials
from the Sample Ad Network
using the SampleCustomEventBanner
and SampleCustomEventInterstital
custom event classes.
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 about these classes.
Banner custom event
In the following example, you first create a banner custom event within Ad Manager mediation. This requires that you define a custom event that points to that specific class in your application through the Ad Manager UI, then implement a banner custom event to return a view.
Define a custom event
Custom events must be defined in the Google 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 a banner
For custom event banner requests, the requestBannerAd:parameter: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.
If your SDK does not support the given ad size or does not support banner ads,
call the customEventBanner:didFailAd:
method of the custom event delegate.
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 requestBannerAd:parameter:label:request:
using the Sample Ad Network:
Swift
func requestBannerAd(adSize: GADAdSize, parameter serverParameter: String!,
label serverLabel: String!, request: GADCustomEventRequest!) {
// Create a banner view with the appropriate size.
bannerAd = SampleBanner(frame: CGRectMake(
0, 0, adSize.size.width, adSize.size.height))
bannerAd.delegate = self
bannerAd.adUnit = serverParameter
let adRequest = SampleAdRequest()
adRequest.testMode = request.isTesting
adRequest.keywords = request.userKeywords
bannerAd.fetchAd(adRequest)
}
Objective-C
- (void)requestBannerAd:(GADAdSize)adSize
parameter:(NSString *)serverParameter
label:(NSString *)serverLabel
request:(GADCustomEventRequest *)request {
// Create the bannerView with the appropriate size.
self.bannerAd =
[[SampleBanner alloc] initWithFrame:CGRectMake(0,
0,
adSize.size.width,
adSize.size.height)];
self.bannerAd.delegate = self;
self.bannerAd.adUnit = serverParameter;
SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
adRequest.testMode = request.isTesting;
adRequest.keywords = request.userKeywords;
[self.bannerAd fetchAd:adRequest];
}
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 = DFPRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)
Objective-C
DFPRequest *request = [DFPRequest 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
Implement the ad listener for your network and invoke the relevant callbacks
on the custom event's delegate to send messages back to mediation. The following
example implements the Sample Ad Network's SampleBannerAdDelegate
interface
to send these messages:
Swift
/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"
// Sent when banner ad has loaded.
func bannerDidLoad(banner: SampleBanner!) {
delegate.customEventBanner(self, didReceiveAd: banner)
}
// Sent when banner has failed to load.
func banner(banner: SampleBanner!, didFailToLoadAdWithErrorCode error: SampleErrorCode) {
let nsError = NSError(domain: SampleCustomEventBanner.customEventErrorDomain,
code: error.rawValue, userInfo: nil)
delegate.customEventBanner(self, didFailAd: nsError)
}
// Sent when a banner is clicked and an external application is launched
func bannerWillLeaveApplication(banner: SampleBanner!) {
delegate.customEventBannerWasClicked(self)
delegate.customEventBannerWillLeaveApplication(self)
}
Objective-C
/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";
// Sent when banner ad has loaded.
- (void)bannerDidLoad:(SampleBanner *)banner {
[self.delegate customEventBanner:self didReceiveAd:banner];
}
// Sent when banner has failed to load.
- (void)banner:(SampleBanner *)banner
didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
NSError *error = [NSError errorWithDomain:customEventErrorDomain
code:errorCode
userInfo:nil];
[self.delegate customEventBanner:self didFailAd:error];
}
// Sent when a banner is clicked and an external application is launched.
- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
[self.delegate customEventBannerWasClicked:self];
[self.delegate customEventBannerWillLeaveApplication:self];
}
Ad Manager mediation supports the following callbacks:
Banner ads
Method | When to call |
---|---|
customEventBanner:didReceiveAd: |
The banner request succeeded. |
customEventBanner:didFailAd: |
The banner request failed. |
customEventBannerWillPresentModal: |
The banner will present a full screen modal view. |
customEventBannerWillDismissModal: |
The banner will dismiss a full screen modal view. |
customEventBannerDidDismissModal: |
The banner did dismiss a full screen modal view. |
customEventBannerWillLeaveApplication: |
The banner caused the user to leave the app. |
customEventBannerWasClicked: |
The banner was clicked. |
Interstitial ads
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. |
See the sample implementation of a custom event banner for more information.
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 = DFPRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)
Objective-C
DFPRequest *request = [DFPRequest 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.
See the sample implementation of an interstitial custom event for more information.