Phát triển bộ chuyển đổi đặt giá thầu

Hướng dẫn này dành cho các mạng quảng cáo muốn xây dựng bộ chuyển đổi đặt giá thầu để tham gia đặt giá thầu theo thời gian thực (RTB) trong quy trình dàn xếp của Google. Nếu bạn là nhà xuất bản, hãy xem hướng dẫn về dàn xếp cho nhà xuất bản.

Bộ chuyển đổi đặt giá thầu là phần phía máy khách của quá trình tích hợp. Bộ chuyển đổi cho phép SDK mạng quảng cáo của bạn giao tiếp với Google Mobile Ads SDK (Legacy) để tải quảng cáo do bên đặt giá thầu của bạn phân phát.

Để tính năng đặt giá thầu hoạt động đúng cách, bộ chuyển đổi của bạn cần xử lý việc khởi chạy, thu thập tín hiệu, tải quảng cáo và chuyển tiếp các sự kiện trong vòng đời quảng cáo. Trong hướng dẫn này, chúng tôi sẽ hướng dẫn bạn cách triển khai bộ chuyển đổi để xử lý các thao tác này.

Quy trình làm việc của bộ chuyển đổi đặt giá thầu

Khởi chạy

Dưới đây là quy trình chi tiết của toàn bộ vòng đời yêu cầu-phản hồi-kết xuất của một bộ chuyển đổi:

Bộ chuyển đổi chịu trách nhiệm về các phần sau của quy trình:

  • Bước 4-7: Khởi chạy bộ chuyển đổi và gọi lại Google Mobile Ads SDK (Legacy) sau khi khởi chạy xong.

  • Bước 10-13: Thu thập tín hiệu từ SDK mạng quảng cáo để gửi đến bên đặt giá thầu của bạn nhằm tham gia vào yêu cầu RTB, đồng thời chuyển tiếp các tín hiệu đó đến SDK quảng cáo trên thiết bị di động của Google.

  • Bước 18-21: Nếu bên đặt giá thầu của bạn trả về giá thầu thắng, hãy tải quảng cáo theo phản hồi từ bên đặt giá thầu. Sau khi tải, hãy thông báo cho Google Mobile Ads SDK (Legacy) rằng quảng cáo đã được tải.

  • Bước 23 trở đi: Trong khi quảng cáo của bạn đang hiển thị, hãy thông báo cho Google Mobile Ads SDK về các sự kiện hiển thị và sự kiện nhấp chuột, cũng như các sự kiện quảng cáo khác xảy ra trong vòng đời hiển thị của quảng cáo.

Triển khai bộ chuyển đổi đặt giá thầu

Để tạo một bộ chuyển đổi đặt giá thầu cho Google Mobile Ads SDK (Legacy), bạn phải mở rộng lớp trừu tượng RtbAdapter. Các phần sau đây giải thích từng phương thức trừu tượng trong RtbAdapter.

getSDKVersionInfo()

Tại đây, bạn nên trả về phiên bản SDK của mình. Phiên bản này được chuyển đến bên đặt giá thầu của bạn trong yêu cầu OpenRTB.

Phương thức này yêu cầu bạn trả về một VersionInfo. Ví dụ dưới đây cho thấy cách bạn có thể chuyển đổi phiên bản chuỗi của SDK thành VersionInfo.

@Override
public VersionInfo getSDKVersionInfo() {
  // Get your SDK's version as a string. E.g. "1.2.3"
  // String versionString = YourSdk.getVersion();
  String splits[] = versionString.split("\\.");
  if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
   }

   String logMessage = String.format("Unexpected SDK version format: %s." +
           "Returning 0.0.0 for SDK version.", sdkVersion);
   Log.w(TAG, logMessage);
   return new VersionInfo(0, 0, 0);
}

getVersionInfo()

Tại đây, bạn nên trả về phiên bản của bộ chuyển đổi. Phiên bản này được chuyển đến bên đặt giá thầu của bạn trong yêu cầu OpenRTB.

Bộ chuyển đổi nguồn mở và được tạo phiên bản của Google sử dụng lược đồ phiên bản bộ chuyển đổi gồm 4 chữ số, nhưng VersionInfo chỉ cho phép 3 chữ số. Để giải quyết vấn đề này, bạn nên kết hợp hai chữ số cuối cùng vào phiên bản bản vá, như minh hoạ dưới đây.

@Override
public VersionInfo getVersionInfo() {
  // Get your adapters's version as a string. E.g. "1.2.3.0"
  String versionString = BuildConfig.VERSION_NAME;
  String splits[] = versionString.split("\\.");
  if (splits.length >= 4) {
      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);
    }

    String logMessage = String.format("Unexpected adapter version format: %s." +
                "Returning 0.0.0 for adapter version.", versionString);
    Log.w(TAG, logMessage);
    return new VersionInfo(0, 0, 0);
}

initialize()

Thời gian chờ: 30 giây

Phương thức initialize() là phương thức đầu tiên được gọi trong bộ chuyển đổi. Hàm này chỉ được gọi một lần cho mỗi phiên. Phương thức này cung cấp cho bạn danh sách các đối tượng MediationConfiguration đại diện cho danh sách đầy đủ các vị trí trong ứng dụng này được định cấu hình cho mạng quảng cáo của bạn; Bạn có thể lặp lại danh sách này để phân tích cú pháp thông tin xác thực cho từng vị trí và truyền dữ liệu có liên quan đến SDK của bạn để khởi chạy.

Sau khi SDK được khởi chạy và sẵn sàng nhận yêu cầu quảng cáo, hãy gọi phương thức onInitializationSucceeded() của InitializationCompleteCallback. Lệnh gọi lại này được chuyển tiếp đến nhà xuất bản ứng dụng để họ biết rằng họ có thể bắt đầu tải quảng cáo.

@Override
public void initialize(Context context,
    InitializationCompleteCallback initializationCompleteCallback,
    List<MediationConfiguration> mediationConfigurations) {
  // Initialize your ad network's SDK.
  ...

  // Invoke the InitializationCompleteCallback once initialization completes.
  initializationCompleteCallback.onInitializationSucceeded();
}

collectSignals()

Thời gian chờ: 1 giây

Mỗi lần nhà xuất bản yêu cầu quảng cáo, một thực thể mới của RtbAdapter sẽ được tạo và phương thức collectSignals() sẽ được gọi. Thực thể này của RtbAdapter sẽ được dùng trong suốt thời gian của vòng đời yêu cầu quảng cáo, phản hồi và hiển thị cho quảng cáo đó. Phương thức collectSignals() cho phép bộ chuyển đổi cung cấp tín hiệu từ thiết bị để gửi đến bên đặt giá thầu trong một yêu cầu OpenRTB.

collectSignals() được gọi trên một luồng nền. Google Mobile Ads SDK (Legacy) đồng thời yêu cầu tín hiệu từ tất cả các bộ chuyển đổi tham gia đặt giá thầu. Vui lòng tôn trọng và hạn chế các lệnh gọi đến luồng giao diện người dùng trong thời gian này. Mọi công việc nặng mà bộ chuyển đổi hoặc SDK của bạn cần thực hiện để thu thập tín hiệu phải được thực hiện trong phương thức initialize() và được lưu vào bộ nhớ đệm.

Sau khi bạn đã chuẩn bị sẵn tín hiệu, hãy gọi lệnh gọi lại onSuccess() bằng tín hiệu đã mã hoá.

Dưới đây là ví dụ về cách triển khai:

@Override
public void collectSignals(RtbSignalData rtbSignalData,
                           SignalCallbacks signalCallbacks) {
  String signals = YourSdk.getSignals();
  signalCallbacks.onSuccess(signals);
}

Nếu bộ chuyển đổi không thu thập được tín hiệu, hãy gọi signalCallbacks.onFailure() kèm theo một chuỗi giải thích lỗi đã xảy ra.

Triển khai các phương thức tải quảng cáo

Thời gian chờ: 10 giây

Nếu bên đặt giá thầu trả về giá thầu thắng, thì Google Mobile Ads SDK (Legacy) sẽ gọi bộ chuyển đổi của bạn để tải quảng cáo thắng, đồng thời chuyển cho bạn mọi dữ liệu mà bên đặt giá thầu trả về mà SDK của bạn cần để tải quảng cáo đó.

