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

Chọn nền tảng: Android iOS Unity Flutter React Native Android (Cũ)

Quảng cáo có tặng thưởng cung cấp cho người dùng các mặt hàng trong ứng dụng khi họ tương tác với quảng cáo dạng video, quảng cáo có thể chơi và bản khảo sát. Để biết thông tin chi tiết, hãy xem bài viết Tổng quan về đơn vị quảng cáo có tặng thưởng.

Để loại bỏ độ trễ khi hiển thị và đảm bảo quảng cáo có sẵn khi người dùng nhận được phần thưởng, Google Mobile Ads SDK for React Native sử dụng tính năng tải trước quảng cáo để quản lý việc tải trong nền, lưu vào bộ nhớ đệm và bổ sung vùng đệm.

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 gốc React Native.

Điều kiện tiên quyết

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

• Thiết lập Google Mobile Ads SDK for React Native.
• Bật quảng cáo thử nghiệm và sử dụng đơn vị quảng cáo thử nghiệm sau:

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

Tìm hiểu về tính năng tải trước quảng cáo

Tính năng tải trước quảng cáo trong Google Mobile Ads SDK for React Native tự động hoá việc tải quảng cáo và lưu vào bộ nhớ đệm.

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

• Quản lý tệp đối chiếu: duy trì tệp đối chiếu cho đến khi quảng cáo xuất hiện.
• 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.
• Lần thử lại được quản lý: tải một quảng cáo mới khi không tải được quảng cáo.
• Xử lý thời 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.

Để tải quảng cáo theo cách thủ công, hãy xem phần Tải một quảng cáo có tặng thưởng.

Bắt đầu tải trước

Để bắt đầu tải trước quảng cáo, hãy gọi phương thức RewardedAdPreloader.start rồi truyền giá trị preloadId, chế độ cài đặt cấu hình và lệnh gọi lại sự kiện để theo dõi các thay đổi về trạng thái vùng đệm:

