หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

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

การเริ่มต้น

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

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

ขั้นตอนที่ 4-7: เริ่มต้นอะแดปเตอร์และเรียก SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google กลับมา เมื่อการเริ่มต้นเสร็จสมบูรณ์
ขั้นตอนที่ 10-13: รวบรวมสัญญาณจาก SDK เครือข่ายโฆษณาเพื่อส่งไปยัง ในการเข้าร่วมคำขอ RTB และส่งต่อไปยัง Google Mobile SDK โฆษณา
ขั้นตอนที่ 18-21: หากผู้เสนอราคาของคุณส่งราคาเสนอที่ชนะกลับมา ให้โหลดโฆษณาตาม ต่อการตอบกลับจากผู้เสนอราคาของคุณ เมื่อโหลดแล้ว ให้แจ้ง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google ที่มีการโหลดโฆษณา
ขั้นตอนที่ 23 และหลังจากนั้น: ขณะที่โฆษณาของคุณแสดง ให้แจ้งโฆษณาบนมือถือของ Google SDK ของเหตุการณ์การแสดงผลและการคลิก รวมถึงเหตุการณ์โฆษณาอื่นๆ ที่เกิดขึ้น ในวงจรการนำเสนอโฆษณา

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

หากต้องการสร้างอะแดปเตอร์การเสนอราคาสำหรับ SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google คุณต้อง ขยายคลาส Abstract 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() เป็นวิธีแรกที่เรียกใช้ในอะแดปเตอร์ ใช่เลย ถูกเรียกเพียง 1 ครั้งต่อเซสชัน วิธีนี้แสดงรายการ 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 ขอสัญญาณจากอะแดปเตอร์ทั้งหมดพร้อมกัน การเข้าร่วมการเสนอราคา โปรดระมัดระวังและจำกัดการเรียกชุด UI ในช่วงเวลานี้ งานหนักที่อะแดปเตอร์หรือ SDK ต้องทำเพื่อรวบรวม ควรทำในเมธอด initialize() และแคช

เมื่อคุณมีสัญญาณพร้อมแล้ว โปรดโทรหา onSuccess() Callback พร้อม สัญญาณที่เข้ารหัส

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

@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 ที่ใช้เพื่อแจ้ง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google เมื่อการโหลดสำเร็จหรือล้มเหลว

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

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

MediationAdConfiguration ยังมี getWatermark() ด้วย เพื่อแสดงผลสตริงที่เข้ารหัสฐาน 64 ซึ่งแสดงรูปภาพ 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 the 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;
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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