إعداد الإعلانات البينية

"الإعلانات البينية" هي إعلانات بملء الشاشة تظهر في نقاط الانتقال في تطبيقك، مثلاً بين الشاشات أو في الوقت الفاصل بين مستويَين في لعبة. ويمكن للمستخدمين النقر على الإعلان للانتقال إلى الوجهة، أو إغلاق الإعلان والعودة إلى التطبيق. لمزيد من التفاصيل، يُرجى الاطّلاع على إرشادات الإعلانات البينية ودراسة حالة.

لإزالة وقت الاستجابة في العرض وضمان توفّر الإعلان عند حدوث انتقال، تستخدم "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);
}

بعد أن يغلق المستخدم الإعلان أو يتعذّر عرض الإعلان، يمكنك إتلاف مثيلات الإعلانات الفردية التي تم استطلاعها. لمزيد من التفاصيل، يُرجى الاطّلاع على استطلاع الإعلان وعرضه.

عرض المثال الكامل

يبدأ المكوّن في المثال التالي التحميل المُسبق عند التثبيت، ويتتبّع عدد الإعلانات المتاحة، ويوفّر عناصر تحكّم لعرض "الإعلانات البينية" التي تم تحميلها مسبقًا:

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 برقم تعريف أداة التحميل المُسبَق.

الخطوات التالية

بعد دمج "الإعلانات البينية"، اطّلِع على المواضيع التالية: