การพัฒนาอะแดปเตอร์การเสนอราคา

คู่มือนี้มีไว้สำหรับเครือข่ายโฆษณาที่ต้องการสร้างอะแดปเตอร์การเสนอราคาเพื่อเข้าร่วมการเสนอราคาแบบเรียลไทม์ (RTB) ภายในสื่อกลางของ Google หากคุณ เป็นผู้เผยแพร่โฆษณา โปรดดูวิธีการใช้สื่อกลางของผู้เผยแพร่โฆษณา

อะแดปเตอร์การเสนอราคาเป็นส่วนฝั่งไคลเอ็นต์ของการผสานรวม อะแดปเตอร์ ช่วยให้ SDK เครือข่ายโฆษณาสื่อสารกับ Google Mobile Ads SDK เพื่อ โหลดโฆษณาที่แสดงโดยผู้เสนอราคา

อะแดปเตอร์จะต้องจัดการการเริ่มต้น การรวบรวมสัญญาณ การโหลดโฆษณา และการส่งต่อเหตุการณ์ในวงจรของโฆษณาเพื่อให้การเสนอราคาทำงานได้อย่างถูกต้อง ในคู่มือนี้ เราจะแนะนำวิธีติดตั้งใช้งานอะแดปเตอร์เพื่อจัดการการดำเนินการเหล่านี้

เวิร์กโฟลว์ของอะแดปเตอร์การเสนอราคา

การเริ่มต้น

ขั้นตอนโดยละเอียดของวงจรทั้งหมดของการส่งคำขอ การตอบกลับ และการแสดงผลของอะแดปเตอร์แสดงไว้ด้านล่าง

อะแดปเตอร์มีหน้าที่รับผิดชอบส่วนต่อไปนี้ของเวิร์กโฟลว์

  • ขั้นตอนที่ 4-7: เริ่มต้นอะแดปเตอร์และเรียกกลับ Google Mobile Ads SDK เมื่อการเริ่มต้นเสร็จสมบูรณ์

  • ขั้นตอนที่ 10-13: รวบรวมสัญญาณจาก SDK เครือข่ายโฆษณาเพื่อส่งไปยังผู้เสนอราคาเพื่อเข้าร่วมคำขอ RTB และส่งต่อสัญญาณไปยัง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google

  • ขั้นตอนที่ 18-21: หากผู้เสนอราคาส่งราคาเสนอที่ชนะกลับมา ให้โหลดโฆษณาตามการตอบกลับจากผู้เสนอราคา เมื่อโหลดแล้ว ให้แจ้ง Google Mobile Ads SDK ว่าโฆษณาโหลดแล้ว

  • ขั้นตอนที่ 23 เป็นต้นไป: ขณะที่โฆษณาแสดงอยู่ ให้แจ้ง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google เกี่ยวกับเหตุการณ์การแสดงผลและการคลิก รวมถึงเหตุการณ์โฆษณาอื่นๆ ที่เกิดขึ้นระหว่างวงจรการแสดงโฆษณา

การติดตั้งใช้งานอะแดปเตอร์การเสนอราคา

หากต้องการสร้างอะแดปเตอร์การเสนอราคาสำหรับ Google Mobile Ads SDK คุณต้องขยายคลาสแอบสแตรกต์ RtbAdapter ส่วนต่อไปนี้จะอธิบายเมธอดแอบสแตรกต์แต่ละรายการใน RtbAdapter

getSDKVersionInfo()

ในส่วนนี้ คุณควรแสดงเวอร์ชันของ SDK ระบบจะส่งเวอร์ชันนี้ไปยังผู้เสนอราคาเป็นส่วนหนึ่งของคำขอ OpenRTB

เมธอดนี้กำหนดให้คุณต้องแสดง VersionInfo ตัวอย่างด้านล่างแสดงวิธี แปลงเวอร์ชันสตริงของ SDK เป็น 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()

ในส่วนนี้ คุณควรแสดงเวอร์ชันของอะแดปเตอร์ ระบบจะส่งเวอร์ชันนี้ไปยังผู้เสนอราคาเป็นส่วนหนึ่งของคำขอ OpenRTB

อะแดปเตอร์โอเพนซอร์สและอะแดปเตอร์ที่มีการกำหนดเวอร์ชัน ของ Google ใช้รูปแบบเวอร์ชันอะแดปเตอร์ 4 หลัก แต่ VersionInfo อนุญาตให้ใช้ได้เพียง 3 หลัก เราขอแนะนำให้รวม 2 หลักสุดท้ายเป็นเวอร์ชันแพตช์ ดังที่แสดงด้านล่าง

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

