Prerequisites
Before you can create custom events, you need to integrate the rewarded ad format into your app.
Creating a custom event
To define a custom event, you must first create it in the AdMob UI. You can find instructions for creating a custom event in Add a custom event.
Once defined, the custom event adapter points to a class within your app that
implements the Adapter
interface to serve a rewarded ad. The custom event also lists a server parameter
that is passed to your rewarded adapter.
Here is a screenshot showing some sample custom event settings:
The screenshot has the following entries:
- Class Name
- The fully-qualified name of the class that implements the custom event adapter.
- Label
- A unique name defining the ad source.
- Parameter
- An optional string argument passed to your custom event adapter.
Implementing the custom event
A custom event is a class that implements Adapter
to serve third-party ads.
The steps below implement a custom event to request and display rewarded ads
from the Sample Ad Network.
Report version numbers
All custom events must report to the Google Mobile Ads SDK both the version of
the custom event itself and the version of the third-party SDK the custom event
interfaces with. Versions are reported as VersionInfo
:
...
import com.google.android.gms.ads.AdFormat;
import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.VersionInfo;
...
public class SampleAdNetworkCustomEvent extends Adapter implements
SampleAdNetworkInitCompletionListener, SampleRewardedVideoAdListener {
...
@Override
public VersionInfo getVersionInfo() {
String versionString = SampleAdNetwork.VERSION_NAME;
String splits[] = versionString.split("\\.");
int major = Integer.parseInt(splits[0]);
int minor = Integer.parseInt(splits[1]);
int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
return new VersionInfo(major, minor, micro);
}
@Override
public VersionInfo getSDKVersionInfo() {
String versionString = com.SampleAdNetwork.VERSION_NAME;
String splits[] = versionString.split("\\.");
int major = Integer.parseInt(splits[0]);
int minor = Integer.parseInt(splits[1]);
int micro = Integer.parseInt(splits[2]);
return new VersionInfo(major, minor, micro);
}
...
}
Initialize the adapter
Upon an app's initialization of the Google Mobile Ads SDK, initialize()
is
invoked on all adapters configured for the app within the
AdMob UI. This functionality is not
currently supported within custom events, but the Adapter
class does require
the method to be implemented. To work around this, invoke the
onInitializationSucceeded()
callback as a placeholder implementation.
...
import com.google.android.gms.ads.AdFormat;
import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.InitializationCompleteCallback;
import com.google.android.gms.ads.mediation.MediationConfiguration;
...
public class SampleAdNetworkCustomEvent extends Adapter implements
SampleRewardedVideoAdListener {
private static final String SAMPLE_AD_UNIT_KEY = "parameter";
private InitializationCompleteCallback initializationCallback;
@Override
public void initialize(Context context,
InitializationCompleteCallback initializationCompleteCallback,
List<MediationConfiguration> mediationConfigurations) {
// This method currently does not get invoked. As a placeholder, call
// onInitializationSucceeded(). This way, when this feature gets
// implemented in the future, your custom events returns a success
// callback for initialization instead of timing out, which would
// delay the Google Mobile Ads SDK calling back your application with
// the initialization complete callback.
initializationCompleteCallback.onInitializationSucceeded();
}
}
Request a rewarded ad
Requests made by your app to load a rewarded ad invoke the loadRewardedAd()
method of the custom event.
Report either a successful or failed ad load to the Google Mobile Ads SDK by invoking
onSuccess
or onFailure
on the MediationAdLoadCallback
argument provided in
the loadRewardedAd()
call. When reporting a successful ad load, provide a
reference to an object that conforms to MediationRewardedAd
. Invocation of the
onSuccess
method returns a MediationRewardedAdCallback
. Custom events should
maintain reference to this object to notify the Google Mobile Ads SDK of ad lifecycle events.
This is shown in further detail in the Show the ad section.
Here's an example implementation of loadRewardedAd()
:
...
import com.google.ads.mediation.sample.sdk.SampleRewardedVideo;
import com.google.android.gms.ads.mediation.InitializationCompleteCallback;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationRewardedAd;
import com.google.android.gms.ads.mediation.MediationRewardedAdCallback;
...
public class SampleAdNetworkCustomEvent extends Adapter implements
SampleAdNetworkInitCompletionListener, MediationRewardedAd {
private static final String SAMPLE_AD_UNIT_KEY = "parameter";
// Domain for your custom event. Typically represented by the package name.
private static final String DOMAIN = "com.google.ads.mediation.sample.customevent";
// Error code indicating the Sample SDK does not have an ad available.
private static final int ERROR_CODE_NOT_AVAILABLE = 0;
private InitializationCompleteCallback initializationCallback;
private MediationRewardedAdCallback rewardedAdCallback;
...
@Override
public void loadRewardedAd(MediationRewardedAdConfiguration adConfiguration,
MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> adLoadCallback) {
// Gets the custom event parameter from thd ad configuration.
String adUnit = adConfiguration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY);
if (SampleRewardedVideo.isAdAvailable()) {
this.rewardedAdCallback = adLoadCallback.onSuccess(this);
} else {
AdError error = new AdError(ERROR_CODE_NOT_AVAILABLE,
"Sample SDK does not have a rewarded video ad available", DOMAIN);
adLoadCallback.onFailure(error);
}
}
...
}
Show the ad
The Google Mobile Ads SDK may call the showAd()
method of your custom event any time after
the custom event notifies the Google Mobile Ads SDK of a successful ad load. Upon invocation
of this method, the adapter should display the rewarded ad.
...
public class SampleAdNetworkCustomEvent extends Adapter implements
SampleAdNetworkInitCompletionListener, MediationRewardedAd {
...
private MediationRewardedAdCallback rewardedAdCallback;
...
@Override
public void showAd(Context context) {
// Show the rewarded ad.
if (SampleRewardedVideo.isAdAvailable()) {
// Rewarded ad available, show ad.
SampleRewardedVideo.showAd();
}
}
...
}
Report ad events
After displaying the ad, the custom event should report ad lifecycle events as
appropriate to the Google Mobile Ads SDK using the MediationRewardedAdCallback
provided at
successful ad load time.
...
public class SampleAdNetworkCustomEvent extends Adapter implements
SampleAdNetworkInitCompletionListener, MediationRewardedAd {
...
private MediationRewardedAdCallback rewardedAdCallback;
...
@Override
public void showAd(Context context) {
// Show the rewarded ad.
if (SampleRewardedVideo.isAdAvailable()) {
// Rewarded ad available, show ad.
SampleRewardedVideo.showAd();
} else {
// Report that ad cannot be shown.
AdError error = new AdError(ERROR_CODE_NOT_AVAILABLE,
"Sample SDK does not have a rewarded video ad available", DOMAIN);
this.rewardedAdCallback.onAdFailedToShow(error);
}
}
@Override
public void onAdFullScreen() {
this.rewardedAdCallback.onAdOpened();
this.rewardedAdCallback.onVideoStart();
this.rewardedAdCallback.reportAdImpression();
}
@Override
public void onAdRewarded(final String rewardType, final int amount) {
/*
* AdMob requires a reward item with a reward type and
* amount to be sent when sending the rewarded callback. If your SDK does
* not have a reward amount you need to do the following:
*
* 1. AdMob provides an ability to override the
* reward value in the UI. Ask the publisher to override the reward
* value on AdMob's UI.
* 2. Send a reward item with default values for the type (an empty string
* "") and reward amount (1).
*/
this.rewardedAdCallback.onUserEarnedReward(new SampleRewardItem(rewardType,
amount));
}
@Override
public void onVideoComplete() {
this.rewardedAdCallback.onVideoComplete();
}
@Override
public void onAdClicked() {
this.rewardedAdCallback.reportAdClicked();
}
@Override
public void onAdClosed() {
this.rewardedAdCallback.onAdClosed();
}
...
}
The ad events that must be reported to the Google Mobile Ads SDK are detailed below:
Ad event | Description |
---|---|
onAdOpened()
|
Notifies the Google Mobile Ads SDK that the ad opened. |
onAdFailedToShow()
|
Notifies the Google Mobile Ads SDK that the rewarded ad failed to show. |
onVideoStart()
|
Notifies the Google Mobile Ads SDK that a rewarded ad started playing. |
reportAdImpression()
|
Notifies the Google Mobile Ads SDK that an impression occurred on the ad. |
onVideoComplete()
|
Notifies the Google Mobile Ads SDK that the rewarded ad finished playing. |
onUserEarnedReward()
|
Notifies the Google Mobile Ads SDK that the user has earned a reward. |
reportAdClicked()
|
Notifies the Google Mobile Ads SDK that the ad has been clicked. |
onAdClosed()
|
Notifies the Google Mobile Ads SDK that the ad closed. |