راه‌اندازی آگهی‌های پاداش‌دار

آگهی‌های پاداش‌دار به کاربران شما محصولات درون‌برنامه می‌دهند تا با آگهی‌های ویدیویی، آگهی‌های قابل‌بازی، و نظرسنجی‌ها تعامل کنند. برای جزئیات، نمای کلی واحدهای آگهی پاداش‌دار را ببینید.

برای حذف تأخیر ارائه و اطمینان از دردسترس بودن آگهی هنگام دریافت پاداش توسط کاربر، Google Mobile Ads SDK for React Native از پیش‌بارگیری آگهی برای مدیریت بارگیری پس‌زمینه، ذخیره‌سازی در حافظه نهان، و پر کردن مجدد میان‌گیر استفاده می‌کند.

این راهنما به شما نشان می‌دهد که چگونه آگهی‌های پاداش‌دار را در برنامه React Native ادغام کنید.

پیش‌نیازها

پیش‌از ادامه دادن، کارهای زیر را انجام دهید:

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

آشنایی با پیش‌بارگذاری آگهی

پیش‌بار کردن آگهی در Google Mobile Ads SDK for React Native بار کردن و ذخیره آگهی در حافظه نهان را خودکار می‌کند.

پیش‌بارگیری آگهی مزایای زیر را ارائه می‌دهد:

  • مدیریت مرجع: مرجع‌ها را تا زمانی که آگهی‌ها نشان داده شوند حفظ می‌کند.
  • بار کردن مجدد خودکار: وقتی آگهی‌ای از حافظه نهان بازیابی می‌شود، آگهی جدیدی بار می‌کند.
  • تلاش‌های مجدد مدیریت‌شده: وقتی آگهی بار نمی‌شود، آگهی جدیدی بار می‌کند.
  • مدیریت انقضا: آگهی‌ها را قبل‌از منقضی شدن بازآوری می‌کند.
  • بهینه‌سازی حافظه نهان: ترتیب حافظه نهان را برای ارائه آگهی با بالاترین اولویت بهینه‌سازی می‌کند.

برای بار کردن دستی آگهی‌ها، به بار کردن یک آگهی پاداش‌دار مراجعه کنید.

شروع پیش‌بارگیری

برای شروع پیش‌بارگیری آگهی‌ها، روش RewardedAdPreloader.start را فراخوانی کنید و مقدار preloadId، تنظیمات پیکربندی، و فراخوان‌های برگشتی رویداد را برای نظارت بر تغییرات وضعیت میان‌گیر ارسال کنید:

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

شناسه پیش‌بارگیری رشته‌ای است که پیکربندی پیش‌بارگیری آگهی را به‌طور یکتا شناسایی می‌کند. اگر از شناسه واحد آگهی برای یک پیکربندی پیش‌بارگیری در برنامه‌تان استفاده می‌کنید، می‌توانید از آن شناسه واحد آگهی به‌عنوان شناسه پیش‌بارگیری استفاده کنید. اگر برنامه‌تان به چند پیش‌بارگذار برای یک شناسه واحد آگهی نیاز دارد، رشته‌های متمایزی برای هر شناسه پیش‌بارگذاری ارسال کنید.

وقتی برنامه‌تان آگهی پیش‌بارشده‌ای را از میان‌گیر نظرسنجی می‌کند، Google Mobile Ads SDK for React Native درخواست آگهی جایگزین در پس‌زمینه می‌کند تا میان‌گیر را دوباره پر کند. اگر هیچ آگهی پیش‌بارشده‌ای در میان‌گیر باقی نمانده باشد، Google Mobile Ads SDK for React Native onAdsExhausted را فراخوانی می‌کند.

حدود حافظه نهان پیش‌بارکردن

Google Mobile Ads SDK for React Native محدودیتی را در سطح برنامه بر تعداد کل آگهی‌های پیش‌بارشده در همه واحدهای آگهی و شناسه‌های پیش‌بار اعمال می‌کند:

  • محدودیت پیش‌فرض: Google حداکثر شش آگهی پیش‌بارشده را در حافظه نگه می‌دارد. این محدودیت برای همه قالب‌ها و شناسه‌های پیش‌بارگذاری مشترک است.
  • اندازه میان‌گیر توصیه‌شده: دو برای هر شناسه پیش‌بارگیری.

