ใช้โฆษณาการแสดงภาพซ้อนภาพ (เบต้า)

เลือกแพลตฟอร์ม: Android iOS

การแสดงภาพซ้อนภาพ

โฆษณาการแสดงภาพซ้อนภาพ (PIP) จะแสดงในหน้าต่างลอยที่อยู่ด้านบนของ เนื้อหาบนหน้าจอ เช่น บทความ ฟีด หรือการเล่นเกม รูปแบบนี้ช่วยให้ ผู้ใช้โต้ตอบกับแอปของคุณได้ในขณะที่โฆษณายังคงแสดงอยู่ เลือกรูปแบบนี้เพื่อแสดงโฆษณาที่ ไม่ครอบครองทั้งหน้าจอ

คู่มือนี้ครอบคลุมการขอและแสดงโฆษณาแบบ Picture-in-Picture ในแอปของคุณ โดยใช้ GMA Next-Gen SDK

ก่อนเริ่มต้น

ก่อนดำเนินการต่อ ให้ทำดังนี้

โหลดโฆษณา

หากต้องการโหลดออบเจ็กต์ PictureInPictureAd ให้สร้างคำขอโฆษณาและเรียกใช้เมธอด load ดังนี้

Kotlin

private fun loadPictureInPictureAd() {
  val request = PictureInPictureAdRequest.Builder(AD_UNIT_ID).build()

  PictureInPictureAd.load(
    request,
    object : AdLoadCallback<PictureInPictureAd> {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.w(TAG, "Picture-in-Picture ad failed to load: $adError")
      }

      override fun onAdLoaded(ad: PictureInPictureAd) {
        Log.d(TAG, "Picture-in-Picture ad loaded.")

        // Capture the PictureInPictureAd reference for later use.
        pipAd = ad
        setAdEventCallback(ad)
      }
    },
  )
}

Java

private void loadPictureInPictureAd() {
  PictureInPictureAdRequest request = new PictureInPictureAdRequest.Builder(AD_UNIT_ID).build();

  PictureInPictureAd.load(
      request,
      new AdLoadCallback<PictureInPictureAd>() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.w(TAG, "Picture-in-Picture ad failed to load: " + adError);
        }

        @Override
        public void onAdLoaded(@NonNull PictureInPictureAd ad) {
          Log.d(TAG, "Picture-in-Picture ad loaded.");

          // Capture the PictureInPictureAd reference for later use.
          pipAd = ad;
          setAdEventCallback(ad);
        }
      });
}

แทนที่ 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 ระดับแอปแทนที่จะเก็บไว้ใน ตัวแปรอินสแตนซ์ของหน้าจอเดียว

ดูตัวอย่างวิธีทำให้โฆษณามองเห็นได้ในทุกหน้าจอได้ใน แอปตัวอย่างต่อไปนี้