Phương thức tải chính xác được gọi phụ thuộc vào định dạng quảng cáo mà yêu cầu này nhắm đến:

Định dạng quảng cáo Phương thức tải
Biểu ngữ loadBannerAd()
Quảng cáo xen kẽ loadInterstitialAd()
Được thưởng loadRewardedAd()

Hãy triển khai các phương thức này cho những định dạng quảng cáo mà bộ chuyển đổi của bạn hỗ trợ.

Phương thức tải được gọi trên luồng giao diện người dùng, trên cùng một thực thể của bộ chuyển đổi mà bạn đã cung cấp tín hiệu. Phương thức này cung cấp cho bạn các tham số sau:

  • MediationAdConfiguration, chứa các tham số mà SDK của bạn cần để tải quảng cáo cho giá thầu thắng, chẳng hạn như giá thầu phản hồi và mọi thông tin xác thực mà nhà xuất bản đã định cấu hình trong giao diện người dùng AdMob.

  • Một đối tượng MediationAdLoadCallback dùng để thông báo cho Google Mobile Ads SDK (Legacy) khi quá trình tải thành công hoặc không thành công.

Sau khi SDK tải quảng cáo, hãy gọi mediationAdLoadCallback.onSuccess(). Trong trường hợp không tải được quảng cáo, hãy gọi mediationAdLoadCallback.onFailure() kèm theo một chuỗi giải thích lỗi đã xảy ra.

Phương thức mediationAdLoadCallback.onSuccess() yêu cầu bạn truyền vào một đối tượng xác nhận một trong các giao diện "Quảng cáo" do SDK quảng cáo trên thiết bị di động của Google xác định. Các giao diện quảng cáo này yêu cầu bạn cung cấp một số thông tin về quảng cáo.

MediationAdConfiguration cũng có phương thức getWatermark() để trả về một chuỗi được mã hoá base64 đại diện cho hình ảnh PNG. Hình ảnh này phải được xếp kề nhau trong một lớp phủ trong suốt trên quảng cáo của bạn. Hãy liên hệ với Google để được hướng dẫn thêm về cách hiển thị hình mờ. Tệp này chứa siêu dữ liệu về quảng cáo đang hiển thị để nhà xuất bản sử dụng nhằm xác định nguồn của quảng cáo được hiển thị.

Đối với biểu ngữ, bạn sẽ được yêu cầu cung cấp chế độ xem biểu ngữ. Đối với quảng cáo xen kẽ và quảng cáo có tặng thưởng, bạn sẽ được yêu cầu triển khai phương thức show() để hiển thị quảng cáo vào thời điểm sau. Tốt nhất là bạn nên đặt lớp tải quảng cáo chịu trách nhiệm triển khai các phương thức quảng cáo này.

Sau đây là ví dụ về cách triển khai loadBannerAd(). Xin lưu ý rằng cách triển khai bộ chuyển đổi của bạn sẽ khác, vì bộ chuyển đổi của bạn tích hợp với một SDK khác.

public final class SampleRtbAdapter extends RtbAdapter {
  ...

  @Override
  public void loadBannerAd(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {

      SampleBannerRenderer bannerRenderer =
          new SampleBannerRenderer(adConfiguration, callback);
      bannerRenderer.render();
    }
}

// Renders a banner ad, and forwards callbacks to Google Mobile Ads SDK (Legacy).
public class SampleBannerRenderer implements MediationBannerAd {
  private MediationBannerAdConfiguration adConfiguration;
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback;
  private AdView adView;
  private MediationBannerAdCallback callback;

  public SampleRtbBannerRenderer(
      MediationBannerAdConfiguration adConfiguration,
      MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> adLoadCallback) {
    this.adConfiguration = adConfiguration;
    this.adLoadCallback = adLoadCallback;
  }

  public void render() {
    adView = new AdView(adConfiguration.getContext());
    adView.setAdSize(adConfiguration.getAdSize());
    // serverParameters are the parameters entered in the AdMob UI for your network.
    adView.setAdUnitId(adConfiguration.getServerParameters().getString("adUnitId"));

    // Map the callbacks from your SDK to Google's SDK.
    adView.setAdListener(new AdListener() {
      // See the next step for more information on callback mapping.
      // ...
    });

    // Get the bid response and watermark from the ad configuration and
    // pass the relevant information to your SDK.
    String ad = adConfiguration.getBidResponse();
    String watermark = adConfiguration.getWatermark();
    Bundle extras = new Bundle();
    extras.putString("bid", ad);
    extras.putString("watermark", watermark);
    AdRequest request = new AdRequest.Builder()
        .addNetworkExtrasBundle(AdMobAdapter.class, extras)
        .build();
    adView.loadAd(request);
  }

