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

อะแดปเตอร์มีหน้าที่รับผิดชอบส่วนต่อไปนี้ของเวิร์กโฟลว์
ขั้นตอนที่ 4-7: เริ่มต้นอะแดปเตอร์และเรียกกลับ Google Mobile Ads SDK (Legacy) เมื่อการเริ่มต้นเสร็จสมบูรณ์
ขั้นตอนที่ 10-13: รวบรวมสัญญาณจาก SDK เครือข่ายโฆษณาเพื่อส่งไปยังผู้เสนอราคาเพื่อเข้าร่วมคำขอ RTB และส่งต่อสัญญาณไปยัง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google
ขั้นตอนที่ 18-21: หากผู้เสนอราคาส่งราคาเสนอที่ชนะกลับมา ให้โหลดโฆษณาตามการตอบกลับจากผู้เสนอราคา เมื่อโหลดแล้ว ให้แจ้ง Google Mobile Ads SDK (Legacy) ว่าโฆษณาโหลดแล้ว
ขั้นตอนที่ 23 เป็นต้นไป: ขณะที่โฆษณากำลังแสดง ให้แจ้ง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google เกี่ยวกับเหตุการณ์การแสดงผลและการคลิก รวมถึงเหตุการณ์โฆษณาอื่นๆ ที่เกิดขึ้นระหว่างวงจรการแสดงโฆษณา
การติดตั้งใช้งานอะแดปเตอร์การเสนอราคา
หากต้องการสร้างอะแดปเตอร์การเสนอราคาสำหรับ Google Mobile Ads SDK (Legacy) คุณต้องขยายคลาสแอบสแตรกต์ 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 (Legacy)
ขอสัญญาณจากอะแดปเตอร์ทั้งหมด
ที่เข้าร่วมการเสนอราคาพร้อมกัน โปรดจำกัดการเรียกใช้เธรด 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 (Legacy) จะเรียกอะแดปเตอร์เพื่อโหลดโฆษณาที่ชนะ โดยส่งข้อมูลใดๆ ที่ ผู้เสนอราคาส่งกลับมาซึ่ง SDK ต้องใช้เพื่อโหลดโฆษณานั้น
เมธอดการโหลดที่เรียกใช้จะขึ้นอยู่กับรูปแบบโฆษณาของคำขอนี้
| รูปแบบโฆษณา | เมธอดการโหลด |
|---|---|
| แบนเนอร์ | loadBannerAd()
|
| โฆษณาคั่นระหว่างหน้า | loadInterstitialAd()
|
| ได้รับรางวัลแล้ว | loadRewardedAd()
|
ติดตั้งใช้งานเมธอดเหล่านี้สำหรับรูปแบบโฆษณาที่อะแดปเตอร์รองรับ
ระบบจะเรียกใช้เมธอดการโหลดในเธรด UI ในอินสแตนซ์เดียวกันของอะแดปเตอร์ที่คุณให้สัญญาณ เมธอดนี้จะแสดงพารามิเตอร์ต่อไปนี้
MediationAdConfigurationซึ่งมีพารามิเตอร์ที่ SDK ต้องใช้เพื่อโหลดโฆษณาสำหรับราคาเสนอที่ชนะ เช่น การตอบกลับราคาเสนอและข้อมูลเข้าสู่ระบบใดๆ ที่ผู้เผยแพร่โฆษณากำหนดค่าไว้ใน UI ของ AdMobออบเจ็กต์
MediationAdLoadCallbackที่ใช้เพื่อแจ้ง Google Mobile Ads SDK (Legacy) เมื่อการโหลดสำเร็จหรือไม่สำเร็จ
เมื่อ 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 (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) เกี่ยวกับเหตุการณ์ในวงจรการแสดงโฆษณา เพื่อให้ระบบส่งต่อเหตุการณ์ไปยัง ผู้เผยแพร่โฆษณาได้ ผู้เผยแพร่โฆษณาคาดหวังการเรียกกลับเหล่านี้ในเวลาที่เฉพาะเจาะจง ไม่ว่า เครือข่ายโฆษณาใดจะแสดงโฆษณา ดังนั้นจึงเป็นเรื่องสำคัญที่จะต้องเรียกใช้การเรียกกลับเหล่านี้ให้มากที่สุดเท่าที่จะเป็นไปได้และในเวลาที่เหมาะสม เพื่อให้ Google Mobile Ads SDK (Legacy) ส่งต่อการเรียกกลับไปยังผู้เผยแพร่โฆษณาได้
อะแดปเตอร์ควรเรียกใช้เหตุการณ์ต่อไปนี้เมื่อมีผลบังคับใช้
| ใช้ได้กับทุกรูปแบบ | |
|---|---|
| เมธอด | เวลาที่เรียกใช้ |
reportAdClicked()
|
โฆษณาได้รับการคลิก |
reportAdImpression()
|
โฆษณาแสดงผลการแสดงผล |
onAdOpened()
|
โฆษณาแสดงมุมมองแบบเต็มหน้าจอ |
onAdClosed()
|
มุมมองแบบเต็มหน้าจอของโฆษณาปิดแล้ว |
onAdLeftApplication()
|
โฆษณาทำให้ผู้ใช้ออกจากแอปพลิเคชัน |
| โฆษณาที่มีการให้รางวัล | |
onRewarded()
|
ผู้ใช้ได้รับรางวัล |
| การเรียกกลับวิดีโอ (โฆษณาที่มีการให้รางวัลและโฆษณาเนทีฟ) | |
onVideoStarted()
|
วิดีโอของโฆษณาเริ่มเล่น |
onVideoCompleted()
|
วิดีโอของโฆษณาเล่นจบแล้ว |
อะแดปเตอร์จะได้รับ MediationAdLoadCallback<MediationAdT, MediationAdCallbackT>
ออบเจ็กต์กลับมาเมื่อเรียกใช้ mediationAdLoadCallback.onSuccess() อะแดปเตอร์ควรเก็บออบเจ็กต์นี้ไว้และใช้เพื่อเรียกใช้เหตุการณ์การแสดงโฆษณาที่เกิดขึ้นในโฆษณา
โดยปกติแล้ว เหตุการณ์ส่วนใหญ่เหล่านี้จะเกิดจาก SDK ของเครือข่ายโฆษณา บทบาทของอะแดปเตอร์คือการแมปการเรียกกลับจาก SDK เครือข่ายโฆษณาไปยัง Google Mobile Ads SDK (Legacy)
ตัวอย่างต่อไปนี้แสดงวิธีส่งต่อการเรียกกลับจากเครื่องมือฟังโฆษณาของ 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) จากนั้นจะตรวจสอบ ว่าชิ้นงานเนทีฟที่จำเป็นแสดงอยู่ก่อนที่จะบันทึกการแสดงผล
แสดงข้อผิดพลาดของโฆษณา
สำหรับรูปแบบแบบเต็มหน้าจอ เช่น โฆษณาคั่นระหว่างหน้าและโฆษณาที่มีการให้รางวัล ในการเรียกกลับการโหลดที่สำเร็จ
คุณจะต้องติดตั้งใช้งาน
MediationInterstitialAd
หรือ MediationRewardedAd
เพื่อให้ Google Mobile Ads SDK (Legacy) ขอให้อะแดปเตอร์แสดงโฆษณาได้
Google Mobile Ads SDK (Legacy) คาดหวังว่าหากอะแดปเตอร์โหลดโฆษณาสําเร็จ โฆษณาจะพร้อมแสดงเมื่อผู้เผยแพร่โฆษณาขอให้แสดง ซึ่งหมายความว่าการเรียกแสดงทุกครั้งควรส่งผลให้เกิดการแสดงผล
อย่างไรก็ตาม อาจมีกรณีพิเศษที่คุณไม่สามารถแสดงโฆษณาได้ หากแสดงโฆษณาไม่ได้ ให้เรียกใช้การเรียกกลับ เพื่อยกเลิกการแสดงผล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, ...);
}
}