ระยะหมดเวลา: 30 วินาที

เมธอด initialize() เป็นเมธอดแรกที่เรียกใช้ในอะแดปเตอร์ โดยจะเรียกใช้เพียงครั้งเดียวต่อเซสชัน เมธอดนี้จะแสดงรายการออบเจ็กต์ MediationConfiguration ซึ่งแสดงรายการตำแหน่งทั้งหมดในแอปนี้ที่กำหนดค่าไว้สำหรับเครือข่ายโฆษณา คุณสามารถวนซ้ำในรายการนี้เพื่อแยกวิเคราะห์ข้อมูลเข้าสู่ระบบสำหรับแต่ละตำแหน่ง และส่งข้อมูลที่เกี่ยวข้องไปยัง SDK เพื่อเริ่มต้น

เมื่อ SDK เริ่มต้นและพร้อมรับคำขอโฆษณาแล้ว ให้เรียกใช้เมธอด onInitializationSucceeded() ของ InitializationCompleteCallback ระบบจะส่งต่อการเรียกกลับนี้ไปยังผู้เผยแพร่แอปเพื่อให้ทราบว่าเริ่มโหลดโฆษณาได้แล้ว

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

ระยะหมดเวลา: 1 วินาที

ทุกครั้งที่ผู้เผยแพร่โฆษณาส่งคำขอโฆษณา ระบบจะสร้างอินสแตนซ์ใหม่ของ RtbAdapter และเรียกใช้เมธอด collectSignals() ระบบจะใช้อินสแตนซ์ RtbAdapter นี้ตลอดระยะเวลาของวงจรการส่งคำขอโฆษณา การตอบกลับ และการแสดงผลสำหรับโฆษณานั้น เมธอด collectSignals() ช่วยให้อะแดปเตอร์แสดงสัญญาณจากอุปกรณ์เพื่อส่งไปยังผู้เสนอราคาในคำขอ OpenRTB ได้

ระบบจะเรียกใช้ collectSignals() ในเธรดเบื้องหลัง Google Mobile Ads SDK ขอสัญญาณจากอะแดปเตอร์ทั้งหมด ที่เข้าร่วมการเสนอราคาพร้อมกัน โปรดจำกัดการเรียกใช้เธรด UI ในช่วงเวลานี้ อะแดปเตอร์หรือ SDK ควรทำงานหนักที่จำเป็นในการรวบรวม สัญญาณในเมธอด initialize() และแคชสัญญาณไว้

เมื่อสัญญาณพร้อมแล้ว ให้เรียกใช้การเรียกกลับ onSuccess() พร้อมสัญญาณที่เข้ารหัส

ตัวอย่างการติดตั้งใช้งานมีดังนี้

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

หากอะแดปเตอร์รวบรวมสัญญาณไม่สำเร็จ ให้เรียกใช้ signalCallbacks.onFailure() พร้อมสตริงที่อธิบายข้อผิดพลาดที่เกิดขึ้น

ติดตั้งใช้งานเมธอดการโหลดโฆษณา

ระยะหมดเวลา: 10 วินาที

หากผู้เสนอราคาส่งราคาเสนอที่ชนะกลับมา Google Mobile Ads SDK จะเรียกอะแดปเตอร์เพื่อโหลดโฆษณาที่ชนะ โดยส่งข้อมูลที่ ผู้เสนอราคาส่งกลับมาซึ่ง SDK ต้องใช้ในการโหลดโฆษณานั้นให้คุณ

เมธอดการโหลดที่เรียกใช้จะขึ้นอยู่กับรูปแบบโฆษณาของคำขอนี้

รูปแบบโฆษณา เมธอดการโหลด
แบนเนอร์ loadBannerAd()
โฆษณาคั่นระหว่างหน้า loadInterstitialAd()
ได้รับรางวัลแล้ว loadRewardedAd()

ติดตั้งใช้งานเมธอดเหล่านี้สำหรับรูปแบบโฆษณาที่อะแดปเตอร์รองรับ

ระบบจะเรียกใช้เมธอดการโหลดในเธรด UI ในอินสแตนซ์เดียวกันของอะแดปเตอร์ที่คุณให้สัญญาณ เมธอดนี้จะแสดงพารามิเตอร์ต่อไปนี้

  • MediationAdConfiguration ซึ่งมีพารามิเตอร์ที่ SDK ต้องใช้ในการโหลดโฆษณาสำหรับราคาเสนอที่ชนะ เช่น การเสนอราคาตอบและข้อมูลเข้าสู่ระบบที่ผู้เผยแพร่โฆษณากำหนดค่าไว้ใน UI ของ AdMob

  • ออบเจ็กต์ MediationAdLoadCallback ที่ใช้เพื่อแจ้ง Google Mobile Ads SDK เมื่อการโหลดสำเร็จหรือล้มเหลว

