Phát triển bộ chuyển đổi dàn xếp mạng quảng cáo

Lưu ý: Khi sử dụng SDK Quảng cáo của Google trên thiết bị di động cùng với Dịch vụ dàn xếp, bạn phải tuân thủ Điều khoản dịch vụ dàn xếp.

Hướng dẫn này dành cho các mạng quảng cáo đang tìm cách tạo bộ chuyển đổi dàn xếp. Nếu bạn là nhà xuất bản, hãy xem hướng dẫn dàn xếp dành cho nhà xuất bản.

Bộ chuyển đổi mạng quảng cáo là lớp giao tiếp giữa mạng quảng cáo của bạn và tính năng Dàn xếp quảng cáo trên thiết bị di động của Google.

Bộ chuyển đổi này chịu trách nhiệm triển khai MediationBannerAdapter để hỗ trợ quảng cáo biểu ngữ và MediationInterstitialAdapter để hỗ trợ quảng cáo xen kẽ. Sự kiện này cũng phải gọi các lệnh gọi lại trong MediationBannerListener và MediationInterstitialListener vào thời điểm thích hợp để thông báo cho nền tảng Dàn xếp quảng cáo trên thiết bị di động của Google về những sự kiện này. Các sự kiện này cũng có thể được chuyển tiếp đến nhà phát triển.

Mạng quảng cáo mẫu

Hướng dẫn này trình bày cách tạo bộ chuyển đổi cho Mạng quảng cáo mẫu. Mạng quảng cáo mẫu chứa các lớp đại diện cho các lớp được hầu hết các mạng quảng cáo cung cấp sau đây:

class SampleAdView {
    public SampleAdView(Context context);
    public void setSize(SampleAdSize size);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void destroy();
}

class SampleAdSize {
    public SampleAdSize(int width, int height);
    public int getWidth();
    public int getHeight();
}

class SampleAdRequest {
    public SampleAdRequest();
    public void setKeywords(Set<String> keywords);
    public void setTestMode(boolean useTesting);
}

class SampleAdListener {
    public void onAdFetchSucceeded();
    public void onAdFetchFailed(SampleErrorCode code);
    public void onAdFullScreen();
    public void onAdClosed();
}

enum SampleErrorCode {
    UNKNOWN,
    BAD_REQUEST,
    NETWORK_ERROR,
    NO_INVENTORY
}

class SampleInterstitial {
    public SampleInterstitial(Context context);
    public void setAdUnit(String sampleAdUnit);
    public void setAdListener(SampleAdListener listener);
    public void fetchAd(SampleAdRequest request);
    public void show();
    public void destroy();
}

Xem quy trình triển khai SDK hoàn chỉnh để biết thêm thông tin về các lớp này.

Triển khai bộ chuyển đổi biểu ngữ

Để triển khai bộ chuyển đổi hỗ trợ quảng cáo biểu ngữ, hãy tạo một lớp triển khai MediationBannerAdapter.

public class SampleAdapter implements MediationBannerAdapter {
    @Override
    public void requestBannerAd(
            Context context,
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View getBannerView() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

Trước khi tìm hiểu sâu hơn về cách triển khai MediationBannerAdapter, hãy thảo luận về các thông số máy chủ, phần phụ dàn xếp và cách truyền các giá trị này đến bộ chuyển đổi.

Tham số máy chủ

Mạng quảng cáo của bạn có thể cần(các) giá trị nhận dạng để xác định một nhà xuất bản. Ví dụ: Mạng quảng cáo mẫu chỉ yêu cầu một đơn vị quảng cáo. Các tham số bắt buộc này được cung cấp cho bạn trong gói serverParameters bên trong requestBannerAd(). Trong quá trình phát triển, bạn có thể giả định rằng gói đã được điền sẵn các khoá mà bạn cần:

private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

@Override
public void requestBannerAd(
        Context context,
        MediationBannerListener listener,
        Bundle serverParameters,
        AdSize adSize,
        MediationAdRequest mediationAdRequest,
        Bundle mediationExtras) {
    String adUnit = serverParameters.getString(SAMPLE_AD_UNIT_KEY);
    ...
}

AdMob sẽ gửi cho bạn một bảng câu hỏi hỏi xem bạn cần những thông số máy chủ nào từ nhà xuất bản để yêu cầu và phân phát quảng cáo. AdMob sẽ sử dụng thông tin đầu vào đó để định cấu hình mạng của bạn trong giao diện người dùng AdMob. Ảnh chụp màn hình dưới đây cho thấy rằng APID là bắt buộc đối với Millennial Media và bắt buộc phải có ID ứng dụng cho NavHost.

AdMob sẽ sử dụng thông tin này để điền gói serverParameters khi tạo thực thể cho bộ chuyển đổi của bạn.

Xem bài viết này để biết thêm thông tin về cách nhà xuất bản sẽ định cấu hình mạng quảng cáo dàn xếp.

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ư:

• getKeywords()
• isTesting()
• taggedForChildDirectedTreatment()

Phần phụ dàn xếp

Nếu mạng quảng cáo của bạn hỗ trợ thông tin nhắm mục tiêu mà MediationAdRequest không cung cấp, thì nhà phát triển ứng dụng có thể chuyển một gói mediationExtras dành riêng đến mạng của bạn. Tính năng Dàn xếp cung cấp một ví dụ về cách chuyển phần phụ dàn xếp.

Để giúp các nhà phát triển tuỳ ý truyền thông tin này dễ dàng hơn, bạn có thể cung cấp một lớp trình tạo gói trong bộ chuyển đổi. Giả sử mạng của bạn hỗ trợ truyền giá trị thu nhập. Bạn có thể thêm một lớp trình tạo trong bộ chuyển đổi để đặt thu nhập:

public static final class BundleBuilder {
    private int income;

    public BundleBuilder setIncome(int income) {
        this.income = income;
        return this;
    }

    public Bundle build() {
        Bundle bundle = new Bundle();
        bundle.putInt("income", income);
        return bundle;
    }
}

Lớp này cung cấp một API không có lỗi để nhà phát triển tạo một gói cho mạng của bạn:

Bundle sampleAdapterBundle =
        new SampleAdapter.BundleBuilder().setIncome(100000).build();

Lưu ý: MediationExtras sẽ rỗng nếu nhà phát triển không cung cấp thông tin bổ sung nào cho mạng của bạn.

requestBannerAd()

Giờ đây, bạn đã được giới thiệu về các thông số máy chủ và phần phụ dàn xếp, chúng ta có thể sử dụng các thông số này để tạo MediationBannerAdapter.

Phương thức requestBannerAd() được gọi ngay sau khi bộ chuyển đổi được tạo thực thể. Đây là nơi bạn nên tạo chế độ xem quảng cáo và đưa ra yêu cầu quảng cáo biểu ngữ.

Hoạt động triển khai requestBannerAd() cho Mạng quảng cáo mẫu sẽ có dạng như sau:

public class SampleAdMobAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";
    private SampleAdView sampleAdView;

    @Override
    public void requestBannerAd(
            Context context, // May be an application context.
            MediationBannerListener listener,
            Bundle serverParameters,
            AdSize adSize,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleAdView = new SampleAdView(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleAdView.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleAdView.setSize(
                new SampleAdSize(adSize.getWidth(),adSize.getHeight()));

        sampleAdView.setAdListener(
                new SampleBannerEventForwarder(listener, this));

        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleAdView.fetchAd(request);
    }
}

Đừng giả định rằng thông số ngữ cảnh thuộc loại Activity. Tùy thuộc vào hoạt động triển khai của nhà xuất bản, tính năng Dàn xếp quảng cáo trên thiết bị di động của Google có thể chuyển tiếp một ngữ cảnh ứng dụng đến bộ chuyển đổi. Nếu bộ chuyển đổi của bạn không thể xử lý ngữ cảnh ứng dụng, bạn nên gọi onAdFailedToLoad() kèm theo mã lỗi AdRequest.ERROR_CODE_INVALID_REQUEST.

Lệnh gọi lại MediationBannerListener

Bạn nên lưu MediationBannerListener được cung cấp trong requestBannerAd() để có thể chuyển tiếp các sự kiện quảng cáo trở về tính năng Dàn xếp quảng cáo trên thiết bị di động của Google. Mỗi lệnh gọi lại phải được gọi vào thời điểm thích hợp trong vòng đời của quảng cáo:

Phương thức	Thời gian gọi
onAdLoaded()	Đã yêu cầu quảng cáo biểu ngữ thành công.
onAdFailedToLoad()	Yêu cầu quảng cáo biểu ngữ không thành công.
onAdClicked()	Đã nhấp vào biểu ngữ.
onAdOpened()	Quảng cáo biểu ngữ đang hiển thị chế độ xem toàn màn hình.
onAdClosed()	Người dùng quay lại ứng dụng sau khi nhấp vào một biểu ngữ.
onAdLeftApplication()	Quảng cáo biểu ngữ khiến người dùng rời khỏi ứng dụng.

Bộ chuyển đổi mạng quảng cáo mẫu sẽ tạo một lớp có tên là SampleBannerEventForwarder để xử lý hoạt động chuyển tiếp sự kiện:

public class SampleBannerEventForwarder extends SampleAdListener {
    private MediationBannerListener mediationListener;
    private SampleAdapter adapter;

    public SampleBannerEventForwarder(
            MediationBannerListener listener, SampleAdapter adapter) {
        this.mediationListener = listener;
        this.adapter = adapter;
    }

    @Override
    public void onAdFetchSucceeded() {
        mediationListener.onAdLoaded(adapter);
    }

    @Override
    public void onAdFetchFailed(SampleErrorCode errorCode) {
        switch(errorCode) {
            case UNKNOWN:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INTERNAL_ERROR);
                break;
            case BAD_REQUEST:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_INVALID_REQUEST);
                break;
            case NETWORK_ERROR:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NETWORK_ERROR);
                break;
            case NO_INVENTORY:
                mediationListener.onAdFailedToLoad(adapter, AdRequest.ERROR_CODE_NO_FILL);
                break;
        }
    }

    @Override
    public void onAdFullScreen() {
        mediationListener.onAdClicked(adapter);
        mediationListener.onAdOpened(adapter);
        mediationListener.onAdLeftApplication(adapter);
    }

    @Override
    public void onAdClosed() {
        mediationListener.onAdClosed(adapter);
    }
}

