Next-Gen SDK
โฆษณาคั่นระหว่างหน้าที่มีการให้รางวัลเป็นรูปแบบโฆษณาที่ช่วยให้คุณนำเสนอรางวัลสำหรับโฆษณาที่ปรากฏโดยอัตโนมัติระหว่างจุดเปลี่ยนหน้าตามปกติของแอป ผู้ใช้ไม่จำเป็นต้องเลือกดูโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัล ซึ่งต่างจากโฆษณาที่มีการให้รางวัล ดูข้อมูลเพิ่มเติมได้ที่ คำแนะนำเกี่ยวกับโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัล
คู่มือนี้อธิบายวิธีผสานรวมโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัลเข้ากับแอป Android
ก่อนเริ่มต้น
ก่อนดำเนินการต่อ ให้ทำดังนี้
- ตั้งค่า GMA Next-Gen SDK
- ใช้รหัสหน่วยโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัลสำหรับการทดสอบ
ca-app-pub-3940256099942544/5354046379- เมื่อสร้างและทดสอบแอป โปรดใช้โฆษณาสำหรับการทดสอบแทนโฆษณาจริง หากไม่ดำเนินการดังกล่าว อาจส่งผลให้บัญชีถูกระงับ
- ก่อนเผยแพร่แอป ให้แทนที่รหัสนี้ด้วยรหัสหน่วยโฆษณา
- ดูรายละเอียดเกี่ยวกับโฆษณาสำหรับการทดสอบGMA Next-Gen SDK ได้ที่ หัวข้อเปิดใช้โฆษณาสำหรับการทดสอบ
ทำความเข้าใจการโหลดโฆษณาล่วงหน้า
การโหลดโฆษณาล่วงหน้าใน GMA Next-Gen SDK จะโหลดและแคชโฆษณาโดยอัตโนมัติ
การโหลดโฆษณาล่วงหน้ามีข้อดีดังนี้
- การจัดการการอ้างอิง: รักษาการอ้างอิงไว้จนกว่าจะมีการแสดงโฆษณา
- การโหลดซ้ำอัตโนมัติ: โหลดโฆษณาใหม่เมื่อมีการดึงโฆษณาจากแคช
- การลองใหม่ที่จัดการแล้ว: โหลดโฆษณาใหม่เมื่อโหลดโฆษณาไม่สำเร็จ
- การจัดการการหมดอายุ: รีเฟรชโฆษณาก่อนหมดอายุ
- การเพิ่มประสิทธิภาพแคช: เพิ่มประสิทธิภาพลำดับแคชเพื่อแสดงโฆษณาที่มีลำดับความสำคัญสูงสุด
เริ่มการโหลดโฆษณาล่วงหน้า
หากต้องการเริ่มโหลดโฆษณาล่วงหน้า ให้เรียกใช้เมธอด startPreload() เพียงครั้งเดียวเมื่อเริ่มแอป หลังจากเรียกใช้เมธอด startPreload() แล้ว
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 = rewardedInterstitialAd if (ad == null) { Log.e(TAG, "Rewarded interstitial ad is not ready yet.") return } ad.adEventCallback = object : RewardedInterstitialAdEventCallback { override fun onAdShowedFullScreenContent() { // Rewarded interstitial ad did show. } override fun onAdDismissedFullScreenContent() { // Rewarded interstitial ad did dismiss. rewardedInterstitialAd = null } override fun onAdFailedToShowFullScreenContent( fullScreenContentError: FullScreenContentError ) { // Rewarded interstitial ad failed to show. Log.e(TAG, "Rewarded interstitial ad failed to show: ${fullScreenContentError.message}") } override fun onAdImpression() { // Rewarded interstitial ad did record an impression. } override fun onAdClicked() { // Rewarded interstitial ad did record a click. } } }
Java
private void listenToAdEvents() { // Listen for ad events. if (rewardedInterstitialAd == null) { Log.e(TAG, "Rewarded interstitial ad is not ready yet."); return; } rewardedInterstitialAd.setAdEventCallback( new RewardedInterstitialAdEventCallback() { @Override public void onAdShowedFullScreenContent() { // Rewarded interstitial ad did show. } @Override public void onAdDismissedFullScreenContent() { // Rewarded interstitial ad did dismiss. rewardedInterstitialAd = null; } @Override public void onAdFailedToShowFullScreenContent( @NonNull FullScreenContentError fullScreenContentError) { // Rewarded interstitial ad failed to show. Log.e( TAG, "Rewarded interstitial ad failed to show: " + fullScreenContentError.getMessage()); } @Override public void onAdImpression() { // Rewarded interstitial ad did record an impression. } @Override public void onAdClicked() { // Rewarded interstitial ad did record a click. } }); }
ไม่บังคับ: ตรวจสอบการติดต่อกลับการยืนยันฝั่งเซิร์ฟเวอร์ (SSV)
หากแอปต้องใช้ข้อมูลเพิ่มเติมใน server-side
verification
Callback ให้ใช้ฟีเจอร์ข้อมูลที่กำหนดเองของโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัล ค่าสตริงที่ตั้งค่าไว้ในออบเจ็กต์โฆษณาคั่นระหว่างหน้าที่มีการให้รางวัลจะส่งไปยังพารามิเตอร์การค้นหา custom_data ของ SSV Callback หากไม่ได้ตั้งค่าข้อมูลที่กำหนดเอง ค่าพารามิเตอร์การค้นหา custom_data จะไม่อยู่ใน SSV Callback
ตัวอย่างโค้ดต่อไปนี้แสดงวิธีตั้งค่าข้อมูลที่กำหนดเองในออบเจ็กต์โฆษณาคั่นระหว่างหน้าที่มีการให้รางวัลก่อนแสดงโฆษณา
Kotlin
Java
แทนที่ SAMPLE_CUSTOM_DATA_STRING ด้วยข้อมูลที่กำหนดเอง
ไม่บังคับ: รอเหตุการณ์การโหลดล่วงหน้า
เมื่อเริ่มโหลดโฆษณาล่วงหน้า ให้ลงทะเบียนเพื่อรับเหตุการณ์การโหลดล่วงหน้าเพื่อรับการแจ้งเตือนเมื่อโหลดโฆษณาล่วงหน้าสำเร็จ โหลดล่วงหน้าไม่สำเร็จ หรือแคชโฆษณาหมด
ตัวอย่างต่อไปนี้แสดงวิธีลงทะเบียนเพื่อรับเหตุการณ์โฆษณาการโหลดล่วงหน้า
Kotlin
val preloadCallback = // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback. object : PreloadCallback { override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) { Log.d( TAG, "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}", ) } override fun onAdsExhausted(preloadId: String) { Log.i(TAG, "Rewarded interstitial preload ad $preloadId is not available") // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted. } override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) { Log.i(TAG, "Rewarded interstitial preload ad $preloadId is available") } } val adRequest = AdRequest.Builder(adUnitId).build() val preloadConfig = PreloadConfiguration(adRequest) RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
Java
PreloadCallback preloadCallback = // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback. new PreloadCallback() { @Override public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) { Log.d( TAG, String.format( "Rewarded interstitial preload ad %s failed to load with error: %s", preloadId, adError.getMessage())); // [Optional] Get the error response info for additional details. // ResponseInfo responseInfo = adError.getResponseInfo(); } @Override public void onAdsExhausted(@NonNull String preloadId) { Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available"); // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted. } @Override public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) { Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available"); } }; AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest); RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
เมื่อโหลดโฆษณาไม่สำเร็จ GMA Next-Gen SDK จะโหลดโฆษณาล่วงหน้าโดยอัตโนมัติและลองคำขอที่ล้มเหลวสำหรับการกำหนดค่าที่โหลดล่วงหน้าอีกครั้ง
ไม่บังคับ: ตรวจสอบความพร้อมใช้งานของโฆษณา
หากต้องการทราบว่ามีโฆษณาพร้อมใช้งานหรือไม่ ให้ตรวจสอบความพร้อมใช้งานของโฆษณา ตัวอย่างต่อไปนี้แสดงวิธีตรวจสอบว่ามีโฆษณาที่โหลดล่วงหน้าพร้อมใช้งานหรือไม่
Kotlin
private fun isAdAvailable(adUnitId: String): Boolean { return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId) }
Java
private boolean isAdAvailable(String adUnitId) { return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId); }
ไม่บังคับ: ตั้งค่าขนาดบัฟเฟอร์
ขนาดบัฟเฟอร์จะควบคุมจำนวนโฆษณาที่โหลดล่วงหน้าซึ่งเก็บไว้ในหน่วยความจำ โดยค่าเริ่มต้น Google จะเพิ่มประสิทธิภาพขนาดบัฟเฟอร์เพื่อปรับสมดุลการใช้หน่วยความจำและเวลาในการตอบสนองการแสดงโฆษณา คุณสามารถตั้งค่าขนาดบัฟเฟอร์ที่กำหนดเองเพื่อเพิ่มจำนวนโฆษณาที่เก็บไว้ในหน่วยความจำ เราขอแนะนำให้ตั้งค่าขนาดบัฟเฟอร์สูงสุดไว้ที่ 4
ตัวอย่างต่อไปนี้แสดงวิธีตั้งค่าขนาดบัฟเฟอร์เป็น 4 โฆษณาที่โหลดล่วงหน้า
Kotlin
val adRequest = AdRequest.Builder(adUnitId).build() // Maintain small or default buffer size unless rapid transitions are expected. val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4) RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
Java
// Maintain small or default buffer size unless rapid transitions are expected. AdRequest adRequest = new AdRequest.Builder(adUnitId).build(); PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4); RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
ขีดจำกัดแคชการโหลดล่วงหน้า
GMA Next-Gen SDK กำหนดขีดจำกัดทั่วทั้งแอปสำหรับจำนวนโฆษณาที่โหลดล่วงหน้าทั้งหมด ในหน่วยโฆษณาทั้งหมดและรหัสการโหลดล่วงหน้า
- ขีดจำกัดเริ่มต้น: Google จะเก็บโฆษณาที่โหลดล่วงหน้าไว้ในหน่วยความจำสูงสุด 6 รายการ ขีดจำกัดนี้ใช้ร่วมกันในทุกรูปแบบและรหัสการโหลดล่วงหน้า
- เราขอแนะนำให้ตั้งค่าขนาดบัฟเฟอร์เป็น 2 หรือ 3 ต่อรหัสการโหลดล่วงหน้า
ไม่บังคับ: หยุดการโหลดโฆษณาล่วงหน้า
หากไม่จำเป็นต้องแสดงโฆษณาสำหรับรหัสการโหลดล่วงหน้าเฉพาะอีกในเซสชัน คุณก็หยุดการโหลดโฆษณาล่วงหน้าได้ หากต้องการหยุดโหลดโฆษณาสำหรับรหัสการโหลดล่วงหน้าเฉพาะ ให้เรียกใช้เมธอด destroy() ด้วยรหัสการโหลดล่วงหน้า การเรียกใช้เมธอด destroy() จะนำโฆษณาที่โหลดล่วงหน้าทั้งหมดที่เชื่อมโยงกับรหัสการโหลดล่วงหน้าออกจากแคช
ตัวอย่างต่อไปนี้แสดงวิธีหยุดการโหลดโฆษณาล่วงหน้า
Kotlin
private fun stopPreloading(adUnitId: String) { // Stops the preloading and destroy preloaded ads. RewardedInterstitialAdPreloader.destroy(adUnitId) }
Java
private void stopPreloading(String adUnitId) { // Stops the preloading and destroy preloaded ads. RewardedInterstitialAdPreloader.destroy(adUnitId); }
ไม่บังคับ: อ่านข้อมูลการตอบกลับ
อ่านข้อมูลการตอบกลับของโฆษณาที่โหลดล่วงหน้าถัดไปโดยไม่ต้องนำโฆษณาออกจากแคช
ตัวอย่างต่อไปนี้แสดงวิธีอ่านข้อมูลการตอบกลับของโฆษณาที่โหลดล่วงหน้าถัดไป
Kotlin
val responseInfo = RewardedInterstitialAdPreloader.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 = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId); if (responseInfo == null) { Log.e(TAG, "Failed to peek ad response info."); return; } Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());