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

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

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

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

پیش‌نیازها

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

Android 

ca-app-pub-3940256099942544/5354046379

iOS 

ca-app-pub-3940256099942544/6978759866

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

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

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

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

برای بار کردن دستی آگهی‌ها، بار کردن یک آگهی تمام‌صفحه پاداش‌دار را ببینید.

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

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

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

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

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

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

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

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

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

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

قبل‌از نمایش آگهی، با فراخوانی روش RewardedInterstitialAdPreloader.isAdAvailable بررسی کنید که آگهی دردسترس باشد. برای بازیابی آگهی، روش RewardedInterstitialAdPreloader.pollAd را فراخوانی کنید.

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

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

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

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

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

  ad.show(onRewardEarned);
}

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

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

برای بررسی اطلاعات پاسخ برای آگهی پیش‌بارشده بعدی بدون برداشتن آگهی از حافظه نهان، RewardedInterstitialAdPreloader.peekAdResponseInfo روش را فراخوانی کنید:

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

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

اختیاری: اعتبارسنجی بازخوانی‌های SSV

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

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

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

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

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

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

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

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

export function destroyRewardedInterstitialAdPreloader(preloadId: string) {
  RewardedInterstitialAdPreloader.destroy(preloadId);
}

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

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

این بخش پیاده‌سازی کامل پیش‌بارگیری آگهی را پوشش می‌دهد.

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

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedInterstitialAd(
      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 Interstitial 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>
  );
}

مراحل بعدی

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