Hãy lưu ý cách Bộ chuyển đổi mạng quảng cáo mẫu đã gửi onAdClicked, onAdOpened và onAdLeftApplication trong cùng một lệnh gọi lại. Mặc dù các lệnh gọi lại cho mạng của bạn có thể không khớp chính xác với lệnh gọi lại mà Quảng cáo trên thiết bị di động của Google yêu cầu, nhưng trách nhiệm của bộ chuyển đổi là cung cấp thông tin liên kết hợp lý.

getBannerView

Sau khi bạn gọi MediationBannerListener.onAdLoaded(), tính năng dàn xếp sẽ gọi getBannerView() để giúp hiển thị chế độ xem biểu ngữ của mạng quảng cáo trên màn hình. Bạn chỉ cần trả về chế độ xem biểu ngữ mà bạn đã tạo trong requestBannerAd():

@Override
public View getBannerView() {
    return sampleAdView;
}

Các sự kiện trong vòng đời hoạt động

Tính năng dàn xếp sẽ thông báo cho bộ chuyển đổi về các sự kiện hoạt động onPause() và onResume() nếu nhà phát triển ứng dụng thông báo cho nền tảng dàn xếp về các sự kiện đó. Thực hiện mọi thao tác tạm dừng và tiếp tục biểu ngữ cần thiết:

@Override
public void onPause() {
}

@Override
public void onResume() {
}

Mạng quảng cáo mẫu không có lệnh gọi tạm dừng hoặc tiếp tục, vì vậy, mạng này cung cấp phương thức triển khai trống.

Tính năng dàn xếp sẽ cố gắng gọi onDestroy() khi bộ chuyển đổi sắp bị huỷ. Thực hiện mọi thao tác dọn dẹp cần thiết tại đây:

@Override
public void onDestroy() {
    if (sampleAdView != null) {
        sampleAdView.destroy();
    }
}

Biểu ngữ thông minh

SDK quảng cáo trên thiết bị di động của Google hỗ trợ kích thước quảng cáo biểu ngữ thông minh, có chiều rộng đầy đủ và chiều cao thay đổi tùy thuộc vào kích thước của thiết bị.

Để có được kích thước quảng cáo chính xác của biểu ngữ thông minh, bộ chuyển đổi nên sử dụng adSize.getWidthInPixels(context) để lấy chiều rộng và adSize.getHeightInPixels(context) thay vì adSize.getHeight() để lấy chiều cao. Sau đó, chia cho mật độ của thiết bị:

int widthInPixels = adSize.getWidthInPixels(context);
int heightInPixels = adSize.getHeightInPixels(context);
DisplayMetrics displayMetrics = Resources.getSystem().getDisplayMetrics();
int widthInDp = Math.round(widthInPixels / displayMetrics.density);
int heightInDp = Math.round(heightInPixels / displayMetrics.density);

Sau đó, bạn có thể sử dụng widthInDp và heightInDp làm kích thước khi đưa ra yêu cầu quảng cáo.

Lưu ý: Không sử dụng adSize.getWidth() hoặc adSize.getHeight() để lấy kích thước quảng cáo. Biểu ngữ thông minh được biểu thị bằng một hằng số có kích thước đặc biệt nội bộ, do đó, adSize.getWidth() và adSize.getHeight() sẽ trả về giá trị âm.

Vậy là xong! Bây giờ, bạn đã có bộ chuyển đổi dàn xếp đang hoạt động cho quảng cáo biểu ngữ! Để tham khảo, bạn có thể xem hoạt động triển khai đầy đủ của SampleAdapter tại đây.

Triển khai bộ chuyển đổi quảng cáo xen kẽ

Việc triển khai bộ chuyển đổi cho quảng cáo xen kẽ tương tự như quảng cáo biểu ngữ. Để triển khai bộ chuyển đổi hỗ trợ quảng cáo xen kẽ, hãy tạo một lớp triển khai MediationInterstitialAdapter:

public class SampleAdapter implements MediationInterstitialAdapter {
    @Override
    public void requestInterstitialAd(
            Context context,
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {}

    @Override
    public View showInterstitial() {}

    @Override
    public void onDestroy() {}

    @Override
    public void onPause() {}

    @Override
    public void onResume() {}
}

Nếu bộ chuyển đổi của bạn cũng hỗ trợ quảng cáo biểu ngữ, thì bạn có thể sử dụng cùng một lớp bộ chuyển đổi để triển khai cả hai giao diện.

Bây giờ, hãy tự tìm hiểu phần phụ dàn xếp và thông số máy chủ trước khi tiếp tục triển khai MediationInterstitialAdapter.

Thông số máy chủ (quảng cáo xen kẽ)

Xem mục Thông số máy chủ biểu ngữ.

Thông số nhắm mục tiêu bổ sung (quảng cáo xen kẽ)

Xem mục Thông số nhắm mục tiêu biểu ngữ bổ sung.

Phần phụ dàn xếp (quảng cáo xen kẽ)

Xem mục Phần phụ dàn xếp biểu ngữ.

requestInterstitialAd

Phương thức requestInterstitialAd() được gọi ngay sau khi bộ chuyển đổi được tạo thực thể. Đây là nơi bạn nên tạo quảng cáo xen kẽ và đưa ra yêu cầu quảng cáo xen kẽ.

Hoạt động triển khai requestInterstitialAd() cho Mạng quảng cáo mẫu sẽ trông giống như sau:

public class SampleAdapter implements MediationBannerAdapter {
    private static final String SAMPLE_AD_UNIT_KEY = "ad_unit";

    private SampleInterstitial sampleInterstitial;