เมื่อ SDK โหลดโฆษณาแล้ว ให้เรียกใช้ mediationAdLoadCallback.onSuccess() ในกรณีที่การโหลดโฆษณาล้มเหลว ให้เรียกใช้ mediationAdLoadCallback.onFailure() พร้อมสตริงที่อธิบายข้อผิดพลาดที่เกิดขึ้น

เมธอด mediationAdLoadCallback.onSuccess() กำหนดให้คุณต้องส่งออบเจ็กต์ที่สอดคล้องกับอินเทอร์เฟซ "โฆษณา" รายการใดรายการหนึ่งที่กำหนดโดย SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google อินเทอร์เฟซโฆษณาเหล่านี้จะขอให้คุณระบุข้อมูลบางอย่างเกี่ยวกับโฆษณา

MediationAdConfiguration ยังมี getWatermark() เมธอด เพื่อแสดงสตริงที่เข้ารหัส Base64 ซึ่งแสดงรูปภาพ PNG คุณควรวางรูปภาพนี้แบบเรียงต่อกันในภาพซ้อนทับแบบโปร่งใสบนโฆษณา โปรดติดต่อ Google เพื่อขอคำแนะนำเพิ่มเติมเกี่ยวกับวิธีแสดงลายน้ำ โดยจะมีข้อมูลเมตาเกี่ยวกับโฆษณาที่แสดงเพื่อให้ผู้เผยแพร่โฆษณาทราบแหล่งที่มาของโฆษณาที่แสดง

สำหรับแบนเนอร์ ระบบจะขอให้คุณระบุมุมมองแบนเนอร์ สำหรับโฆษณาคั่นระหว่างหน้าและโฆษณาที่มีการให้รางวัล ระบบจะขอให้คุณติดตั้งใช้งานเมธอด show() เพื่อแสดงโฆษณาในภายหลัง เราขอแนะนำให้คลาสที่โหลดโฆษณามีหน้าที่รับผิดชอบในการติดตั้งใช้งานเมธอดโฆษณาเหล่านี้ด้วย

ตัวอย่างการติดตั้งใช้งาน loadBannerAd() มีดังนี้ โปรดทราบว่าการติดตั้งใช้งานของอะแดปเตอร์จะมีลักษณะแตกต่างกัน เนื่องจากอะแดปเตอร์ผสานรวมกับ SDK อื่น

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.
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;
  }
}

ส่งต่อเหตุการณ์ในวงจรการแสดงโฆษณา

ความรับผิดชอบสุดท้ายของอะแดปเตอร์คือการแจ้ง Google Mobile Ads SDK เกี่ยวกับเหตุการณ์ในวงจรการแสดงโฆษณา เพื่อให้ระบบส่งต่อเหตุการณ์เหล่านั้นไปยัง ผู้เผยแพร่โฆษณาได้ ผู้เผยแพร่โฆษณาคาดหวังการเรียกกลับเหล่านี้ในเวลาที่เฉพาะเจาะจง ไม่ว่า เครือข่ายโฆษณาใดจะแสดงโฆษณา ดังนั้นจึงเป็นเรื่องสำคัญที่จะต้องเรียกใช้การเรียกกลับเหล่านี้ให้มากที่สุดเท่าที่จะเป็นไปได้และในเวลาที่เหมาะสม เพื่อให้ Google Mobile Ads SDK ส่งต่อการเรียกกลับไปยังผู้เผยแพร่โฆษณาได้

อะแดปเตอร์ควรเรียกใช้เหตุการณ์ต่อไปนี้เมื่อมีผลบังคับใช้

ใช้ได้กับทุกรูปแบบ
เมธอด เวลาที่ควรเรียกใช้
reportAdClicked() มีการคลิกโฆษณา
reportAdImpression() โฆษณาแสดงผลการแสดงผล
onAdOpened() โฆษณาแสดงมุมมองแบบเต็มหน้าจอ
onAdClosed() การดูหน้าจอแบบเต็มหน้าจอของโฆษณาปิดแล้ว
onAdLeftApplication() โฆษณาทำให้ผู้ใช้ออกจากแอปพลิเคชัน
โฆษณาที่มีการให้รางวัล
onRewarded() ผู้ใช้ได้รับรางวัล
การเรียกกลับวิดีโอ (โฆษณาที่มีการให้รางวัลและโฆษณาเนทีฟ)
onVideoStarted() วิดีโอของโฆษณาเริ่มเล่น
onVideoCompleted() วิดีโอของโฆษณาเล่นจบแล้ว

