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

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

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

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

پیش‌نیازها

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

Android 

ca-app-pub-3940256099942544/1033173712

iOS 

ca-app-pub-3940256099942544/4411468910

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

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

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

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

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

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

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

export function startPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  try {
    const started = InterstitialAdPreloader.start(
      preloadId,
      {
        request: {adUnitId},
        bufferSize: 2,
      },
      {
        // Called when an ad is preloaded into the buffer.
        onAdPreloaded: (metadata) => {
          console.log(`Interstitial ad preloaded for ${metadata.preloadId}`);
          customPreloadCallback?.onAdPreloaded?.(metadata);
        },
        // Called when an ad fails to preload.
        onAdFailedToPreload: (error: LoadAdError) => {
          console.error('Failed to preload interstitial ad:', error.message);
          customPreloadCallback?.onAdFailedToPreload?.(error);
        },
        // Called when all preloaded ads in the buffer have been shown.
        onAdsExhausted: () => {
          console.log('Preload buffer exhausted for interstitial ads.');
          customPreloadCallback?.onAdsExhausted?.();
        },
      },
    );
    return started;
  } catch (error) {
    console.error('Error starting interstitial ad preloader:', error);
    return false;
  }
}

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

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

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

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

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

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

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

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

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

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

export function showPreloadedAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (InterstitialAdPreloader.isAdAvailable(preloadId)) {
    const ad = InterstitialAdPreloader.pollAd(preloadId);
    if (ad) {
      ad.adEventCallback = {
        // Called when the ad is presented on screen.
        onAdShowedFullScreenContent: () => {
          console.log('Preloaded interstitial ad showed full screen content.');
          customAdEventCallback?.onAdShowedFullScreenContent?.();
        },
        // Called when the ad is closed by the user.
        onAdDismissedFullScreenContent: () => {
          console.log('Preloaded interstitial ad dismissed.');
          customAdEventCallback?.onAdDismissedFullScreenContent?.();
          ad.destroy();
        },
        // Called when presentation fails.
        onAdFailedToShowFullScreenContent: (error) => {
          console.error('Preloaded interstitial ad failed to show:', error);
          customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
          ad.destroy();
        },
        // Called when an impression is recorded.
        onAdImpression: () => {
          console.log('Preloaded interstitial ad recorded an impression.');
          customAdEventCallback?.onAdImpression?.();
        },
        // Called when the user taps the ad.
        onAdClicked: () => {
          console.log('Preloaded interstitial ad was clicked.');
          customAdEventCallback?.onAdClicked?.();
        },
        // Called when the ad is estimated to have earned money.
        onAdPaid: (adValue) => {
          console.log(
            `Preloaded interstitial ad paid: ${adValue.amountMicros}` +
              ` ${adValue.currencyCode}`,
          );
          customAdEventCallback?.onAdPaid?.(adValue);
        },
      };
      ad.show();
    }
  } else {
    console.log('No preloaded interstitial ad available in buffer.');
  }
}

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

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

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

export function peekPreloadedAdResponseInfo(preloadId: string) {
  if (InterstitialAdPreloader.isAdAvailable(preloadId)) {
    const responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
    if (responseInfo) {
      console.log('Next preloaded ad response info:', responseInfo);
    }
  }
}

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

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

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

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

export function destroyPreloader(preloadId: string) {
  InterstitialAdPreloader.destroy(preloadId);
}

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

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

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

export function InterstitialScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Initializing Preloader...');

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

  useEffect(() => {
    // Start preloading interstitial ads on component mount
    startPreloader(INTERSTITIAL_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('Ad preloaded and ready!');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Preload failed: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted.');
      },
    });
    setStatus('Preloader started.');

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

  const handleShow = () => {
    showPreloadedAd(PRELOAD_ID, {
      onAdDismissedFullScreenContent: () => {
        setStatus('Ad dismissed.');
      },
      onAdFailedToShowFullScreenContent: (error) => {
        setStatus(`Failed to show ad: ${error.message}`);
      },
    });
    setStatus('Showing preloaded ad...');
    refreshAdCount();
  };

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

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

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

مراحل بعدی

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