    @Override
    public void requestInterstitialAd(
            Context context, // May be an application context.
            MediationInterstitialListener listener,
            Bundle serverParameters,
            MediationAdRequest mediationAdRequest,
            Bundle mediationExtras) {
        sampleInterstitial = new SampleInterstitial(context);

        if (serverParameters.containsKey(SAMPLE_AD_UNIT_KEY)) {
            sampleInterstitial.setAdUnit(serverParameters.getString(SAMPLE_AD_UNIT_KEY));
        } else {
            listener.onAdFailedToLoad(this, AdRequest.ERROR_CODE_INVALID_REQUEST);
        }

        sampleInterstitial.setAdListener(
                new SampleInterstitialEventForwarder(listener, this));

        // Make an ad request.
        SampleAdRequest request = new SampleAdRequest();
        request.setTestMode(mediationAdRequest.isTesting());
        request.setKeywords(mediationAdRequest.getKeywords());
        sampleInterstitial.fetchAd(request);
    }
}

Đừng giả định rằng thông số ngữ cảnh thuộc loại Hoạt động! Tính năng Dàn xếp quảng cáo trên thiết bị di động của Google chuyển tiếp ngữ cảnh do nhà phát triển ứng dụng chuyển và có thể ngữ cảnh ứng dụng đã được chuyển. Nếu bộ chuyển đổi của bạn không thể xử lý ngữ cảnh ứng dụng, bạn nên gọi onAdFailedToLoad kèm theo mã lỗi AdRequest.ERROR_CODE_INVALID_REQUEST.

Lệnh gọi lại MediationInterstitialListener

Bạn nên lưu MediationInterstitialListener được cung cấp trong requestInterstitialAd để có thể chuyển tiếp các sự kiện quảng cáo trở lại tính năng Dàn xếp quảng cáo trên thiết bị di động của Google. Mỗi lệnh gọi lại phải được gọi vào thời điểm thích hợp trong vòng đời của quảng cáo:

Phương thức	Thời gian gọi
onAdLoaded	Yêu cầu quảng cáo xen kẽ thành công.
onAdFailedToLoad	Yêu cầu quảng cáo xen kẽ không thành công.
onAdOpened	Quảng cáo xen kẽ đang hiển thị.
onAdClosed	Quảng cáo xen kẽ đã đóng.
onAdLeftApplication	Quảng cáo xen kẽ khiến người dùng rời khỏi ứng dụng.

showInterstitial

Sau khi gọi MediationInterstitialListener.onAdLoaded(), bạn phải đợi hiển thị quảng cáo xen kẽ cho đến khi showInterstitial() được gọi. Nhà phát triển ứng dụng sẽ quyết định thời điểm hiển thị quảng cáo xen kẽ, có thể tối đa vài phút sau khi được yêu cầu.

Việc triển khai showInterstitial() khá đơn giản. Chỉ hiển thị đối tượng quảng cáo xen kẽ của bạn:

@Override
public void showInterstitial() {
    sampleInterstitial.show();
}

Sự kiện vòng đời hoạt động (quảng cáo xen kẽ)

Xem mục Sự kiện vòng đời hoạt động của biểu ngữ.

Sau khi triển khai các sự kiện trong vòng đời hoạt động, bộ chuyển đổi dàn xếp của bạn đã sẵn sàng xử lý quảng cáo xen kẽ! Để tham khảo, bạn có thể xem hoạt động triển khai đầy đủ của SampleAdapter tại đây.

Câu hỏi thường gặp

Tôi phải làm gì nếu bộ chuyển đổi của tôi chỉ hỗ trợ quảng cáo biểu ngữ hoặc quảng cáo xen kẽ, chứ không hỗ trợ cả hai?

Nếu bộ chuyển đổi của bạn chỉ hỗ trợ quảng cáo biểu ngữ thì bạn chỉ cần triển khai giao diện MediationBannerAdapter. Nếu bộ chuyển đổi của bạn chỉ hỗ trợ quảng cáo xen kẽ thì bạn chỉ cần triển khai giao diện MediationInterstitialAdapter.