إعداد إعلانات البانر

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

توضّح هذه الصفحة كيفية دمج إعلانات البانر التكيُّفية الثابتة في تطبيق React Native.

المتطلبات الأساسية

قبل المتابعة، عليك تنفيذ ما يلي:

Android 

ca-app-pub-3940256099942544/9214589741

iOS 

ca-app-pub-3940256099942544/2435281174

الحصول على حجم الإعلان

لطلب "إعلان بانر تكيُّفي ثابت"، استخدِم طريقة AdSize.getLargeAnchoredAdaptiveBannerAdSize مع عرض حاوية الإعلان المتاحة بوحدات بكسل مستقلة الكثافة (dp). تعرض هذه الطريقة وعدًا يتم حله إلى عنصر AdSize.

يحصل المثال التالي على حجم "إعلان بانر تكيُّفي ثابت" ويعرضه:

export async function getAdaptiveAdSize(width: number): Promise<AdSize> {
  const adSize = await AdSize.getLargeAnchoredAdaptiveBannerAdSize(width);
  return adSize;
}

تحميل إعلان

بعد الحصول على عنصر AdSize، يمكنك استدعاء طريقة load في فئة BannerAd باستخدام معرّف الوحدة الإعلانية وحجم الإعلان.

يحمّل المثال التالي "إعلان بانر تكيُّفي ثابت" بحجم الإعلان ومعرّف الوحدة الإعلانية، ويتلقّى مثيل BannerAd الذي تم تحميله في حال النجاح، ويسجّل خطأ في حال الفشل:

export function loadBannerAd(
  adUnitId: string,
  adSize: AdSize,
  callback?: BannerAdLoadCallback,
): void {
  BannerAd.load(
    {adUnitId, adSize},
    {
      // Called when an ad has finished loading.
      onAdLoaded: (ad) => {
        console.log('Banner ad loaded successfully.');
        callback?.onAdLoaded?.(ad);
      },
      // Called when an ad request fails.
      onAdFailedToLoad: (error: LoadAdError) => {
        console.error('Failed to load banner ad:', error.message);
        callback?.onAdFailedToLoad?.(error);
      },
    },
  );
}

إعادة تحميل إعلان

إذا ضبطت وحدتك الإعلانية لإعادة التحميل، لن تحتاج إلى طلب إعلان آخر عند تعذُّر تحميل الإعلان. تلتزم Google Mobile Ads SDK for React Native بأي معدّل إعادة تحميل تحدّده في واجهة مستخدم AdMob. إذا لم تكن قد فعّلت إعادة التحميل، يمكنك إرسال طلب جديد. لمزيد من التفاصيل حول إعادة تحميل الوحدات الإعلانية، مثل ضبط معدّل إعادة التحميل، يُرجى الاطّلاع على مقالة ضبط خيار إعادة التحميل التلقائية لإعلانات البانر.

عرض "إعلان بانر"

لعرض مثيل BannerAd تم تحميله، مرِّر مثيل الإعلان إلى السمة ad لمكوّن BannerAdView في هيكلية طرق العرض.

يعرض المثال التالي إعلانًا ويزيله عند إلغاء تحميل المكوّن:

export function BannerAdViewComponent({ad}: {ad: BannerAd}): React.JSX.Element {
  useEffect(() => {
    // Destroy native resources when the component unmounts.
    return () => {
      ad.destroy();
    };
  }, [ad]);

  return <BannerAdView ad={ad} />;
}

يستدعي هذا المثال الإجراء destroy عند إلغاء تحميل المكوّن أو عند استبدال مثيل الإعلان. تؤدي هذه العملية إلى إخلاء مساحة الذاكرة والموارد التي يستخدمها الإعلان.

الاستماع إلى أحداث الإعلانات

للاستماع إلى أحداث الإعلانات، مثل مرّات ظهور الإعلانات والنقرات، يمكنك ضبط عمليات الاستدعاء على مكوّن BannerAdView. للاطّلاع على جميع عمليات إعادة الاتصال، يُرجى مراجعة BannerAdViewProps.

يضبط المثال التالي عمليات الاستدعاء لرصد أحداث "إعلانات البانر":

export function BannerEventsExample({ad}: {ad: BannerAd}): React.JSX.Element {
  return (
    <BannerAdView
      ad={ad}
      // Called when an impression is recorded for an ad.
      onAdImpression={() => {
        console.log('Banner ad recorded an impression.');
      }}
      // Called when a click is recorded for an ad.
      onAdClicked={() => {
        console.log('Banner ad clicked.');
      }}
      // Called when the ad opens an in-app overlay or landing page.
      onAdShowedFullScreenContent={() => {
        console.log('Banner ad opened overlay content.');
      }}
      // Called when the user dismisses the ad overlay.
      onAdDismissedFullScreenContent={() => {
        console.log('Banner ad overlay dismissed.');
      }}
      // Called when the ad is estimated to have earned money.
      onAdPaid={(adValue) => {
        console.log(
          `Banner ad paid: ${adValue.amountMicros} ${adValue.currencyCode}`,
        );
      }}
      // Called when the ad automatically refreshes.
      onAdRefreshed={() => {
        console.log('Banner ad refreshed.');
      }}
      // Called when the ad fails to automatically refresh.
      onAdFailedToRefresh={(error) => {
        console.error('Banner ad failed to refresh:', error.message);
      }}
    />
  );
}

يستمع هذا المثال إلى أحداث الإعلانات، مثل إغلاق الإعلانات ومرات الظهور والنقرات والعرض بملء الشاشة وإيرادات الإعلانات المقدَّرة وعمليات إعادة التحميل الناجحة وغير الناجحة.

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

يتناول هذا القسم المثال الكامل لدمج "إعلان بانر" في مكوّن React Native.

يدمج المثال التالي "إعلان بانر" في مكوّن React Native ويدير مثيل الإعلان في الحالة:

export function BannerScreen() {
  const {width} = useWindowDimensions();
  const insets = useSafeAreaInsets();
  const [ad, setAd] = useState<BannerAd | null>(null);
  const [status, setStatus] = useState('Idle');

  useEffect(() => {
    return () => {
      ad?.destroy();
    };
  }, [ad]);

  const handleLoadAd = async () => {
    setStatus('Loading adaptive banner ad...');
    try {
      const adaptiveSize = await getAdaptiveAdSize(width);
      loadBannerAd(BANNER_AD_UNIT_ID, adaptiveSize, {
        onAdLoaded: (loadedAd) => {
          setAd(loadedAd);
          setStatus('Banner ad loaded successfully.');
        },
        onAdFailedToLoad: (error: LoadAdError) => {
          setStatus(`Failed to load banner ad: ${error.message}`);
        },
      });
    } catch (error) {
      setStatus(`Failed to get adaptive ad size: ${error}`);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Anchored Adaptive Banner Ad</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <View style={styles.buttonGroup}>
        <Button title="Load Banner Ad" onPress={handleLoadAd} />
      </View>
      {ad ? (
        <View style={[styles.bannerContainer, {bottom: insets.bottom}]}>
          <BannerAdView
            ad={ad}
            onAdImpression={() => setStatus('Banner ad recorded impression.')}
            onAdClicked={() => setStatus('Banner ad clicked.')}
            onAdShowedFullScreenContent={() =>
              setStatus('Banner ad showed overlay content.')
            }
            onAdDismissedFullScreenContent={() =>
              setStatus('Banner ad overlay dismissed.')
            }
          />
        </View>
      ) : null}
    </View>
  );
}

استبدِل BANNER_AD_UNIT_ID بمعرّف وحدتك الإعلانية.

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

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