ตั้งค่าโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัล

เลือกแพลตฟอร์ม: Android iOS Unity Flutter Android (เดิม)

โฆษณาคั่นระหว่างหน้าที่มีการให้รางวัลเป็นรูปแบบที่ช่วยให้คุณนำเสนอรางวัลสำหรับโฆษณาที่ปรากฏโดยอัตโนมัติระหว่างจุดเปลี่ยนหน้าตามปกติของแอป ผู้ใช้ไม่จําเป็นต้องเลือกดูโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัล ซึ่งต่างจากโฆษณาที่มีการให้รางวัล ดูข้อมูลเพิ่มเติมได้ที่หลักเกณฑ์ของโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัล

คู่มือนี้อธิบายวิธีผสานรวมโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัลลงในแอป Android

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

โปรดทำสิ่งต่อไปนี้ก่อนดำเนินการต่อ

• ตั้งค่า GMA Next-Gen SDK
• ใช้รหัสหน่วยโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัลแบบทดสอบ ca-app-pub-3940256099942544/5354046379
  • เมื่อสร้างและทดสอบแอป โปรดตรวจสอบว่าคุณใช้โฆษณาทดสอบ ไม่ใช่โฆษณาจริงที่ใช้งานจริง หากคุณไม่ใช้รหัสหน่วยโฆษณาทดสอบ Google อาจระงับบัญชีของคุณ
  • ก่อนเผยแพร่แอป ให้แทนที่รหัสนี้ด้วยรหัสหน่วยโฆษณา
  • ดูรายละเอียดเกี่ยวกับโฆษณาทดสอบของ GMA Next-Gen SDK ได้ที่เปิดใช้โฆษณาทดสอบ

ทำความเข้าใจการโหลดโฆษณาล่วงหน้า (เบต้า)

การโหลดโฆษณาล่วงหน้าใน GMA Next-Gen SDK จะโหลดและแคชโฆษณาโดยอัตโนมัติ

การโหลดโฆษณาล่วงหน้ามีประโยชน์ดังนี้

• การจัดการข้อมูลอ้างอิง: เก็บข้อมูลอ้างอิงไว้จนกว่าโฆษณาจะแสดง
• การโหลดซ้ำอัตโนมัติ: โหลดโฆษณาใหม่เมื่อดึงโฆษณาจากแคช
• การลองใหม่ที่มีการจัดการ: โหลดโฆษณาใหม่เมื่อโหลดโฆษณาไม่สำเร็จ
• การจัดการการหมดอายุ: รีเฟรชโฆษณาก่อนหมดอายุ
• การเพิ่มประสิทธิภาพแคช: เพิ่มประสิทธิภาพลำดับแคชเพื่อแสดงโฆษณาที่มีลำดับความสำคัญสูงสุด

หมายเหตุ: หากต้องการโหลดโฆษณาด้วยตนเอง โปรดดูหัวข้อโหลดโฆษณาคั่นระหว่างหน้าที่มีการให้รางวัลรายการเดียว

เริ่มการโหลดโฆษณาล่วงหน้า

หากต้องการเริ่มโหลดโฆษณาล่วงหน้า ให้เรียกใช้เมธอด start 1 ครั้งเมื่อเริ่มต้น GMA Next-Gen SDK หลังจากที่คุณเรียกใช้เมธอด start แล้ว GMA Next-Gen SDK จะโหลดโฆษณาล่วงหน้าโดยอัตโนมัติและลองส่งคำขอที่ล้มเหลวอีกครั้งสำหรับการกำหนดค่าที่โหลดไว้ล่วงหน้า

ตัวอย่างต่อไปนี้แสดงวิธีเริ่มโหลดโฆษณาล่วงหน้า

Kotlin

private fun startPreloading(adUnitId: String) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

แทนที่ AD_UNIT_ID ด้วยรหัสหน่วยโฆษณา

ตัวอย่างก่อนหน้านี้แสดงวิธีใช้รหัสหน่วยโฆษณาเป็นรหัสการโหลดล่วงหน้า รหัสการโหลดล่วงหน้าคือตัวระบุสตริงที่คุณสร้างขึ้นเพื่อระบุการกำหนดค่าการโหลดโฆษณาล่วงหน้า หากแอปของคุณต้องมีการกำหนดค่าการกำหนดเป้าหมายหลายรายการสำหรับรหัสหน่วยโฆษณาเดียวกัน ให้ส่งตัวระบุสตริงที่กำหนดเอง

การโหลดโฆษณาล่วงหน้าไม่รองรับการเปลี่ยนแปลงพารามิเตอร์การกำหนดเป้าหมายหรือคำขอโฆษณา หากต้องการเปลี่ยนพารามิเตอร์การกำหนดเป้าหมายระหว่างคำขอ ให้ใช้การโหลดครั้งเดียว

รับและแสดงโฆษณาที่โหลดไว้ล่วงหน้า

ก่อนแสดงโฆษณา ให้เรียกใช้เมธอด pollAd อย่าจัดเก็บออบเจ็กต์โฆษณาที่โหลดไว้ล่วงหน้า เมื่อคุณเรียกใช้เมธอด pollAd GMA Next-Gen SDK จะดึงข้อมูลโฆษณาที่พร้อมใช้งานและโหลดโฆษณาถัดไปล่วงหน้าในเบื้องหลังโดยอัตโนมัติ หากไม่มีโฆษณาที่พร้อมใช้งาน GMA Next-Gen SDK จะไม่แสดงโฆษณา

เมื่อมีออบเจ็กต์โฆษณาที่พร้อมใช้งาน ให้เรียกใช้เมธอด show เพื่อแสดงโฆษณา ใช้ Listener ของรางวัลเพื่อจัดการกิจกรรมที่มีการให้รางวัล ตัวอย่างต่อไปนี้แสดงวิธีดึงข้อมูลและแสดงโฆษณาที่โหลดไว้ล่วงหน้า

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

เมื่อแอปของคุณไปถึงตำแหน่งโฆษณาและเรียกใช้เมธอด show ได้ ให้เรียกใช้เมธอด pollAd อย่าเรียกใช้เมธอด pollAd ใน Callback ของการโหลดล่วงหน้าหรือหลังจากตรวจสอบเมธอด isAdAvailable เพื่อเก็บโฆษณาไว้ หากต้องการตรวจสอบข้อมูลเมตาของโฆษณาก่อนแสดงโฆษณา โปรดอ่านข้อมูลการตอบกลับโดยไม่ต้องนำโฆษณาออกจากแคช

รอเหตุการณ์โฆษณา

ก่อนแสดงโฆษณา ให้รอเหตุการณ์โฆษณา ตัวอย่างต่อไปนี้จะบันทึก 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.
        }
      });
}

ไม่บังคับ: ตรวจสอบความถูกต้องของ Callback ของการยืนยันฝั่งเซิร์ฟเวอร์ (SSV)

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

• พารามิเตอร์การค้นหา user_id: ระบุผู้ใช้ที่จะให้เครดิต เช่น รหัสบัญชีภายใน
• พารามิเตอร์การค้นหา custom_data: มีข้อมูลแอป เช่น ตำแหน่งรางวัล ระดับเกม หรือ Nonce ที่เซิร์ฟเวอร์สร้างขึ้น

หากคุณไม่ได้ตั้งค่า Google จะละเว้นพารามิเตอร์การค้นหานั้นจาก SSV Callback

ตัวอย่างต่อไปนี้จะตั้งค่าข้อมูลที่กำหนดเองในออบเจ็กต์โฆษณาก่อนแสดงโฆษณา

Kotlin

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

แทนที่ SAMPLE_CUSTOM_DATA_STRING ด้วยข้อมูลที่กำหนดเอง

ประเด็นสำคัญ: พารามิเตอร์การค้นหา custom_data จะเข้ารหัสเปอร์เซ็นต์ ก่อนแยกวิเคราะห์ค่า ให้ถอดรหัส URL ของสตริงในเซิร์ฟเวอร์และยืนยันลายเซ็น Callback ก่อนที่จะเชื่อถือพารามิเตอร์การค้นหา user_id หรือ custom_data

ไม่บังคับ: ฟังเหตุการณ์การโหลดล่วงหน้า

เมื่อเริ่มโหลดโฆษณาล่วงหน้า ให้ลงทะเบียนรับเหตุการณ์โหลดล่วงหน้าเพื่อรับการแจ้งเตือนเมื่อโหลดโฆษณาล่วงหน้าสำเร็จ โหลดล่วงหน้าไม่สำเร็จ หรือแคชโฆษณาหมด