  // MediationBannerAd implementation

  @NonNull
  @Override
  public View getView() {
    return adView;
  }
}

Chuyển tiếp các sự kiện trong vòng đời trình bày quảng cáo

Trách nhiệm cuối cùng của bộ chuyển đổi là thông báo cho Google Mobile Ads SDK (Legacy) về mọi sự kiện trong vòng đời của bản trình bày để có thể chuyển tiếp các sự kiện đó đến nhà xuất bản. Nhà xuất bản mong đợi các lệnh gọi lại này vào những thời điểm cụ thể, bất kể mạng quảng cáo nào phân phát quảng cáo, vì vậy, điều quan trọng là phải gọi càng nhiều lệnh gọi lại càng tốt và vào đúng thời điểm, để Google Mobile Ads SDK (Legacy) có thể chuyển tiếp các lệnh gọi lại đó đến nhà xuất bản.

Bộ chuyển đổi nên gọi các sự kiện sau khi thích hợp:

Điểm chung của mọi định dạng
Phương thức Thời điểm gọi
reportAdClicked() Quảng cáo đã được nhấp vào.
reportAdImpression() Quảng cáo đã hiển thị một lượt hiển thị.
onAdOpened() Quảng cáo đã hiển thị chế độ xem toàn màn hình.
onAdClosed() Chế độ xem toàn màn hình của quảng cáo đã bị đóng.
onAdLeftApplication() Quảng cáo khiến người dùng rời khỏi ứng dụng.
Quảng cáo có tặng thưởng
onRewarded() Người dùng được nhận phần thưởng.
Lệnh gọi lại video (quảng cáo gốc và quảng cáo có tặng thưởng)
onVideoStarted() Video của quảng cáo đã bắt đầu.
onVideoCompleted() Video của quảng cáo đã phát xong.

Bộ chuyển đổi sẽ nhận lại đối tượng MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> khi gọi mediationAdLoadCallback.onSuccess(). Bộ chuyển đổi dự kiến sẽ giữ đối tượng này và sử dụng đối tượng này để gọi các sự kiện trình bày xảy ra trên quảng cáo của bạn.

Thông thường, hầu hết các sự kiện này đều do SDK của mạng quảng cáo điều khiển. Vai trò của bộ chuyển đổi chỉ đơn giản là liên kết các lệnh gọi lại từ SDK mạng quảng cáo của bạn với Google Mobile Ads SDK (Legacy).

Ví dụ sau đây minh hoạ cách bạn chuyển tiếp lệnh gọi lại từ trình nghe quảng cáo của SDK đến Google Mobile Ads SDK (Legacy):

adView.setAdListener(new AdListener() {
    public void onAdLoaded() {
        callback = adLoadCallback.onSuccess(SampleBannerRenderer.this);
    }

    public void onAdImpression() {
        if (callback != null) {
            callback.reportAdImpression();
        }
    }

    public void onAdFailedToLoad(LoadAdError adError) {
        adLoadCallback.onFailure("Error: " + adError.toString());
    }

    public void onAdClosed() {
        if (callback != null) {
            callback.onAdClosed();
        }
    }

    public void onAdOpened() {
        if (callback != null) {
            callback.onAdOpened();
            callback.reportAdClicked();
        }
    }

    public void onAdLeftApplication() {
        if (callback != null) {
            callback.onAdLeftApplication();
        }
    }
});

Các thành phần bắt buộc để theo dõi lượt hiển thị quảng cáo gốc

Google Mobile Ads SDK (Legacy) ghi lại một lượt hiển thị cho quảng cáo gốc khi 1 px của quảng cáo hiển thị. Nếu SDK mạng quảng cáo của bạn yêu cầu hiển thị các thành phần cụ thể để hiển thị một lượt hiển thị hợp lệ, thì bên đặt giá thầu có thể cho biết các thành phần gốc bắt buộc này trong giá thầu phản hồi. Sau đó, Google Mobile Ads SDK (Legacy) sẽ xác thực rằng các thành phần gốc bắt buộc của bạn được hiển thị trước khi ghi lại một lượt hiển thị.

Hãy xem tài liệu về thành phần bắt buộc cho quảng cáo gốc để biết thêm thông tin về cách chỉ định các thành phần bắt buộc bổ sung trong giá thầu phản hồi.

Hiển thị lỗi quảng cáo

Đối với các định dạng toàn màn hình, chẳng hạn như quảng cáo xen kẽ và quảng cáo có tặng thưởng, trong lệnh gọi lại tải thành công, bạn sẽ cung cấp một phương thức triển khai MediationInterstitialAd hoặc MediationRewardedAd để Google Mobile Ads SDK (Legacy) có thể yêu cầu bộ chuyển đổi của bạn hiển thị quảng cáo.

Google Mobile Ads SDK (Legacy) dự kiến rằng nếu một bộ chuyển đổi tải quảng cáo thành công, thì quảng cáo đó sẽ sẵn sàng hiển thị khi nhà xuất bản yêu cầu hiển thị quảng cáo. Điều này có nghĩa là mỗi lệnh gọi hiển thị sẽ dẫn đến một lượt hiển thị.

Tuy nhiên, có thể có những trường hợp đặc biệt mà bạn không thể hiển thị quảng cáo. Nếu bạn không thể hiển thị quảng cáo, hãy gọi lệnh gọi lại onAdFailedToShow() để huỷ lượt hiển thị.

Bảng dưới đây cho biết cách lệnh gọi lại bản trình bày ảnh hưởng đến việc ghi nhận lượt hiển thị cho các định dạng quảng cáo toàn màn hình:

Số nhận cuộc gọi lại Kết quả
onAdOpened() Impression recorded
onAdFailedToShow() Impression failure1
Không có lựa chọn nào ở trên trong vài giây Impression recorded

1 Đối với các lượt hiển thị không thành công, mạng quảng cáo của bạn sẽ không bị tính phí cho lượt hiển thị đó, nhưng điều này sẽ ảnh hưởng đến mức điều chỉnh tỷ lệ sự kiện có thể tính phí. Hãy xem tín hiệu yêu cầu giá thầu để biết thêm thông tin.

Ví dụ minh hoạ sau đây cho thấy một vòng đời tải/hiển thị, trong đó lệnh gọi hiển thị quảng cáo có thể không thành công.

final class SampleRtbAdapter extends RtbAdapter implements MediationRewardedAd {

