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