Thiết lập quảng cáo có tặng thưởng

Chọn nền tảng: Android iOS Unity Flutter Android (Phiên bản cũ)

Quảng cáo có tặng thưởng cho phép bạn tặng người dùng vật phẩm trong ứng dụng vì đã tương tác với quảng cáo dạng video, quảng cáo có thể chơi và tham gia cuộc khảo sát.

Hướng dẫn này trình bày cách tích hợp quảng cáo có tặng thưởng vào ứng dụng Android.

Trước khi bắt đầu

Trước khi tiếp tục, hãy làm như sau:

  • Thiết lập GMA Next-Gen SDK.
  • Sử dụng mã đơn vị quảng cáo có tặng thưởng thử nghiệm ca-app-pub-3940256099942544/5224354917.
    • Khi bạn tạo và thử nghiệm ứng dụng, hãy nhớ sử dụng quảng cáo thử nghiệm thay vì quảng cáo đang chạy trong thực tế. Nếu bạn không sử dụng mã đơn vị quảng cáo thử nghiệm, Google có thể tạm ngưng tài khoản của bạn.
    • Trước khi xuất bản ứng dụng, hãy thay thế mã này bằng mã đơn vị quảng cáo của bạn.
    • Để biết thông tin chi tiết về quảng cáo thử nghiệm GMA Next-Gen SDK, hãy xem Bật quảng cáo thử nghiệm.

Tìm hiểu về tính năng tải trước quảng cáo (thử nghiệm)

Tính năng tải trước quảng cáo trong GMA Next-Gen SDK sẽ tự động hoá quá trình tải và lưu vào bộ nhớ đệm quảng cáo.

Tính năng tải trước quảng cáo mang lại những lợi ích sau:

  • Quản lý tham chiếu: duy trì các tham chiếu cho đến khi quảng cáo được hiển thị.
  • Tự động tải lại: tải một quảng cáo mới khi một quảng cáo được truy xuất từ bộ nhớ đệm.
  • Quản lý số lần thử lại: tải một quảng cáo mới khi một quảng cáo không tải được.
  • Xử lý thời gian hết hạn: làm mới quảng cáo trước khi hết hạn.
  • Tối ưu hoá bộ nhớ đệm: tối ưu hoá thứ tự bộ nhớ đệm để phân phối quảng cáo có mức độ ưu tiên cao nhất.

Bắt đầu tải trước quảng cáo

Để bắt đầu tải trước quảng cáo, hãy gọi phương thức start một lần khi bạn khởi chạy GMA Next-Gen SDK. Sau khi bạn gọi phương thức start, GMA Next-Gen SDK sẽ tự động tải trước quảng cáo và thử lại các yêu cầu không thành công đối với các cấu hình được tải trước.

Ví dụ sau đây cho thấy cách bắt đầu tải trước quảng cáo:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig);

Thay thế AD_UNIT_ID bằng mã đơn vị quảng cáo của bạn.

Ví dụ trước cho thấy cách sử dụng mã đơn vị quảng cáo làm mã tải trước. Mã tải trước là một giá trị nhận dạng chuỗi mà bạn tạo để xác định cấu hình tải trước quảng cáo. Nếu ứng dụng của bạn yêu cầu nhiều cấu hình nhắm mục tiêu cho cùng một mã đơn vị quảng cáo, hãy chuyển giá trị nhận dạng chuỗi tuỳ chỉnh.

Tính năng tải trước quảng cáo không hỗ trợ việc thay đổi các tham số nhắm mục tiêu hoặc yêu cầu quảng cáo. Nếu bạn cần thay đổi các tham số nhắm mục tiêu giữa các yêu cầu, hãy sử dụng tính năng tải một lần.

Nhận và hiển thị quảng cáo được tải trước

Trước khi hiển thị quảng cáo, hãy gọi phương thức pollAd. Không lưu đối tượng quảng cáo được tải trước. Khi bạn gọi phương thức pollAd, GMA Next-Gen SDK sẽ truy xuất một quảng cáo có sẵn và tự động tải trước quảng cáo tiếp theo ở chế độ nền. Nếu không có quảng cáo nào khả dụng, GMA Next-Gen SDK sẽ không trả về quảng cáo nào.

Khi bạn có một đối tượng quảng cáo có sẵn, hãy gọi phương thức show để hiển thị quảng cáo. Sử dụng trình nghe sự kiện có tặng thưởng để xử lý các sự kiện có tặng thưởng. Ví dụ sau đây cho thấy cách truy xuất và hiển thị một quảng cáo được tải trước:

Kotlin

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

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded 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 RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

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

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

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

Khi ứng dụng của bạn đến một vị trí đặt quảng cáo và có thể gọi phương thức show, hãy gọi phương thức pollAd. Không gọi phương thức pollAd trong lệnh gọi lại tải trước hoặc sau khi kiểm tra phương thức isAdAvailable để giữ một quảng cáo. Nếu bạn cần kiểm tra siêu dữ liệu quảng cáo trước khi hiển thị quảng cáo, hãy đọc thông tin phản hồi mà không cần xoá quảng cáo khỏi bộ nhớ đệm.

Theo dõi các sự kiện quảng cáo

Trước khi hiển thị quảng cáo, hãy theo dõi các sự kiện quảng cáo. Ví dụ sau đây đăng ký lệnh gọi lại cho các sự kiện quảng cáo:

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.
        }
      });
}

Không bắt buộc: Xác thực lệnh gọi lại của tính năng xác minh phía máy chủ (SSV)