อะแดปเตอร์จะได้รับ MediationAdLoadCallback<MediationAdT, MediationAdCallbackT> ออบเจ็กต์กลับมาเมื่อเรียกใช้ mediationAdLoadCallback.onSuccess() อะแดปเตอร์ควรเก็บออบเจ็กต์นี้ไว้และใช้เพื่อเรียกใช้เหตุการณ์การแสดงโฆษณาที่เกิดขึ้นในโฆษณา

โดยปกติแล้ว เหตุการณ์ส่วนใหญ่เหล่านี้จะเกิดจาก SDK ของเครือข่ายโฆษณา บทบาทของอะแดปเตอร์คือการแมปการเรียกกลับจาก SDK เครือข่ายโฆษณาไปยัง Google Mobile Ads SDK

ตัวอย่างต่อไปนี้แสดงวิธีส่งต่อ Callback จาก Listener โฆษณาของ SDK ไปยัง Google Mobile Ads SDK

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

ชิ้นงานที่จำเป็นสำหรับการติดตามการแสดงผลโฆษณาเนทีฟ

Google Mobile Ads SDK บันทึกการแสดงผลสำหรับโฆษณาเนทีฟเมื่อโฆษณาแสดง 1 พิกเซลของ หาก SDK เครือข่ายโฆษณาต้องแสดงชิ้นงานที่เฉพาะเจาะจงเพื่อให้แสดงผลการแสดงผลที่ถูกต้อง ผู้เสนอราคาสามารถระบุชิ้นงานเนทีฟที่จำเป็นเหล่านี้ในการเสนอราคาตอบ Google Mobile Ads SDK จากนั้นจะตรวจสอบว่าชิ้นงานเนทีฟที่จำเป็นแสดงอยู่ก่อนที่จะบันทึกการแสดงผล

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีระบุชิ้นงานเพิ่มเติมที่จำเป็นในการตอบกลับราคาเสนอได้ที่เอกสารประกอบเกี่ยวกับชิ้นงานที่จำเป็นสำหรับโฆษณาเนทีฟ

แสดงข้อผิดพลาดของโฆษณา

สำหรับรูปแบบแบบเต็มหน้าจอ เช่น โฆษณาคั่นระหว่างหน้าและโฆษณาที่มีการให้รางวัล ในการเรียกกลับการโหลดที่สำเร็จ คุณจะต้องติดตั้งใช้งาน MediationInterstitialAd หรือ MediationRewardedAd เพื่อให้ Google Mobile Ads SDK ขอให้อะแดปเตอร์แสดงโฆษณาได้

Google Mobile Ads SDK คาดหวังว่าหากอะแดปเตอร์โหลดโฆษณาสําเร็จ โฆษณาจะพร้อมแสดงเมื่อผู้เผยแพร่โฆษณาขอให้แสดง ซึ่งหมายความว่าการเรียกแสดงทุกครั้งควรส่งผลให้เกิดการแสดงผล

อย่างไรก็ตาม อาจมีกรณีพิเศษที่คุณไม่สามารถแสดงโฆษณาได้ หากแสดงโฆษณาไม่ได้ ให้เรียกใช้การเรียกกลับ เพื่อยกเลิกการแสดงผลonAdFailedToShow()

ตารางด้านล่างแสดงวิธีที่การเรียกกลับการแสดงโฆษณาส่งผลต่อการบันทึกการแสดงผลสำหรับรูปแบบโฆษณาแบบเต็มหน้าจอ

การเรียกกลับ ผลลัพธ์
onAdOpened() Impression recorded
onAdFailedToShow() Impression failure1
ไม่มีการเรียกกลับข้างต้นเป็นเวลาหลายวินาที Impression recorded

1 สำหรับการแสดงผลที่ล้มเหลว ระบบจะไม่เรียกเก็บเงินการแสดงผลจากเครือข่ายโฆษณา แต่การแสดงผลที่ล้มเหลวจะส่งผลต่อการปรับอัตราเหตุการณ์ที่เรียกเก็บเงินได้ ดูข้อมูลเพิ่มเติมได้ที่สัญญาณ คำขอราคาเสนอ

ตัวอย่างจำลองต่อไปนี้แสดงวงจรการโหลด/การแสดงโฆษณาที่การเรียกแสดงโฆษณาอาจส่งผลให้เกิดข้อผิดพลาด

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, ...);
  }
}