Tài liệu hướng dẫn này dành cho những người muốn sử dụng nền tảng Dàn xếp AdMob để hiển thị quảng cáo video có tặng thưởng trên mạng quảng cáo của bên thứ ba.
Sự kiện tùy chỉnh và các mạng quảng cáo được AdMob hỗ trợ
Các mạng quảng cáo được nền tảng dàn xếp AdMob hỗ trợ trực tiếp sẽ triển khai bộ chuyển đổi dàn xếp chuẩn. Tuy nhiên, bạn vẫn có thể sử dụng các mạng quảng cáo không được AdMob hỗ trợ trực tiếp để yêu cầu và hiển thị video có tặng thưởng bằng cách triển khai bộ chuyển đổi sự kiện tùy chỉnh. Sự khác biệt giữa bộ chuyển đổi dàn xếp chuẩn và bộ chuyển đổi sự kiện tùy chỉnh được trình bày bên dưới.
Xác định thông số máy chủ
Những mạng quảng cáo được dàn xếp thông qua nền tảng dàn xếp AdMob cần một hoặc nhiều giá trị nhận dạng để nhận dạng một nhà xuất bản. Các giá trị nhận dạng này được biểu thị dưới dạng thông số máy chủ và được xác định khi định cấu hình mạng quảng cáo của bên thứ ba cho hoạt động dàn xếp trong giao diện người dùng AdMob.
Nếu bạn đang tạo bộ chuyển đổi sự kiện tùy chỉnh, hãy thực hiện bước tiếp theo bên dưới để tạo một sự kiện tùy chỉnh. Nếu bạn đang tạo một bộ chuyển đổi, mạng quảng cáo của bạn và các thông số máy chủ tương ứng sẽ được định cấu hình như là một phần trong quy trình giới thiệu mạng quảng cáo với AdMob.
Tạo sự kiện tùy chỉnh
Để xác định một sự kiện tùy chỉnh, trước tiên bạn phải tạo sự kiện đó trong giao diện người dùng AdMob. Bạn có thể
tham khảo bài viết về Thêm sự kiện tùy chỉnh
để biết cách tạo sự kiện tùy chỉnh. Sau khi được xác định,
sự kiện tùy chỉnh đó trỏ đến một lớp trong ứng dụng sẽ triển khai
MediationRewardedVideoAdAdapter để phân phát video có tặng thưởng. Sự kiện tùy chỉnh này
cũng liệt kê một thông số máy chủ được chuyển tới bộ chuyển đổi video có tặng thưởng.
Bạn có thể thấy một số tùy chọn cài đặt của sự kiện tùy chỉnh mẫu trong ảnh chụp màn hình dưới đây:
Ảnh chụp màn hình có các mục nhập sau:
- Tên lớp
- Tên đủ điều kiện của lớp triển khai sự kiện tùy chỉnh.
- Nhãn
- Tên duy nhất của sự kiện.
- Thông số
- Một đối số được chuyển đến sự kiện tùy chỉnh (không bắt buộc).
Triển khai bộ chuyển đổi dàn xếp
Phần này trình bày các bước mà bạn bắt buộc phải thực hiện để triển khai một bộ chuyển đổi. Để cho bạn thấy hình thức hiển thị trong thực tế của mã bộ chuyển đổi, chúng tôi đã tạo SDK mạng quảng cáo mẫu và sẽ tạo bộ chuyển đổi cho SDK này.
Chạy bộ chuyển đổi
Theo yêu cầu quảng cáo video có tặng thưởng ban đầu của một ứng dụng, SDK quảng cáo trên thiết bị di động của Google
sẽ gọi phương thức initialize() của bộ chuyển đổi.
Bộ chuyển đổi của bạn chịu trách nhiệm triển khai phương thức này
để chạy mạng quảng cáo của bên thứ ba. Phương thức này cung cấp cho bạn gói serverParameters
mà bạn có thể cần để hoàn thành việc chạy bộ chuyển đổi. Có một sự khác biệt nhỏ
về cách truy cập vào các thông số này, tùy thuộc vào việc bạn
đang phát triển bộ chuyển đổi dàn xếp hay bộ chuyển đổi sự kiện tùy chỉnh.
Đối với bộ chuyển đổi dàn xếp, các khóa cho thông số máy chủ được định cấu hình trước và bạn có thể trích xuất từng thông số máy chủ. Đối với các sự kiện tùy chỉnh, có một thông số duy nhất có thể được truy cập qua khóa MediationRewardedVideoAdAdapter.CUSTOM_EVENT_SERVER_PARAMETER_FIELD:
Bộ chuyển đổi dàn xếp
String parameter1 = serverParameters.getString("SERVER_PARAMETER_KEY1");
String parameter2 = serverParameters.getString("SERVER_PARAMETER_KEY2");
Sự kiện tùy chỉnh
String parameter = serverParameters.getString(MediationRewardedVideoAdAdapter.CUSTOM_EVENT_SERVER_PARAMETER_FIELD);
Bộ chuyển đổi này sẽ giữ lại tệp tham chiếu đến bản sao MediationRewardedVideoAdListener
để có thể chuyển tiếp các sự kiện quảng cáo tới
SDK quảng cáo trên thiết bị di động của Google. Nếu chạy thành công, bộ chuyển đổi sẽ
gọi MediationRewardedVideoAdListener.onInitializationSucceeded().
Nếu chạy không thành công, bộ chuyển đổi sẽ gọi
MediationRewardedVideoAdListener.onInitializationFailed(). Trong
trường hợp việc chạy bộ chuyển đổi không thành công, SDK quảng cáo trên thiết bị di động của Google
sẽ thử chạy lại bộ chuyển đổi mỗi lần thực hiện yêu cầu quảng cáo video có tặng thưởng.
Dưới đây là một ví dụ về hoạt động triển khai phương thức initialize():
@Override
public void initialize(Context context,
MediationAdRequest mediationAdRequest,
String unused,
MediationRewardedVideoAdListener listener,
Bundle serverParameters,
Bundle mediationExtras) {
// In this method you should initialize your SDK.
// The sample SDK requires activity context to initialize, so check
// that the context provided by the app is an activity context before
// initializing.
if (!(context instanceof Activity)) {
// Context not an Activity context, log the reason for failure and
// fail the initialization.
Log.d(TAG, "Sample SDK requires an Activity context to initialize");
listener.onInitializationFailed(
SampleAdapter.this, AdRequest.ERROR_CODE_INVALID_REQUEST);
return;
}
// Get the Ad Unit ID for the Sample SDK from serverParameters bundle.
String adUnit = serverParameters.getString(
MediationRewardedVideoAdAdapter.CUSTOM_EVENT_SERVER_PARAMETER_FIELD);
if (TextUtils.isEmpty(adUnit)) {
listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
return;
}
// Create a rewarded video event forwarder to forward the events from
// the Sample SDK to the Google Mobile Ads SDK.
mRewardedVideoEventForwarder =
new SampleMediationRewardedVideoEventForwarder(listener, SampleAdapter.this);
// Initialize the Sample SDK.
SampleRewardedVideo.initialize((Activity) context, adUnit, mRewardedVideoEventForwarder);
}
public class SampleMediationRewardedVideoEventForwarder extends SampleRewardedVideoAdListener {
...
@Override
public void onRewardedVideoInitialized() {
super.onRewardedVideoInitialized();
mIsInitialized = true;
mMediationRewardedVideoAdListener.onInitializationSucceeded(mSampleAdapter);
}
@Override
public void onRewardedVideoInitializationFailed(SampleErrorCode error) {
super.onRewardedVideoInitializationFailed(error);
mIsInitialized = false;
mMediationRewardedVideoAdListener.onInitializationFailed(
mSampleAdapter, getAdMobErrorCode(error));
}
}
Trả về trạng thái chạy
Phương thức isInitialized() của bộ chuyển đổi sẽ trả về giá trị false cho đến khi
bộ chuyển đổi thực hiện lệnh gọi đầu tiên tới
MediationRewardedVideoAdListener.onInitializationSucceeded(). Khi đó,
phương thức này sẽ luôn trả về giá trị true (như được trình bày bên dưới):
@Override
public boolean isInitialized() {
return mRewardedVideoEventForwarder != null && mRewardedVideoEventForwarder.isInitialized();
}
Tải video có tặng thưởng
Sau khi bộ chuyển đổi gọi phương thức
MediationRewardedVideoAdListener.onInitializationSucceeded(),
SDK quảng cáo trên thiết bị di động của Google có thể gọi phương thức loadAd() của
bộ chuyển đổi. Phương thức này sẽ yêu cầu một video có tặng thưởng và gọi
MediationRewardedVideoAdListener.onAdLoaded() sau khi có video có tặng thưởng để
hiển thị. Nếu không có video nào, bộ chuyển đổi sẽ gọi
MediationRewardedVideoAdListener.onAdFailedToLoad().
Đối với video có tặng thưởng, nhiều mạng quảng cáo triển khai API khi không có khái niệm về
yêu cầu quảng cáo. Sau khi đã chạy mạng quảng cáo, bạn có thể kiểm tra xem liệu có
khoảng không quảng cáo nào cho người dùng hiện tại hay không và quảng cáo đã sẵn sàng hay chưa. Nếu đáp ứng tiêu chí này,
bạn có thể hiển thị quảng cáo cho người dùng. Dưới đây là một ví dụ về hoạt động triển khai
loadAd() cho một mạng quảng cáo như vậy:
@Override
public void loadAd(MediationAdRequest mediationAdRequest,
Bundle serverParameters,
Bundle mediationExtras) {
if (SampleRewardedVideo.isAdAvailable()) {
// Ad already available, use the forwarder to send a success callback
// to AdMob.
mRewardedVideoEventForwarder.onAdLoaded();
} else {
// No ad available, use the forwarder to send a failure callback.
mRewardedVideoEventForwarder.onAdFailedToLoad();
}
}
Trong yêu cầu quảng cáo đầu tiên, loadAd() có thể được gọi trên bộ chuyển đổi ngay
sau khi bộ chuyển đổi gọi
phương thức MediationRewardedVideoAdListener.onInitializationSucceeded(). Nếu
một mạng quảng cáo vẫn đang tải quảng cáo tại thời điểm này, việc ngay lập tức báo cáo
một quảng cáo không thể tải có thể dẫn đến khả năng cao là yêu cầu quảng cáo video có tặng thưởng ban đầu đó
không được thực hiện. Trong trường hợp này, các bộ chuyển đổi nên theo dõi
thời điểm tải quảng cáo và hoãn việc phản hồi cho SDK quảng cáo trên thiết bị di động của Google
cho đến khi quảng cáo đã tải thành công hoặc không thể tải.
SDK quảng cáo trên thiết bị di động của Google có đặt thời gian chờ phòng trường hợp bộ chuyển đổi
phản hồi không đủ nhanh.
Hiển thị video có tặng thưởng
SDK quảng cáo trên thiết bị di động của Google có thể gọi phương thức showVideo() của bộ chuyển đổi
bất cứ lúc nào sau khi bộ chuyển đổi thông báo cho SDK quảng cáo trên thiết bị di động của Google về việc tải quảng cáo
thành công. Phương thức showVideo() sẽ chỉ được gọi một lần cho mỗi
lần gọi lại loadAd() thành công. Sau khi gọi phương thức này, bộ chuyển đổi
sẽ phát video có tặng thưởng.
@Override
public void showVideo() {
// Show the rewarded video ad.
if (SampleRewardedVideo.isAdAvailable()) {
// Rewarded video ad available, show ad.
SampleRewardedVideo.showAd();
} else {
// Show ad will only be called if the adapter sends back an ad
// loaded callback in response to a loadAd request. If for any
// reason the adapter is not ready to show an ad after sending
// an ad loaded callback, log a warning.
Log.w(TAG, "No ads to show.");
}
}
Xác định phần thưởng
Khi sẵn sàng tặng thưởng cho người dùng, bộ chuyển đổi phải tạo một đối tượng
phù hợp với giao diện RewardItem. Dưới đây là một ví dụ về hoạt động triển khai
RewardItem:
/**
* A {@link RewardItem} that maps the sample reward type and reward amount.
*/
public class SampleRewardItem implements RewardItem {
private String mRewardType;
private int mRewardAmount;
/**
* Creates a {@link SampleRewardItem}.
*
* @param rewardType the sample reward type.
* @param rewardAmount the sample reward amount.
*/
public SampleRewardItem(String rewardType, int rewardAmount) {
this.mRewardType = rewardType;
this.mRewardAmount = rewardAmount;
}
@Override
public String getType() {
return mRewardType;
}
@Override
public int getAmount() {
return mRewardAmount;
}
}
Để thông báo cho SDK quảng cáo trên thiết bị di động của Google biết rằng người dùng sẽ được tặng thưởng, bộ chuyển đổi
cần phải gọi
phương thức MediationRewardedVideoAdListener.onRewarded() bằng cách sử dụng một bản sao của RewardItem làm đối số.
Chuyển tiếp các sự kiện quảng cáo đến SDK quảng cáo trên thiết bị di động của Google
Bộ chuyển đổi của bạn bắt buộc phải thông báo cho SDK quảng cáo trên thiết bị di động của Google khi có bất kỳ sự kiện quảng cáo nào sau đây xảy ra:
| Phương thức MediationRewardedVideoAdListener | Thời điểm gọi |
|---|---|
| onAdOpened() | Một lớp phủ toàn màn hình che khuất nội dung ứng dụng |
| onVideoStarted() | Quảng cáo video bắt đầu |
| onAdClicked() | Người dùng nhấp vào quảng cáo video |
| onAdLeftApplication() | Người dùng rời khỏi ứng dụng do quảng cáo video (ví dụ: để truy cập vào trình duyệt) |
| onRewarded() | Quảng cáo video tặng thưởng cho người dùng |
| onAdClosed() | Quảng cáo video bị đóng |
Dưới đây là một ví dụ về hoạt động triển khai việc chuyển tiếp quảng cáo đến SDK quảng cáo trên thiết bị di động của Google:
/**
* A SampleRewardedVideoAdListener that forwards events to AdMob mediation's
* link.
*/
public class SampleMediationRewardedVideoEventForwarder extends SampleRewardedVideoAdListener {
private MediationRewardedVideoAdListener mMediationRewardedVideoAdListener;
private SampleAdapter mSampleAdapter;
private boolean mIsInitialized;
/**
* Creates a new SampleMediationRewardedVideoEventForwarder.
*
* @param listener An AdMob Mediation MediationRewardedVideoAdListener that should
* receive forwarded events.
* @param sampleAdapter A SampleAdapter mediation adapter.
*/
public SampleMediationRewardedVideoEventForwarder(MediationRewardedVideoAdListener listener,
SampleAdapter sampleAdapter) {
this.mMediationRewardedVideoAdListener = listener;
this.mSampleAdapter = sampleAdapter;
}
/**
* @return whether or not the Sample SDK is initialized.
*/
public boolean isInitialized() {
return mIsInitialized;
}
@Override
public void onRewardedVideoInitialized() {
super.onRewardedVideoInitialized();
mIsInitialized = true;
mMediationRewardedVideoAdListener.onInitializationSucceeded(mSampleAdapter);
}
@Override
public void onRewardedVideoInitializationFailed(SampleErrorCode error) {
super.onRewardedVideoInitializationFailed(error);
mIsInitialized = false;
mMediationRewardedVideoAdListener.onInitializationFailed(
mSampleAdapter, getAdMobErrorCode(error));
}
@Override
public void onAdRewarded(final String rewardType, final int amount) {
super.onAdRewarded(rewardType, 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
* front end. Document this asking the publisher to override the
* reward value on AdMob's front end.
*
* 2. Send a reward item with default values for the type (an empty
* string "") and reward amount (1).
*/
mMediationRewardedVideoAdListener.onRewarded(
mSampleAdapter, new SampleRewardItem(rewardType, amount));
}
@Override
public void onAdClicked() {
super.onAdClicked();
mMediationRewardedVideoAdListener.onAdClicked(mSampleAdapter);
}
@Override
public void onAdFullScreen() {
super.onAdFullScreen();
mMediationRewardedVideoAdListener.onAdOpened(mSampleAdapter);
// Only send video started here if your SDK starts video
// immediately after the ad has been opened/is fullscreen.
mMediationRewardedVideoAdListener.onVideoStarted(mSampleAdapter);
}
@Override
public void onAdClosed() {
super.onAdClosed();
mMediationRewardedVideoAdListener.onAdClosed(mSampleAdapter);
}
/**
* Forwards the ad loaded event to AdMob SDK. The Sample SDK does not
* have an ad loaded callback, the adapter calls this method if an ad
* is available when loadAd is called.
*/
protected void onAdLoaded() {
mMediationRewardedVideoAdListener.onAdLoaded(mSampleAdapter);
}
/**
* Forwards the ad failed event to AdMob SDK. The Sample SDK does not
* have an ad failed to load callback, the adapter calls this method
* to forward the failure callback.
*/
protected void onAdFailedToLoad() {
mMediationRewardedVideoAdListener.onAdFailedToLoad(
mSampleAdapter, AdRequest.ERROR_CODE_NO_FILL);
}
/**
* Converts SampleErrorCode into an AdMob SDK's AdRequest error code.
*
* @param errorCode a Sample SDK error code.
* @return an AdMob SDK readable error code.
*/
private int getAdMobErrorCode(SampleErrorCode errorCode) {
switch (errorCode) {
case BAD_REQUEST:
return AdRequest.ERROR_CODE_INVALID_REQUEST;
case NETWORK_ERROR:
return AdRequest.ERROR_CODE_NETWORK_ERROR;
case NO_INVENTORY:
return AdRequest.ERROR_CODE_NO_FILL;
case UNKNOWN:
default:
return AdRequest.ERROR_CODE_INTERNAL_ERROR;
}
}
}
Mạng quảng cáo của bên thứ ba có thể có các trình nghe sự kiện quảng cáo cho mạng quảng cáo của họ.
Sự kiện quảng cáo từ SDK của bên thứ ba có thể được liên kết tới sự kiện quảng cáo tương ứng cho
MediationRewardedVideoAdListener có trong phương thức initialize()
của bộ chuyển đổi và được gọi vào thời điểm thích hợp.
Thông báo về việc thay đổi ngữ cảnh
Bộ chuyển đổi có thể triển khai OnContextChangedListener (không bắt buộc) để nhận
thông báo khi ngữ cảnh hiện tại thay đổi. Phương thức onContextChanged()
được gọi khi ngữ cảnh hiện tại của đối tượng RewardedVideoAd được
cập nhật. Bạn có thể truy cập vào ngữ cảnh mới của hoạt động như được hiển thị dưới đây:
@Override
public void onContextChanged(Context context) {
if (context instanceof Activity) {
SampleRewardedVideo.setCurrentActivity((Activity) context);
}
}
Thông số nhắm mục tiêu bổ sung
Mã
MediationAdRequest
chứa một số thông tin nhắm mục tiêu phổ biến mà bạn có thể sử dụng để nhắm mục tiêu quảng cáo,
chẳng hạn như:
Chấp nhận các thông số tùy chỉnh cho bộ chuyển đổi
Mạng quảng cáo mà bộ chuyển đổi đang dàn xếp có thể hỗ trợ các thông số nhắm mục tiêu bổ sung
hoặc các mục nhập không có trong thông tin được cung cấp trong
MediationAdRequest. Nếu điều này đúng với bộ chuyển đổi của bạn, bạn có thể yêu cầu nhà xuất bản
cung cấp một gói thông tin cho mạng của mình. Gói này được chuyển đến
bộ chuyển đổi của bạn trong cả hai phương thức initialize() và loadAd().
Ví dụ: sau đây là cách nhà xuất bản có thể cung cấp gói cho
bộ chuyển đổi SampleAdapter:
Bundle bundle = new Bundle();
bundle.putBoolean("ShouldAddAwesomeSauce", true);
AdRequest adRequest = new AdRequest.Builder()
.addNetworkExtrasBundle(SampleAdapter.class, bundle)
.build();
Để giúp các nhà phát triển dễ dàng tạo gói này cho bạn, bạn nên thêm một lớp tiện lợi vào bộ chuyển đổi để giúp nhà xuất bản tạo một gói cho bộ chuyển đổi của bạn:
public static final class MediationExtrasBundleBuilder {
// Keys to add and obtain the extra parameters from the bundle.
private static final String KEY_AWESOME_SAUCE = "awesome_sauce";
/**
* An extra value used to populate the "ShouldAddAwesomeSauce" property
* of the Sample SDK's ad request.
*/
private boolean mShouldAddAwesomeSauce;
public MediationExtrasBundleBuilder setShouldAddAwesomeSauce(
boolean shouldAddAwesomeSauce) {
this.mShouldAddAwesomeSauce = shouldAddAwesomeSauce;
return MediationExtrasBundleBuilder.this;
}
public MediationExtrasBundleBuilder setIncome(int income) {
this.mIncome = income;
return MediationExtrasBundleBuilder.this;
}
public Bundle build() {
Bundle extras = new Bundle();
extras.putInt(KEY_INCOME, mIncome);
return extras;
}
}
Lớp tiện lợi này cung cấp API rõ ràng hơn để nhà phát triển tạo một gói cho mạng của bạn:
Bundle sampleAdNetworkBundle =
new SampleAdapter.MediationExtrasBundleBuilder().setShouldAddAwesomeSauce(true).build();