export function startRewardedAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = RewardedAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`Rewarded ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload rewarded ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('Rewarded ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

Mã tải trước là một chuỗi giúp xác định riêng biệt một cấu hình tải trước quảng cáo. Nếu sử dụng mã đơn vị quảng cáo cho một cấu hình tải trước duy nhất trong ứng dụng, bạn có thể sử dụng mã đơn vị quảng cáo đó làm mã tải trước. Nếu ứng dụng của bạn yêu cầu nhiều trình tải trước cho cùng một mã đơn vị quảng cáo, hãy truyền các chuỗi riêng biệt cho mỗi mã tải trước.

Khi ứng dụng của bạn thăm dò một quảng cáo được tải trước từ vùng đệm, Google Mobile Ads SDK for React Native sẽ yêu cầu một quảng cáo thay thế ở chế độ nền để lấp đầy vùng đệm. Nếu không còn quảng cáo được tải trước nào trong vùng đệm, thì Google Mobile Ads SDK for React Native sẽ gọi onAdsExhausted.

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

Google Mobile Ads SDK for React Native thực thi 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ả đơn vị quảng cáo và mã tải trước:

• Giới hạn mặc định: Google lưu giữ tối đa 6 quảng cáo được tải trước trong bộ nhớ. Giới hạn này được áp dụng cho tất cả định dạng và mã tải trước.
• Dung lượng bộ nhớ đệm được đề xuất: Hai cho mỗi mã tải trước.

Nếu ứng dụng của bạn đạt đến giới hạn trên toàn ứng dụng, thì các yêu cầu trong nền cho quảng cáo được tải trước sẽ tạm dừng cho đến khi các quảng cáo hiện có được thăm dò ý kiến từ bộ nhớ đệm hoặc bị huỷ. Quá trình tải trước cũng tạm dừng trong khi quảng cáo toàn màn hình đang hiển thị trên màn hình.

Thăm dò ý kiến và hiển thị quảng cáo

Trước khi hiển thị quảng cáo, hãy xác minh rằng quảng cáo có sẵn bằng cách gọi phương thức RewardedAdPreloader.isAdAvailable. Để truy xuất quảng cáo, hãy gọi phương thức RewardedAdPreloader.pollAd.

Để theo dõi các sự kiện trình bày, chẳng hạn như việc đóng quảng cáo hoặc lỗi hiển thị, hãy đặt thuộc tính adEventCallback trên thực thể quảng cáo trước khi gọi phương thức show:

Ví dụ sau đây kiểm tra xem quảng cáo có sẵn hay không và theo dõi các sự kiện trình bày trước khi hiển thị quảng cáo:

export function showPreloadedRewardedAd(
  preloadId: string,
  onRewardEarned: (reward: Reward) => void,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!RewardedAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded rewarded ad available right now.');
    return;
  }

  const ad = RewardedAdPreloader.pollAd(preloadId);
  if (!ad) {
    return;
  }

  ad.adEventCallback = {
    // Called when the ad is presented on screen.
    onAdShowedFullScreenContent: () => {
      console.log('Preloaded rewarded ad showed full screen content.');
      customAdEventCallback?.onAdShowedFullScreenContent?.();
    },
    // Called when the ad is closed by the user.
    onAdDismissedFullScreenContent: () => {
      console.log('Preloaded rewarded ad dismissed full screen content.');
      customAdEventCallback?.onAdDismissedFullScreenContent?.();
      ad.destroy();
    },
    // Called when presentation fails.
    onAdFailedToShowFullScreenContent: (error) => {
      console.error('Failed to show preloaded rewarded ad:', error);
      customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
      ad.destroy();
    },
    // Called when an impression is recorded.
    onAdImpression: () => {
      console.log('Preloaded rewarded ad recorded an impression.');
      customAdEventCallback?.onAdImpression?.();
    },
    // Called when the user taps the ad.
    onAdClicked: () => {
      console.log('Preloaded rewarded ad was clicked.');
      customAdEventCallback?.onAdClicked?.();
    },
    // Called when the ad is estimated to have earned money.
    onAdPaid: (adValue) => {
      console.log(
        `Preloaded rewarded ad paid: ${adValue.amountMicros}` +
          ` ${adValue.currencyCode}`,
      );
      customAdEventCallback?.onAdPaid?.(adValue);
    },
  };

  ad.show(onRewardEarned);
}

Để giải phóng bộ nhớ và tài nguyên, hãy gọi phương thức ad.destroy trong lệnh gọi lại onAdDismissedFullScreenContent và onAdFailedToShowFullScreenContent.

Đọc thông tin phản hồi

Để kiểm tra thông tin phản hồi cho quảng cáo được tải trước tiếp theo mà không xoá quảng cáo khỏi bộ nhớ đệm, hãy gọi phương thức RewardedAdPreloader.peekAdResponseInfo:

export function peekRewardedAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded rewarded ad response info:', responseInfo);
  }
  return responseInfo;
}

Nếu có quảng cáo, phương thức peekAdResponseInfo sẽ trả về một đối tượng ResponseInfo chứa thông tin về nguồn quảng cáo đã tải và bộ chuyển đổi mạng.

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ủ

Nếu ứng dụng của bạn yêu cầu các tham số xác minh tuỳ chỉnh (chẳng hạn như mã nhận dạng người dùng hoặc siêu dữ liệu phần thưởng tuỳ chỉnh) 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 thuộc tính serverSideVerificationOptions trên thực thể quảng cáo được thăm dò trước khi gọi show.

Các giá trị bạn đặt sẽ được truyền đến tham số truy vấn gọi lại SSV:

• userId: Chuyển đến tham số truy vấn user_id để xác định người dùng.
• customData: Chuyển đến tham số truy vấn custom_data để chuyển tiếp siêu dữ liệu tuỳ chỉnh.

Ví dụ sau đây đặt ServerSideVerificationOptions (customData và userId) cho một đối tượng quảng cáo có tặng thưởng trước khi hiển thị quảng cáo:

export function setServerSideVerificationRewarded(ad: RewardedAd) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

Lưu ý quan trọng: Giá trị tham số truy vấn custom_data là phần trăm thoát hoặc được mã hoá URL. Khi xử lý lệnh gọi lại SSV trên máy chủ, hãy giải mã URL của chuỗi này trước khi xử lý.

Dọn dẹp tài nguyên

Nếu bạn không cần hiển thị quảng cáo cho một mã tải trước cụ thể trong phần còn lại của phiên, hãy gọi phương thức RewardedAdPreloader.destroy. Quá trình này sẽ dừng tải trước cho mã tải trước đó và giải phóng quảng cáo tải trước không dùng đến khỏi bộ nhớ.

Ví dụ sau đây sẽ dừng tải trước:

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

Sau khi người dùng đóng quảng cáo hoặc quảng cáo không hiển thị, hãy huỷ các thực thể quảng cáo được thăm dò riêng lẻ. Để biết thông tin chi tiết, hãy xem phần Thăm dò ý kiến và hiển thị quảng cáo.

Xem ví dụ đầy đủ

Thành phần mẫu sau đây bắt đầu tải trước khi gắn, theo dõi số lượng quảng cáo có sẵn và cung cấp các chế độ kiểm soát để hiển thị quảng cáo có tặng thưởng được tải trước:

export function RewardedScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Preloader idle.');
  const [reward, setReward] = useState<string | null>(null);

  const refreshAdCount = () => {
    const count = RewardedAdPreloader.getNumAdsAvailable(PRELOAD_ID);
    setNumAdsAvailable(count);
  };

  useEffect(() => {
    // Start preloading ads on component mount
    const started = startRewardedAdPreloader(REWARDED_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('Rewarded ad preloaded into buffer.');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Failed to preload rewarded ad: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted for rewarded ads.');
      },
    });
    if (started) {
      setStatus('Preloader started.');
    }

    // Clean up preloader resources on component unmount
    return () => {
      destroyRewardedAdPreloader(PRELOAD_ID);
    };
  }, []);

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedAd(
      PRELOAD_ID,
      (userReward) => {
        setReward(`${userReward.amount} ${userReward.type}`);
      },
      {
        onAdDismissedFullScreenContent: () => {
          setStatus('Ad dismissed.');
        },
        onAdFailedToShowFullScreenContent: (error) => {
          setStatus(`Failed to show preloaded ad: ${error.message}`);
        },
      },
    );
    refreshAdCount();
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Preload Rewarded Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      {reward && <Text style={styles.rewardText}>Earned: {reward}</Text>}
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Thay thế nội dung sau:

• REWARDED_AD_UNIT_ID bằng mã đơn vị quảng cáo của bạn.
• PRELOAD_ID bằng mã trình tải trước của bạn.

Các bước tiếp theo

Sau khi tích hợp quảng cáo có tặng thưởng, hãy khám phá các chủ đề sau:

• Doanh thu từ quảng cáo ở cấp lượt hiển thị
• Quyền riêng tư và sự đồng ý của người dùng