 private MediationRewardedAdCallback callback;
 private RewardedAd rewardedAd;

 ...

  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration adConfiguration,
      final MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> loadCallback) {

    // Load an ad. This mock example uses Google's SDK, but in practice
    // your adapter will load the ad using your ad network's SDK.
    RewardedAd.load(adConfiguration.getContext(),
        "ca-app-pub-3940256099942544/5224354917",
        new AdRequest.Builder().build(),
        new RewardedAdLoadCallback() {
          @Override
          public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
            // When the ad loads, invoke the load success callback.
            callback = loadCallback.onSuccess(SampleRtbAdapter.this);
          }
        });
  }

  @Override
  public void showAd(Context context) {
    // In this mock example, your ad network requires an activity context, but
    // didn't receive one, making you unable to show the ad.
    if (!(context instanceof Activity)) {
      AdError error = new AdError(1, "Context must be an activity",
          "com.google.ads.mediation.sample");
      callback.onAdFailedToShow(error);
    }

    // This example shows Google SDK's callbacks, but it's likely your SDK
    // has similar presentation callbacks.
    rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Your ad network SDK successfully showed the ad. Call onAdOpened().
        callback.onAdOpened();
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Your ad network SDK failed to show the ad, invoke onAdFailedToShow.
        // In practice, you will map your SDK's error to an AdError.
        AdError error = new AdError(adError.getCode(), adError.getMessage(),
            adError.getDomain());
        callback.onAdFailedToShow(adError);
      }
    });


    rewardedAd.show((Activity) context, ...);
  }
}