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

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

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

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

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

การเริ่มต้น

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

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

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

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

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

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

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

หากต้องการสร้างอะแดปเตอร์การเสนอราคาสำหรับ Google Mobile Ads SDK (Legacy) คุณต้องขยายคลาสแอบสแตรกต์ RtbAdapter ส่วนต่อไปนี้จะอธิบายเมธอด Abstract แต่ละรายการใน 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 ระบบจะส่งต่อ Callback นี้ไปยังผู้เผยแพร่แอปเพื่อให้ทราบว่าสามารถเริ่มโหลดโฆษณาได้

@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 (Legacy) จะขอสัญญาณจากอะแดปเตอร์ทั้งหมดที่เข้าร่วมการเสนอราคาพร้อมกัน โปรดคำนึงถึงผู้อื่นและจำกัดการเรียกไปยังเธรด UI ในช่วงเวลานี้ งานหนักๆ ที่อะแดปเตอร์หรือ SDK ต้องทำเพื่อรวบรวมสัญญาณควรทำในเมธอด initialize() และแคชไว้

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

ตัวอย่างการใช้งาน

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

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

ใช้วิธีการโหลดโฆษณา

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

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

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

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

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

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

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

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

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

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

นอกจากนี้ 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 (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;
  }
}

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

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

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

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

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

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

ตัวอย่างต่อไปนี้แสดงวิธีส่งต่อ Callback จาก Listener โฆษณาของ SDK ไปยัง 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();
        }
    }
});

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

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

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

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

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

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

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

ตารางด้านล่างแสดงผลกระทบของ Callback การนำเสนอต่อการบันทึกการแสดงผลสำหรับรูปแบบโฆษณาแบบเต็มหน้าจอ

การติดต่อกลับ ผลลัพธ์
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, ...);
  }
}