Triển khai bộ chuyển đổi video có tặng thưởng

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

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()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();