ตัวอย่างต่อไปนี้แสดงวิธีลงทะเบียนสำหรับเหตุการณ์โฆษณาที่โหลดล่วงหน้า

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 จะโหลดโฆษณาล่วงหน้าโดยอัตโนมัติและลองส่งคำขอที่ล้มเหลวอีกครั้งสำหรับการกำหนดค่าที่โหลดไว้ล่วงหน้า อย่าเรียกใช้คำขอโหลดด้วยตนเองใน Callback ที่ไม่สำเร็จ ในเมธอด Callback ของเหตุการณ์โหลดล่วงหน้า อย่าเรียกใช้เมธอด pollAd, destroy หรือ start การเรียกใช้เมธอดเหล่านี้ใน Callback อาจทำให้เกิดลูปการโหลดแบบเรียกซ้ำ

ไม่บังคับ: ตรวจสอบความพร้อมใช้งานของโฆษณา

หากต้องการทราบว่ามีโฆษณาพร้อมใช้งานหรือไม่ ให้ตรวจสอบความพร้อมใช้งานของโฆษณา ตัวอย่างต่อไปนี้จะตรวจสอบว่ามีโฆษณาที่โหลดไว้ล่วงหน้าหรือไม่

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId);
}

ไม่บังคับ: ตั้งค่าขนาดบัฟเฟอร์

ขนาดบัฟเฟอร์จะควบคุมจำนวนโฆษณาที่โหลดล่วงหน้าซึ่งเก็บไว้ในหน่วยความจำ โดยค่าเริ่มต้น Google จะเพิ่มประสิทธิภาพขนาดบัฟเฟอร์เพื่อสร้างสมดุลระหว่างการใช้หน่วยความจำและเวลาในการตอบสนองของการแสดงโฆษณา คุณสามารถกำหนดขนาดบัฟเฟอร์ที่กำหนดเองเพื่อเพิ่มหรือลดจำนวนโฆษณาที่เก็บไว้ในหน่วยความจำได้ เราขอแนะนำให้ใช้ขนาดบัฟเฟอร์ของโฆษณาที่โหลดไว้ล่วงหน้า 2 รายการ หากการเข้าชมส่วนใหญ่มาจากอุปกรณ์ที่มีหน่วยความจำต่ำ ให้ลดขนาดบัฟเฟอร์

ตัวอย่างต่อไปนี้แสดงวิธีตั้งค่าขนาดบัฟเฟอร์

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  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);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

ขีดจำกัดแคชที่โหลดล่วงหน้า

GMA Next-Gen SDK บังคับใช้ขีดจำกัดทั่วทั้งแอปสำหรับจำนวนโฆษณาที่โหลดล่วงหน้าทั้งหมดในหน่วยโฆษณาและรหัสการโหลดล่วงหน้าทั้งหมด ดังนี้

• ขีดจำกัดเริ่มต้น: Google จะเก็บโฆษณาที่โหลดไว้ล่วงหน้าไว้ในหน่วยความจำได้สูงสุด 6 รายการ ขีดจำกัดนี้จะใช้ร่วมกันในทุกรูปแบบและรหัสการโหลดล่วงหน้า
• เราขอแนะนำให้ใช้ขนาดบัฟเฟอร์เป็น 2 สำหรับรหัสการโหลดล่วงหน้าแต่ละรหัส

หมายเหตุ: หากแอปของคุณจะได้รับประโยชน์จากการเพิ่มขีดจำกัดทั่วทั้งแอป โปรดติดต่อผู้จัดการฝ่ายดูแลลูกค้าเพื่อขอเพิ่มขีดจำกัด

ไม่บังคับ: หยุดโหลดโฆษณาล่วงหน้า

เปิดใช้การโหลดล่วงหน้าไว้ขณะที่แอปแสดงโฆษณา ในระหว่างนี้ อย่าใช้วิธี destroy หากไม่จำเป็นต้องแสดงโฆษณาสำหรับรหัสการโหลดล่วงหน้าที่เฉพาะเจาะจงอีกในเซสชัน คุณสามารถหยุดโหลดโฆษณาล่วงหน้าได้ หากต้องการหยุดโหลดโฆษณาสำหรับรหัสการโหลดล่วงหน้าที่เฉพาะเจาะจง ให้เรียกใช้เมธอด 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);
}

ไม่บังคับ: อ่านข้อมูลคำตอบ

อ่านข้อมูลการตอบกลับของโฆษณาที่โหลดไว้ล่วงหน้าถัดไปโดยไม่ต้องนำโฆษณาออกจากแคช หากต้องการตรวจสอบข้อมูลเมตาของโฆษณาก่อนแสดงโฆษณา ให้อ่านข้อมูลการตอบกลับแทนการเรียกใช้เมธอด pollAd

ตัวอย่างต่อไปนี้แสดงวิธีอ่านข้อมูลการตอบกลับโฆษณาที่โหลดไว้ล่วงหน้าถัดไป

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());