โฆษณาการแสดงภาพซ้อนภาพ (PIP) จะแสดงในหน้าต่างลอยที่อยู่ด้านบนของ เนื้อหาบนหน้าจอ เช่น บทความ ฟีด หรือการเล่นเกม รูปแบบนี้ช่วยให้ ผู้ใช้โต้ตอบกับแอปของคุณได้ในขณะที่โฆษณายังคงแสดงอยู่ เลือกรูปแบบนี้เพื่อแสดงโฆษณาที่ ไม่ครอบครองทั้งหน้าจอ
คู่มือนี้ครอบคลุมการขอและแสดงโฆษณาแบบ Picture-in-Picture ในแอปของคุณ โดยใช้ GMA Next-Gen SDK
ก่อนเริ่มต้น
ก่อนดำเนินการต่อ ให้ทำดังนี้
ติดตั้ง GMA Next-Gen SDK เวอร์ชัน
1.4.0ขึ้นไปเปิดใช้โฆษณาทดสอบและใช้รหัสหน่วยโฆษณาทดสอบต่อไปนี้
/21775744923/example/picture-in-picture
โหลดโฆษณา
หากต้องการโหลดออบเจ็กต์ PictureInPictureAd ให้สร้างคำขอโฆษณาและเรียกใช้เมธอด load ดังนี้
Kotlin
Java
แทนที่ AD_UNIT_ID ด้วยรหัสหน่วยโฆษณา
แสดงโฆษณา
หากต้องการแสดงโฆษณาแบบ Picture-in-Picture บนหน้าจอ ให้กำหนดค่า
ตัวเลือก Picture-in-Picture แล้วเรียกใช้เมธอด show ตัวอย่างต่อไปนี้
ตั้งค่าตำแหน่งเริ่มต้นของโฆษณาและขอบเขตการนำเสนอเป็นหน้าจอ
Kotlin
private fun showPictureInPictureAd(activity: Activity) { // Capture the ad reference saved from the onAdLoaded callback. val ad = pipAd if (ad != null) { val options = PictureInPictureAdOptions.Builder() // Uses the Google Mobile Ads SDK's default screen position. .setPosition(PictureInPictureAdPosition.DEFAULT) // Binds the ad lifecycle to the host screen. .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN) .build() ad.show(activity, options) } else { Log.d(TAG, "No ad to show.") } }
Java
private void showPictureInPictureAd(@NonNull Activity activity) { // Use the ad reference saved from the onAdLoaded callback. if (pipAd != null) { PictureInPictureAdOptions options = new PictureInPictureAdOptions.Builder() // Uses the Google Mobile Ads SDK's default screen position. .setPosition(PictureInPictureAdPosition.DEFAULT) // Binds the ad lifecycle to the host screen. .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN) .build(); pipAd.show(activity, options); } else { Log.d(TAG, "No ad to show."); } }
กำหนดตำแหน่ง
โดยค่าเริ่มต้น GMA Next-Gen SDK จะแสดงโฆษณาแบบภาพซ้อนภาพที่มุมขวาล่าง ของหน้าจอเมื่อแสดงเป็นครั้งแรก หรือที่ตำแหน่งล่าสุดที่ทราบหาก เคยแสดงมาก่อน หากต้องการปรับแต่งตำแหน่งที่โฆษณาปรากฏ ให้ตั้งค่าตำแหน่งใน ตัวเลือกภาพซ้อนภาพ ตัวอย่างต่อไปนี้จะกำหนดตำแหน่งที่ด้านบนของ เนื้อหาที่มุมซ้ายบนของหน้าจอ
Kotlin
private fun createTopLeftPositionOptions(): PictureInPictureAdOptions { return PictureInPictureAdOptions.Builder() // Sets the ad position to the top-left corner of the screen. .setPosition(PictureInPictureAdPosition.TOP_LEFT) .build() }
Java
private PictureInPictureAdOptions createTopLeftPositionOptions() { return new PictureInPictureAdOptions.Builder() // Sets the ad position to the top-left corner of the screen. .setPosition(PictureInPictureAdPosition.TOP_LEFT) .build(); }
ดูตำแหน่งว่างทั้งหมดได้ที่
PictureInPictureAdPosition
กำหนดขอบเขตการนำเสนอ
โดยค่าเริ่มต้น GMA Next-Gen SDK จะเชื่อมโยงโฆษณาแบบการแสดงภาพซ้อนภาพกับหน้าจอโฮสต์ปัจจุบัน GMA Next-Gen SDK ปิดโฆษณาเมื่อลำดับชั้นการแสดงผลของหน้าจอโฮสต์ไม่อยู่ในหน่วยความจำอีกต่อไป หากต้องการให้โฆษณายังคงแสดงอยู่หลังจากนำหน้าจอโฮสต์ออกจากหน่วยความจำ ให้ตั้งค่าขอบเขตการนำเสนอเป็นแอปพลิเคชันโดยทำดังนี้
Kotlin
private fun createApplicationScopedOptions(): PictureInPictureAdOptions { return PictureInPictureAdOptions.Builder() // Keeps the ad visible beyond the host screen's lifecycle. .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION) .build() }
Java
private PictureInPictureAdOptions createApplicationScopedOptions() { return new PictureInPictureAdOptions.Builder() // Keeps the ad visible beyond the host screen's lifecycle. .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION) .build(); }
ดูข้อมูลเพิ่มเติมได้ที่ทำให้โฆษณามองเห็นได้ในทุกหน้าจอ
ตั้งค่าการเรียกกลับของเหตุการณ์โฆษณา
หากต้องการจัดการเหตุการณ์วงจรโฆษณาแบบภาพซ้อนภาพ ให้ตั้งค่า Callback ของเหตุการณ์ใน โฆษณาก่อนแสดง การเรียกกลับนี้จะรายงานเหตุการณ์มาตรฐาน เช่น การคลิก และการแสดงผล การเรียกกลับนี้ยังรายงานเหตุการณ์เฉพาะการแสดงภาพซ้อนภาพ เช่น เมื่อโฆษณาแสดงหรือซ่อนอยู่ด้วย
Kotlin
private fun setAdEventCallback(pipAd: PictureInPictureAd) { pipAd.adEventCallback = object : PictureInPictureAdEventCallback { override fun onAdShown() { Log.d(TAG, "Picture-in-Picture ad shown.") } override fun onAdHidden() { Log.d(TAG, "Picture-in-Picture ad hidden.") } override fun onAdImpression() { Log.d(TAG, "Picture-in-Picture ad recorded an impression.") } override fun onAdClicked() { Log.d(TAG, "Picture-in-Picture ad recorded a click.") } override fun onAdShowedFullScreenContent() { Log.d(TAG, "Picture-in-Picture ad showed full screen content.") } override fun onAdDismissedFullScreenContent() { Log.d(TAG, "Picture-in-Picture ad dismissed full screen content.") } override fun onAdFailedToShowFullScreenContent( fullScreenContentError: FullScreenContentError ) { Log.w( TAG, "Picture-in-Picture ad failed to show full screen content: $fullScreenContentError", ) } override fun onAdPaid(value: AdValue) { Log.d(TAG, "Picture-in-Picture ad paid: ${value.valueMicros} ${value.currencyCode}") } } }
Java
private void setAdEventCallback(@NonNull PictureInPictureAd pipAd) { pipAd.setAdEventCallback( new PictureInPictureAdEventCallback() { @Override public void onAdShown() { Log.d(TAG, "Picture-in-Picture ad shown."); } @Override public void onAdHidden() { Log.d(TAG, "Picture-in-Picture ad hidden."); } @Override public void onAdImpression() { Log.d(TAG, "Picture-in-Picture ad recorded an impression."); } @Override public void onAdClicked() { Log.d(TAG, "Picture-in-Picture ad recorded a click."); } @Override public void onAdShowedFullScreenContent() { Log.d(TAG, "Picture-in-Picture ad showed full screen content."); } @Override public void onAdDismissedFullScreenContent() { Log.d(TAG, "Picture-in-Picture ad dismissed full screen content."); } @Override public void onAdFailedToShowFullScreenContent( @NonNull FullScreenContentError fullScreenContentError) { Log.w( TAG, "Picture-in-Picture ad failed to show full screen content: " + fullScreenContentError); } @Override public void onAdPaid(@NonNull AdValue value) { Log.d( TAG, "Picture-in-Picture ad paid: " + value.getValueMicros() + " " + value.getCurrencyCode()); } }); }
ซ่อนโฆษณา
หากต้องการนำโฆษณาลอยออกจากหน้าจอ ให้เรียกใช้เมธอด hide เมธอดนี้
เรียกใช้ Callback ของเหตุการณ์ที่ซ่อนโฆษณา
Kotlin
private fun hidePictureInPictureAd() { // Capture the ad reference saved from the onAdLoaded callback. val ad = pipAd if (ad != null) { ad.hide() } else { Log.d(TAG, "No ad to hide.") } }
Java
private void hidePictureInPictureAd() { // Use the ad reference saved from the onAdLoaded callback. if (pipAd != null) { pipAd.hide(); } else { Log.d(TAG, "No ad to hide."); } }
ล้างข้อมูลทรัพยากรโฆษณา
หากไม่ต้องการให้หน่วยความจำรั่วไหล ให้ทิ้งการอ้างอิงไปยังออบเจ็กต์โฆษณาเมื่อแอป ใช้โฆษณาเสร็จแล้ว เช่น เมื่อแอปของคุณไม่แสดงหรือ โต้ตอบกับโฆษณาอีก สำหรับโฆษณาที่กำหนดขอบเขตระดับหน้าจอ ให้ทิ้งการอ้างอิงเมื่อแอปนำหน้าจอโฮสต์ออกจากหน่วยความจำ สําหรับโฆษณาที่กำหนดขอบเขตเป็นแอป ให้เก็บการอ้างอิงโฆษณาไว้ขณะที่ผู้ใช้ไปยังหน้าจอต่างๆ และทิ้งการอ้างอิงเมื่อผู้ใช้ปิดโฆษณา
Kotlin
private fun cleanUpPictureInPictureAd() { pipAd?.destroy() pipAd = null }
Java
private void cleanUpPictureInPictureAd() { // Use the ad reference saved from the onAdLoaded callback. if (pipAd != null) { pipAd.destroy(); pipAd = null; } }
แสดงโฆษณาในหน้าจอต่างๆ
เมื่อตั้งค่าขอบเขตของงานนำเสนอเป็นแอปพลิเคชัน โฆษณาแบบ Picture-in-Picture จะยังคงมองเห็นได้แม้ว่าแอปจะนำหน้าจอโฮสติ้งออกจากหน่วยความจำแล้วก็ตาม หากต้องการโต้ตอบหรือปิดโฆษณาเมื่อผู้ใช้ออกจากหน้าจอโฮสต์ แอปของคุณต้องคงสิทธิ์เข้าถึงโฆษณาแบบภาพซ้อนภาพไว้ เราขอแนะนําให้ เก็บโฆษณาไว้ในตัวจัดการสถานะที่ใช้ร่วมกันหรือ Singleton ระดับแอปแทนที่จะเก็บไว้ใน ตัวแปรอินสแตนซ์ของหน้าจอเดียว
ดูตัวอย่างวิธีทำให้โฆษณามองเห็นได้ในทุกหน้าจอได้ใน แอปตัวอย่างต่อไปนี้