اگر برنامه شما به حد مجاز سراسری برنامه برسد، درخواست‌های پس‌زمینه برای آگهی‌های پیش‌بارشده تا زمانی که آگهی‌های موجود از حافظه نهان نظرسنجی شوند یا ازبین بروند، متوقف می‌شوند. پیش‌بارگیری همچنین زمانی‌که آگهی تمام‌صفحه به‌طور فعال در صفحه نمایش داده می‌شود، موقتاً متوقف می‌شود.

نظرسنجی و نمایش آگهی

پیش‌از نمایش آگهی، با فراخوانی روش RewardedAdPreloader.isAdAvailable درستی‌سنجی کنید که آگهی دردسترس باشد. برای بازیابی آگهی، روش RewardedAdPreloader.pollAd را فراخوانی کنید.

برای گوش دادن به رویدادهای ارائه، مانند رد کردن آگهی یا خطاهای نمایش، ویژگی adEventCallback را در نمونه آگهی قبل‌از فراخوانی روش show تنظیم کنید:

مثال زیر دردسترس بودن آگهی را بررسی می‌کند و قبل‌از نمایش آگهی، رویدادهای ارائه را گوش می‌دهد:

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

برای آزاد کردن حافظه و منابع، روش ad.destroy را در بازخوان‌های onAdDismissedFullScreenContent و onAdFailedToShowFullScreenContent فراخوانی کنید.

خواندن اطلاعات پاسخ

برای بررسی اطلاعات پاسخ برای آگهی پیش‌بارشده بعدی بدون برداشتن آگهی از حافظه نهان، 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;
}

اگر آگهی دردسترس باشد، روش peekAdResponseInfo یک شیء ResponseInfo برمی‌گرداند که حاوی اطلاعاتی درباره منبع آگهی بارشده و آداپتورهای شبکه است.

اختیاری: اعتبارسنجی تماس‌های برگشتی درستی‌سنجی سمت سرور

اگر برنامه‌تان به پارامترهای درستی‌سنجی سفارشی، مثل شناسه کاربر یا فراداده پاداش سفارشی، در بازخوان‌های درستی‌سنجی سمت سرور (SSV) نیاز دارد، ویژگی serverSideVerificationOptions را در نمونه آگهی نظرسنجی‌شده قبل‌از فراخوانی show تنظیم کنید.

مقادیری که تنظیم می‌کنید به پارامترهای پُرسمان بازخوانی SSV ارسال می‌شوند:

  • userId: به پارامتر پُرسمان user_id منتقل می‌شود تا کاربر را شناسایی کند.
  • customData: به پارامتر پُرسمان custom_data منتقل می‌شود تا فراداده سفارشی را بازارسال کند.

مثال زیر ServerSideVerificationOptions (customData و userId) را در شیء آگهی پاداش‌دار قبل‌از نمایش آگهی تنظیم می‌کند:

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

پاک‌سازی منابع

اگر دیگر نیازی به نمایش آگهی برای شناسه پیش‌بارگیری خاصی برای بقیه جلسه ندارید، روش RewardedAdPreloader.destroy را فراخوانی کنید. این فرایند پیش‌بارگیری را برای آن شناسه پیش‌بارگیری متوقف می‌کند و آگهی‌های پیش‌بارگیری‌شده استفاده‌نشده را از حافظه آزاد می‌کند.

مثال زیر پیش‌بارگذاری را متوقف می‌کند:

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

پس‌از اینکه کاربر آگهی را رد کرد یا آگهی نشان داده نشد، نمونه‌های آگهی نظرسنجی‌شده را به‌صورت جداگانه ازبین ببرید. برای جزئیات، به نظرسنجی و نمایش آگهی مراجعه کنید.

مشاهده مثال کامل

نمونه مؤلفه زیر پیش‌بارگیری را در نصب شروع می‌کند، تعداد آگهی‌های دردسترس را ردیابی می‌کند، و کنترل‌هایی برای نمایش آگهی‌های پاداش‌دار پیش‌بارگیری‌شده ارائه می‌دهد:

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

موارد زیر را جایگزین کنید:

  • REWARDED_AD_UNIT_ID را با شناسه واحد آگهی‌تان جایگزین کنید.
  • PRELOAD_ID با شناسه پیش‌بارگذار شما.

مراحل بعدی

پس‌از ادغام آگهی‌های پاداش‌دار، موضوعات زیر را کاوش کنید: