คู่มือนี้มีไว้สำหรับเครือข่ายโฆษณาที่ต้องการสร้างอะแดปเตอร์การเสนอราคา เพื่อเข้าร่วมการเสนอราคาแบบเรียลไทม์ (RTB) ภายในสื่อกลางของ Google หากคุณเป็นผู้เผยแพร่โฆษณา โปรดดูวิธีการสื่อกลางสำหรับผู้เผยแพร่โฆษณา
อแดปเตอร์การเสนอราคาคือส่วนฝั่งไคลเอ็นต์ของการผสานรวม อแดปเตอร์ ช่วยให้ SDK เครือข่ายโฆษณาสื่อสารกับ SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google เพื่อ โหลดโฆษณาที่แสดงโดยผู้เสนอราคาของคุณ
หากต้องการให้การเสนอราคาทำงานได้อย่างถูกต้อง อะแดปเตอร์จะต้องจัดการการเริ่มต้น การรวบรวมสัญญาณ การโหลดโฆษณา และการส่งต่อเหตุการณ์วงจรโฆษณา ในคู่มือนี้ เราจะอธิบายวิธีติดตั้งใช้งานอแดปเตอร์เพื่อจัดการการดำเนินการเหล่านี้
เวิร์กโฟลว์ของอะแดปเตอร์การเสนอราคา
การเริ่มต้น
ขั้นตอนโดยละเอียดของวงจรคำขอ-การตอบกลับ-การแสดงผลทั้งหมด ของอแดปเตอร์แสดงอยู่ด้านล่าง
อแดปเตอร์มีหน้าที่รับผิดชอบในส่วนต่างๆ ของเวิร์กโฟลว์ต่อไปนี้
ขั้นตอนที่ 4-7: เริ่มต้นอแดปเตอร์และเรียกกลับ SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google เมื่อการเริ่มต้นเสร็จสมบูรณ์
ขั้นตอนที่ 10-13: รวบรวมสัญญาณจาก SDK เครือข่ายโฆษณาเพื่อส่งไปยัง ผู้เสนอราคาเพื่อเข้าร่วมคำขอ RTB และส่งต่อสัญญาณไปยัง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google
ขั้นตอนที่ 18-21: หากผู้เสนอราคาส่งคืนราคาเสนอที่ชนะ ให้โหลดโฆษณาตาม การตอบกลับจากผู้เสนอราคา เมื่อโหลดแล้ว ให้แจ้ง Google Mobile Ads SDK ว่าโหลดโฆษณาแล้ว
ขั้นตอนที่ 23 เป็นต้นไป: ขณะที่โฆษณากำลังแสดง ให้แจ้ง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google เกี่ยวกับเหตุการณ์การแสดงผลและเหตุการณ์คลิก รวมถึงเหตุการณ์โฆษณาอื่นๆ ที่เกิดขึ้น ในช่วงวงจรการนำเสนอของโฆษณา
การติดตั้งใช้งานอแดปเตอร์การเสนอราคา
หากต้องการสร้างอแดปเตอร์การเสนอราคาสำหรับ Google Mobile Ads SDK คุณต้องขยาย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
ระบบจะส่งต่อการเรียกกลับนี้ไปยังผู้เผยแพร่แอปเพื่อให้ทราบว่าสามารถเริ่มโหลดโฆษณาได้
@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()
จะเรียกใช้ในเธรดเบื้องหลัง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google
จะขอสัญญาณจากอแดปเตอร์ทั้งหมด
ที่เข้าร่วมการเสนอราคาพร้อมกัน โปรดเคารพและจำกัดการเรียกใช้ในเทรด UI
ในช่วงเวลานี้ งานหนักๆ ที่อะแดปเตอร์หรือ SDK ต้องทำเพื่อรวบรวมสัญญาณควรทำในเมธอด initialize()
และแคชไว้
เมื่อสัญญาณพร้อมแล้ว ให้เรียกใช้onSuccess()
การเรียกกลับพร้อมกับสัญญาณที่เข้ารหัส
ตัวอย่างการใช้งาน
@Override
public void collectSignals(RtbSignalData rtbSignalData,
SignalCallbacks signalCallbacks) {
String signals = YourSdk.getSignals();
signalCallbacks.onSuccess(signals);
}
หากอะแดปเตอร์รวบรวมสัญญาณไม่สำเร็จ ให้โทรหา signalCallbacks.onFailure()
พร้อมสตริงที่อธิบายข้อผิดพลาดที่เกิดขึ้น
ใช้วิธีการโหลดโฆษณา
ระยะหมดเวลา: 10 วินาที
หากผู้เสนอราคาส่งราคาเสนอที่ชนะกลับมา SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google จะเรียกอแดปเตอร์เพื่อโหลดโฆษณาที่ชนะ และส่งข้อมูลใดๆ ที่ผู้เสนอราคา ส่งกลับมาซึ่ง 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 เครือข่ายโฆษณาของคุณไปยัง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google
ตัวอย่างต่อไปนี้แสดงวิธีส่งต่อการเรียกกลับจากเครื่องมือฟังโฆษณาของ 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 จะตรวจสอบ ว่าชิ้นงานเนทีฟที่จำเป็นแสดงก่อนที่จะบันทึกการแสดงผล
ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีระบุชิ้นงานที่จำเป็นเพิ่มเติมในคำขอเสนอราคาได้ที่เอกสารประกอบเกี่ยวกับชิ้นงานที่จำเป็นสำหรับโฆษณาเนทีฟ
แสดงข้อผิดพลาดของโฆษณา
สำหรับรูปแบบเต็มหน้าจอ เช่น โฆษณาคั่นระหว่างหน้าและโฆษณาที่มีการให้รางวัล ในการเรียกกลับ load ที่สำเร็จ คุณจะต้องระบุการใช้งาน
MediationInterstitialAd
หรือ MediationRewardedAd
เพื่อให้ SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google ขอให้ตัวกลางแสดงโฆษณาได้
Google Mobile Ads SDK คาดหวังว่าหากอแดปเตอร์โหลดโฆษณาสำเร็จ โฆษณาจะพร้อมแสดงเมื่อผู้เผยแพร่โฆษณาขอให้แสดง ซึ่งหมายความว่า การเรียกใช้โฆษณาทุกครั้งควรส่งผลให้เกิดการแสดงผล
อย่างไรก็ตาม อาจมีกรณีที่แสดงโฆษณาไม่ได้ หากแสดงโฆษณาไม่ได้ ให้เรียกใช้
onAdFailedToShow()
การเรียกกลับเพื่อยกเลิกการแสดงผล
ตารางด้านล่างแสดงให้เห็นว่าการเรียกกลับการนำเสนอมีผลต่อการบันทึกการแสดงผลสำหรับรูปแบบโฆษณาแบบเต็มหน้าจออย่างไร
การติดต่อกลับ | ผลลัพธ์ |
---|---|
onAdOpened() | Impression recorded
|
onAdFailedToShow() | Impression failure1
|
ไม่ตรงกับข้อใดเลยเป็นเวลาหลายวินาที | Impression recorded
|
1 สำหรับการแสดงผลที่ไม่สำเร็จ ระบบจะไม่เรียกเก็บเงินจากเครือข่ายโฆษณาสำหรับการแสดงผล แต่ จะส่งผลต่อการปรับอัตราเหตุการณ์ที่เรียกเก็บเงินได้ ดูข้อมูลเพิ่มเติมได้ที่สัญญาณคำขอเสนอราคา
ตัวอย่างจำลองต่อไปนี้แสดงวงจรการโหลด/การแสดงผลที่การเรียกใช้ ad show อาจส่งผลให้เกิดข้อผิดพลาด
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, ...);
}
}