Để chuyển ngữ cảnh người dùng và ứng dụng trong lệnh gọi lại của tính năng xác minh phía máy chủ (SSV), hãy đặt các lựa chọn xác minh trên đối tượng quảng cáo trước khi hiển thị quảng cáo. Vì lệnh gọi lại của SSV đến máy chủ của bạn từ Google mà không có trạng thái phiên, hãy đính kèm các chuỗi không bắt buộc sau đây. Google chuyển tiếp các chuỗi này mà không thay đổi dưới dạng các tham số truy vấn đã ký trong lệnh gọi lại của SSV.

  • Tham số truy vấn user_id: Xác định người dùng cần ghi có, chẳng hạn như mã tài khoản nội bộ.
  • Tham số truy vấn custom_data: Chứa dữ liệu ứng dụng, chẳng hạn như vị trí đặt phần thưởng, cấp độ trò chơi hoặc giá trị nonce do máy chủ tạo.

Nếu bạn không đặt giá trị, Google sẽ bỏ qua tham số truy vấn đó khỏi lệnh gọi lại của SSV.

Ví dụ sau đây đặt dữ liệu tuỳ chỉnh trên một đối tượng quảng cáo trước khi hiển thị quảng cáo:

Kotlin

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

Java

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

Thay thế SAMPLE_CUSTOM_DATA_STRING bằng dữ liệu tuỳ chỉnh của bạn.

Lưu ý quan trọng: Tham số truy vấn custom_data được mã hoá theo tỷ lệ phần trăm. Trước khi bạn phân tích cú pháp giá trị, hãy giải mã URL chuỗi trên máy chủ của bạn và xác minh chữ ký gọi lại trước khi tin tưởng các tham số truy vấn user_id hoặc custom_data.

Không bắt buộc: Theo dõi các sự kiện tải trước

Khi bạn bắt đầu tải trước quảng cáo, hãy đăng ký các sự kiện tải trước để nhận thông báo khi quảng cáo được tải trước thành công, không tải trước được hoặc bộ nhớ đệm quảng cáo đã cạn kiệt.

Ví dụ sau đây cho thấy cách đăng ký các sự kiện quảng cáo tải trước:

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

Khi một quảng cáo không tải được, GMA Next-Gen SDK sẽ tự động tải trước quảng cáo và thử lại các yêu cầu không thành công đối với các cấu hình được tải trước. Không gọi các yêu cầu tải thủ công trong lệnh gọi lại lỗi. Trong các phương thức gọi lại sự kiện tải trước, không gọi các phương thức pollAd, destroy hoặc start. Việc gọi các phương thức này trong lệnh gọi lại có thể gọi các vòng lặp tải đệ quy.

Không bắt buộc: Kiểm tra tính khả dụng của quảng cáo

Nếu bạn cần biết liệu có quảng cáo hay không, hãy kiểm tra tính khả dụng của quảng cáo. Ví dụ sau đây kiểm tra xem có quảng cáo được tải trước hay không:

Kotlin

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

Java

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

Không bắt buộc: Đặt kích thước bộ nhớ đệm

Dung lượng bộ nhớ đệm kiểm soát số lượng quảng cáo được tải trước và lưu trong bộ nhớ. Theo mặc định, Google tối ưu hoá dung lượng bộ nhớ đệm để cân bằng mức tiêu thụ bộ nhớ và độ trễ phân phát quảng cáo. Bạn có thể đặt dung lượng bộ nhớ đệm tuỳ chỉnh để tăng hoặc giảm số lượng quảng cáo được lưu trong bộ nhớ. Bạn nên đặt dung lượng bộ nhớ đệm là 2 quảng cáo được tải trước. Nếu phần lớn lưu lượng truy cập của bạn đến từ các thiết bị có bộ nhớ thấp, hãy giảm dung lượng bộ nhớ đệm.

Ví dụ sau đây cho thấy cách đặt dung lượng bộ nhớ đệm:

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

Giới hạn bộ nhớ đệm tải trước

GMA Next-Gen SDK áp dụng giới hạn trên toàn ứng dụng đối với tổng số quảng cáo được tải trước trên tất cả các đơn vị quảng cáo và mã tải trước:

  • Giới hạn mặc định: Google lưu tối đa 6 quảng cáo được tải trước trong bộ nhớ. Giới hạn này được chia sẻ trên tất cả các định dạng và mã tải trước.
  • Chúng tôi đề xuất giữ dung lượng bộ nhớ đệm là hai cho mỗi mã tải trước.

Không bắt buộc: Ngừng tải trước quảng cáo

Luôn bật tính năng tải trước trong khi ứng dụng của bạn phân phát quảng cáo. Trong thời gian này, không sử dụng phương thức destroy. Nếu không cần hiển thị lại quảng cáo cho một mã tải trước cụ thể trong phiên, bạn có thể ngừng tải trước quảng cáo. Để ngừng tải quảng cáo cho một mã tải trước cụ thể, hãy gọi phương thức destroy bằng mã tải trước. Việc gọi phương thức destroy sẽ xoá tất cả quảng cáo được tải trước liên kết với mã tải trước khỏi bộ nhớ đệm.

Ví dụ sau đây cho thấy cách ngừng tải trước quảng cáo:

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

Không bắt buộc: Đọc thông tin phản hồi

Đọc thông tin phản hồi của quảng cáo được tải trước tiếp theo mà không cần xoá quảng cáo khỏi bộ nhớ đệm. Nếu bạn cần kiểm tra siêu dữ liệu quảng cáo trước khi hiển thị quảng cáo, hãy đọc thông tin phản hồi thay vì gọi phương thức pollAd.

Ví dụ sau đây cho thấy cách đọc thông tin phản hồi của quảng cáo được tải trước tiếp theo:

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