คู่มือนี้อธิบายวิธีผสานรวมโฆษณาที่มีการให้รางวัลลงในแอป Android
ก่อนเริ่มต้น
ก่อนดำเนินการต่อ ให้ทำดังนี้
- ตั้งค่า GMA Next-Gen SDK
- ใช้รหัสหน่วยโฆษณาที่มีการให้รางวัลสำหรับการทดสอบ
/6499/example/rewarded- เมื่อสร้างและทดสอบแอป โปรดใช้โฆษณาสำหรับการทดสอบแทนโฆษณาจริง หากไม่ใช้รหัสหน่วยโฆษณาสำหรับการทดสอบ Google อาจระงับบัญชีของคุณ
- ก่อนเผยแพร่แอป ให้แทนที่รหัสนี้ด้วยรหัสหน่วยโฆษณา
- ดูรายละเอียดเกี่ยวกับโฆษณาสำหรับการทดสอบGMA Next-Gen SDK ได้ที่ หัวข้อเปิดใช้โฆษณาสำหรับการทดสอบ
ทำความเข้าใจการโหลดโฆษณาล่วงหน้า (เบต้า)
การโหลดโฆษณาล่วงหน้า (เบต้า) ใน GMA Next-Gen SDK จะโหลดและแคชโฆษณาโดยอัตโนมัติ
การโหลดโฆษณาล่วงหน้ามีประโยชน์ดังนี้
- การจัดการการอ้างอิง: รักษาการอ้างอิงไว้จนกว่าจะมีการแสดงโฆษณา
- การโหลดซ้ำอัตโนมัติ: โหลดโฆษณาใหม่เมื่อมีการดึงโฆษณาจากแคช
- การลองใหม่ที่จัดการ: โหลดโฆษณาใหม่เมื่อโหลดโฆษณาไม่สำเร็จ
- การจัดการการหมดอายุ: รีเฟรชโฆษณาก่อนหมดอายุ
- การเพิ่มประสิทธิภาพแคช: เพิ่มประสิทธิภาพลำดับแคชเพื่อแสดงโฆษณาที่มีลำดับความสำคัญสูงสุด
เริ่มการโหลดโฆษณาล่วงหน้า
หากต้องการเริ่มโหลดโฆษณาล่วงหน้า ให้เรียกใช้เมธอด start เพียงครั้งเดียวเมื่อเริ่มแอป หลังจากเรียกใช้เมธอด start แล้ว
GMA Next-Gen SDK จะโหลดโฆษณาล่วงหน้าโดยอัตโนมัติและลองคำขอที่ล้มเหลวสำหรับการกำหนดค่าที่โหลดล่วงหน้าอีกครั้ง
ตัวอย่างต่อไปนี้แสดงวิธีเริ่มโหลดโฆษณาล่วงหน้า
Kotlin
Java
แทนที่ AD_UNIT_ID ด้วยรหัสหน่วยโฆษณา
ตัวอย่างก่อนหน้านี้แสดงวิธีใช้รหัสหน่วยโฆษณาเป็นรหัสการโหลดล่วงหน้า รหัสการโหลดล่วงหน้าคือตัวระบุสตริงที่คุณสร้างขึ้นเพื่อระบุการกำหนดค่าการโหลดโฆษณาล่วงหน้า หากแอปต้องใช้การกำหนดค่าการกำหนดเป้าหมายหลายรายการสำหรับรหัสหน่วยโฆษณาเดียวกัน ให้ส่งตัวระบุสตริงที่กำหนดเอง
รับและแสดงโฆษณาที่โหลดล่วงหน้า
เมื่อต้องการแสดงโฆษณา ให้เรียกใช้เมธอด pollAd
GMA Next-Gen SDK จะดึงโฆษณาที่พร้อมใช้งานและโหลดโฆษณาถัดไปล่วงหน้าโดยอัตโนมัติ
ในเบื้องหลัง หากไม่มีโฆษณาที่พร้อมใช้งาน GMA Next-Gen SDK จะไม่แสดงโฆษณา
เมื่อมีออบเจ็กต์โฆษณาที่พร้อมใช้งาน ให้เรียกใช้เมธอด show เพื่อแสดงโฆษณา
ใช้ Listener รางวัลเพื่อจัดการเหตุการณ์รางวัล ตัวอย่างต่อไปนี้แสดงวิธีดึงและแสดงโฆษณาที่โหลดล่วงหน้า
Kotlin
Java
หลีกเลี่ยงการเรียกใช้เมธอด pollAd จนกว่าคุณจะพร้อมแสดงโฆษณา หากต้องการอ่านข้อมูลการตอบกลับของโฆษณาโดยไม่แสดงโฆษณา โปรดดูหัวข้อ
อ่านข้อมูลการตอบกลับ
รอเหตุการณ์โฆษณา
รอเหตุการณ์โฆษณาก่อนแสดงโฆษณา ตัวอย่างต่อไปนี้แสดงวิธีลงทะเบียน Callback สำหรับเหตุการณ์โฆษณา
Kotlin
private fun listenToAdEvents() { // Listen for ad events. val ad = rewardedAd if (ad == null) { Log.e(TAG, "Rewarded ad is not ready yet.") return } ad.adEventCallback = object : RewardedAdEventCallback { override fun onAdShowedFullScreenContent() { // Rewarded ad did show. } override fun onAdDismissedFullScreenContent() { // Rewarded ad did dismiss. rewardedAd = null } override fun onAdFailedToShowFullScreenContent( fullScreenContentError: FullScreenContentError ) { // Rewarded ad failed to show. Log.e(TAG, "Rewarded ad failed to show: ${fullScreenContentError.message}") } override fun onAdImpression() { // Rewarded ad did record an impression. } override fun onAdClicked() { // Rewarded ad did record a click. } } }
Java
private void listenToAdEvents() { // Listen for ad events. if (rewardedAd == null) { Log.e(TAG, "Rewarded ad is not ready yet."); return; } rewardedAd.setAdEventCallback( new RewardedAdEventCallback() { @Override public void onAdShowedFullScreenContent() { // Rewarded ad did show. } @Override public void onAdDismissedFullScreenContent() { // Rewarded ad did dismiss. rewardedAd = null; } @Override public void onAdFailedToShowFullScreenContent( FullScreenContentError fullScreenContentError) { // Rewarded ad failed to show. Log.e(TAG, "Rewarded ad failed to show: " + fullScreenContentError.getMessage()); } @Override public void onAdImpression() { // Rewarded ad did record an impression. } @Override public void onAdClicked() { // Rewarded ad did record a click. } }); }
ไม่บังคับ: ตรวจสอบการติดต่อกลับการยืนยันฝั่งเซิร์ฟเวอร์ (SSV)
หากแอปต้องการข้อมูลเพิ่มเติมในการยืนยันฝั่งเซิร์ฟเวอร์ Callback ให้ใช้ฟีเจอร์ข้อมูลที่กำหนดเองของโฆษณาที่มีการให้รางวัล ค่าสตริงที่ตั้งค่าไว้ในออบเจ็กต์โฆษณาที่มีการให้รางวัลจะส่งไปยังพารามิเตอร์การค้นหา custom_data ของ SSV Callback หากไม่ได้ตั้งค่าข้อมูลที่กำหนดเอง ค่าพารามิเตอร์การค้นหา custom_data จะไม่อยู่ใน SSV Callback
ตัวอย่างโค้ดต่อไปนี้แสดงวิธีตั้งค่าข้อมูลที่กำหนดเองในออบเจ็กต์โฆษณาที่มีการให้รางวัลก่อนแสดงโฆษณา
Kotlin
Java
แทนที่ SAMPLE_CUSTOM_DATA_STRING ด้วยข้อมูลที่กำหนดเอง
ไม่บังคับ: รอเหตุการณ์การโหลดล่วงหน้า
เมื่อเริ่มโหลดโฆษณาล่วงหน้า ให้ลงทะเบียนเพื่อรับเหตุการณ์การโหลดล่วงหน้าเพื่อรับการแจ้งเตือนเมื่อโหลดโฆษณาล่วงหน้าสำเร็จ โหลดล่วงหน้าไม่สำเร็จ หรือแคชโฆษณาหมด
ตัวอย่างต่อไปนี้แสดงวิธีลงทะเบียนเพื่อรับเหตุการณ์การโหลดโฆษณาล่วงหน้า
Kotlin
val preloadCallback = object : PreloadCallback { override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) { Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}") } override fun onAdsExhausted(preloadId: String) { Log.i(TAG, "Rewarded preload ad $preloadId is not available") } override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) { Log.i(TAG, "Rewarded preload ad $preloadId is available") } } val adRequest = AdRequest.Builder(adUnitId).build() val preloadConfig = PreloadConfiguration(adRequest) RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
Java
PreloadCallback preloadCallback = new PreloadCallback() { @Override public void onAdFailedToPreload(String preloadId, LoadAdError adError) { Log.d( TAG, String.format( "Rewarded preload ad %s failed to load with error: %s", preloadId, adError.getMessage())); } @Override public void onAdsExhausted(String preloadId) { Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available"); } @Override public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) { Log.i(TAG, "Rewarded preload ad " + preloadId + " is available"); } }; AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest); RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
เมื่อโหลดโฆษณาไม่สำเร็จ GMA Next-Gen SDK จะโหลดโฆษณาล่วงหน้าโดยอัตโนมัติและลองคำขอที่ล้มเหลวสำหรับการกำหนดค่าที่โหลดล่วงหน้าอีกครั้ง
ไม่บังคับ: ตรวจสอบความพร้อมใช้งานของโฆษณา
หากต้องการทราบว่ามีโฆษณาพร้อมใช้งานหรือไม่ ให้ตรวจสอบความพร้อมใช้งานของโฆษณา ตัวอย่างต่อไปนี้แสดงวิธีตรวจสอบว่ามีโฆษณาที่โหลดล่วงหน้าพร้อมใช้งานหรือไม่
Kotlin
private fun isAdAvailable(adUnitId: String): Boolean { return RewardedAdPreloader.isAdAvailable(adUnitId) }
Java
private boolean isAdAvailable(String adUnitId) { return RewardedAdPreloader.isAdAvailable(adUnitId); }
ไม่บังคับ: ตั้งค่าขนาดบัฟเฟอร์
ขนาดบัฟเฟอร์จะควบคุมจำนวนโฆษณาที่โหลดล่วงหน้าที่เก็บไว้ในหน่วยความจำ โดยค่าเริ่มต้น Google จะเพิ่มประสิทธิภาพขนาดบัฟเฟอร์เพื่อปรับสมดุลการใช้หน่วยความจำและเวลาในการตอบสนองของการแสดงโฆษณา คุณสามารถตั้งค่าขนาดบัฟเฟอร์ที่กำหนดเองเพื่อเพิ่มจำนวนโฆษณาที่เก็บไว้ในหน่วยความจำ
ตัวอย่างต่อไปนี้แสดงวิธีตั้งค่าขนาดบัฟเฟอร์เป็นโฆษณาที่โหลดล่วงหน้า 2 รายการ
Kotlin
val adRequest = AdRequest.Builder(adUnitId).build() // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads. val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2) RewardedAdPreloader.start(adUnitId, preloadConfig)
Java
AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads. PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2); RewardedAdPreloader.start(adUnitId, preloadConfig);
ขีดจำกัดแคชการโหลดล่วงหน้า
GMA Next-Gen SDK กำหนดขีดจำกัดทั่วทั้งแอปสำหรับจำนวนโฆษณาที่โหลดล่วงหน้าทั้งหมด ในหน่วยโฆษณาและรหัสการโหลดล่วงหน้าทั้งหมด ดังนี้
- ขีดจำกัดเริ่มต้น: Google จะเก็บโฆษณาที่โหลดล่วงหน้าไว้ในหน่วยความจำสูงสุด 6 รายการ ขีดจำกัดนี้ใช้ร่วมกันในทุกรูปแบบและรหัสการโหลดล่วงหน้า
- เราขอแนะนำให้ตั้งค่าขนาดบัฟเฟอร์เป็น 2 สำหรับรหัสการโหลดล่วงหน้าแต่ละรายการ
ไม่บังคับ: หยุดการโหลดโฆษณาล่วงหน้า
หากไม่จำเป็นต้องแสดงโฆษณาสำหรับรหัสการโหลดล่วงหน้าที่เฉพาะเจาะจงอีกครั้งในเซสชัน คุณก็หยุดการโหลดโฆษณาล่วงหน้าได้ หากต้องการหยุดโหลดโฆษณาสำหรับรหัสการโหลดล่วงหน้าที่เฉพาะเจาะจง ให้เรียกใช้เมธอด destroy ด้วยรหัสการโหลดล่วงหน้า การเรียกใช้เมธอด destroy จะนำโฆษณาที่โหลดล่วงหน้าทั้งหมดที่เชื่อมโยงกับรหัสการโหลดล่วงหน้าออกจากแคช
ตัวอย่างต่อไปนี้แสดงวิธีหยุดการโหลดโฆษณาล่วงหน้า
Kotlin
private fun stopPreloading(adUnitId: String) { // Stops the preloading and destroy preloaded ads. RewardedAdPreloader.destroy(adUnitId) }
Java
private void stopPreloading(String adUnitId) { // Stops the preloading and destroy preloaded ads. RewardedAdPreloader.destroy(adUnitId); }
ไม่บังคับ: อ่านข้อมูลการตอบกลับ
อ่านข้อมูลการตอบกลับของโฆษณาที่โหลดล่วงหน้าถัดไปโดยไม่ต้องนำโฆษณาออกจากแคช
ตัวอย่างต่อไปนี้แสดงวิธีอ่านข้อมูลการตอบกลับของโฆษณาที่โหลดล่วงหน้าถัดไป
Kotlin
val responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId) if (responseInfo == null) { Log.e(TAG, "Failed to peek ad response info.") return } Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")
Java
ResponseInfo responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId); if (responseInfo == null) { Log.e(TAG, "Failed to peek ad response info."); return; } Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());