إعداد "الإعلانات على شاشة فتح التطبيق"

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

يشرح هذا الدليل كيفية دمج "الإعلانات على شاشة فتح التطبيق" في تطبيق React Native.

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

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

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

فهم التحميل المسبَق للإعلانات

تؤدي ميزة "التحميل المسبَق للإعلان" في Google Mobile Ads SDK for React Native إلى تحميل الإعلانات وتخزينها مؤقتًا بشكل تلقائي.

يوفّر التحميل المسبَق للإعلانات المزايا التالية:

  • إدارة المراجع: تحتفظ بالمراجع إلى أن يتم عرض الإعلانات.
  • إعادة التحميل التلقائي: يتم تحميل إعلان جديد عند استرداد إعلان من ذاكرة التخزين المؤقت.
  • عمليات إعادة المحاولة المُدارة: يتم تحميل إعلان جديد عندما يتعذّر تحميل إعلان.
  • التعامل مع انتهاء الصلاحية: يتم إعادة تحميل الإعلانات قبل انتهاء صلاحيتها.
  • تحسين ذاكرة التخزين المؤقت: يحسّن ترتيب ذاكرة التخزين المؤقت لعرض الإعلان ذي الأولوية القصوى.

لتحميل الإعلانات يدويًا، يُرجى الاطّلاع على دليل تحميل إعلان واحد على شاشة فتح التطبيق.

بدء التحميل المُسبَق

لبدء تحميل الإعلانات مسبقًا، استخدِم طريقة AppOpenAdPreloader.start وأدخِل قيمة preloadId وإعدادات الضبط وعمليات معاودة الاتصال بالأحداث لمراقبة تغييرات حالة التخزين المؤقت:

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

‫preloadId هو سلسلة تحدّد بشكل فريد إعدادات التحميل المسبق للإعلانات. إذا تم استخدام adUnitId لإعداد تحميل مسبق واحد فقط في تطبيقك، يمكنك استخدام معرّف الوحدة الإعلانية هذا كمعرّف التحميل المسبق. إذا كان تطبيقك يتطلّب عدة أدوات تحميل مسبق لرقم تعريف الوحدة الإعلانية نفسه، عليك تمرير سلاسل مختلفة لكل رقم تعريف تحميل مسبق.

عندما يستطلع تطبيقك إعلانًا تم تحميله مسبقًا من المخزن المؤقت، يطلب Google Mobile Ads SDK for React Native إعلانًا بديلاً في الخلفية لإعادة ملء المخزن المؤقت. في حال عدم توفّر إعلانات محمَّلة مسبقًا في المخزن المؤقت، يستدعي Google Mobile Ads SDK for React Native دالة الاستدعاء onAdsExhausted.

حدود التحميل المُسبَق لذاكرة التخزين المؤقت

يفرض Google Mobile Ads SDK for React Native حدًا أقصى على مستوى التطبيق لإجمالي عدد الإعلانات التي يتم تحميلها مسبقًا:

  • الحدّ التلقائي: تحتفظ Google بستة إعلانات محمَّلة مسبقًا كحدّ أقصى في الذاكرة.
  • ننصحك بالاحتفاظ بحجم ذاكرة التخزين المؤقت يبلغ اثنين لكل معرّف تحميل مسبق.

إذا بلغ تطبيقك الحدّ الأقصى على مستوى التطبيق، سيتم إيقاف طلبات الخلفية للإعلانات المحمَّلة مسبقًا مؤقتًا إلى أن يتم استطلاع الإعلانات الحالية وعرضها أو إتلافها.

استطلاع الإعلان وعرضه

للتحقّق من الإعلانات المحمَّلة مسبقًا والمتاحة واسترداد نسخة من الإعلان، يمكنك استدعاء الطريقة AppOpenAdPreloader.pollAd.

للاستماع إلى أحداث العرض بملء الشاشة، سجِّل عمليات الاستدعاء في السمة adEventCallback لمثيل AppOpenAd الذي تم عرضه قبل استدعاء طريقة show:

export function showPreloadedAppOpenAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!AppOpenAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded app open ad available right now.');
    return;
  }

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

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

  ad.show();
}

لإخلاء الذاكرة والموارد، يمكنك استدعاء طريقة ad.destroy في عمليات الاستدعاء onAdDismissedFullScreenContent و onAdFailedToShowFullScreenContent عندما يرفض المستخدم إعلانًا أو يتعذّر عرض الإعلان.

قراءة معلومات الردّ

لفحص تفاصيل الإعلان التالي الذي تم تحميله مسبقًا بدون إزالته من ذاكرة التخزين المؤقت، يمكنك استدعاء الطريقة AppOpenAdPreloader.peekAdResponseInfo:

export function peekAppOpenAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded app open ad response info:', responseInfo);
  }
  return responseInfo;
}

إدارة "الإعلانات على شاشة فتح التطبيق" باستخدام مدير على مستوى التطبيق

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

يوفّر استخدام حساب إداري على مستوى التطبيق العديد من المزايا الرئيسية:

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

ينفّذ المثال التالي مديرًا على مستوى التطبيق باستخدام الكائن AppOpenAdPreloader:

export class AppOpenAdManager {
  private adUnitId: string;
  private preloadId: string;
  private appStateSubscription?: NativeEventSubscription;
  private startTimeoutId?: ReturnType<typeof setTimeout>;

  constructor(adUnitId: string, preloadId: string) {
    this.adUnitId = adUnitId;
    this.preloadId = preloadId;
  }

  start(): boolean {
    if (!AppOpenAdPreloader.getConfiguration(this.preloadId)) {
      AppOpenAdPreloader.start(
        this.preloadId,
        {
          request: {adUnitId: this.adUnitId},
          bufferSize: 2,
        },
        {
          onAdPreloaded: (event) => {
            console.log(`App open ad preloaded for ${event.preloadId}`);
          },
          onAdFailedToPreload: (error: LoadAdError) => {
            console.error('Failed to preload app open ad:', error.message);
          },
          onAdsExhausted: () => {
            console.log('App open ad buffer exhausted.');
          },
        },
      );
    }

    if (!this.appStateSubscription && !this.startTimeoutId) {
      // Delay attaching the listener to ensure native dismissal transitions complete
      this.startTimeoutId = setTimeout(() => {
        this.startTimeoutId = undefined;
        if (!this.appStateSubscription) {
          this.appStateSubscription = AppState.addEventListener(
            'change',
            (nextAppState: AppStateStatus) => {
              if (nextAppState === 'active') {
                this.showAdIfAvailable();
              }
            },
          );
        }
      }, APP_STATE_LISTENER_DELAY_MS);
    }

    return true;
  }

  pause(): void {
    if (this.startTimeoutId) {
      clearTimeout(this.startTimeoutId);
      this.startTimeoutId = undefined;
    }
    this.appStateSubscription?.remove();
    this.appStateSubscription = undefined;
  }

  stop(): void {
    this.pause();
    AppOpenAdPreloader.destroy(this.preloadId);
  }

  showAdIfAvailable() {
    if (!AppOpenAdPreloader.isAdAvailable(this.preloadId)) {
      console.log('App open ad is not preloaded or available right now.');
      return;
    }

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

    // Pause listener while presenting the ad
    this.pause();

    ad.adEventCallback = {
      onAdShowedFullScreenContent: () => {
        console.log('Preloaded app open ad showed full screen content.');
      },
      onAdDismissedFullScreenContent: () => {
        console.log('Preloaded app open ad dismissed full screen content.');
        ad.destroy();
        this.start();
      },
      onAdFailedToShowFullScreenContent: (error) => {
        console.error('Failed to show preloaded app open ad:', error);
        ad.destroy();
        this.start();
      },
    };

    ad.show();
  }
}

الاستماع إلى أحداث فتح التطبيق

لعرض الإعلانات عندما يعود تطبيقك إلى المقدّمة، سجِّل مستمعًا من النوع change في الوحدة AppState في المكوّن الجذر لتطبيقك، مثل App.tsx. تحقَّق من وقت انتقال الحالة إلى active. على سبيل المثال، يمكنك استدعاء طريقة start في مثيل مدير الإعلانات في مكوّن App.tsx.

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

  1. أزِل متتبِّع الأحداث AppState قبل عرض إعلان بملء الشاشة.
  2. للتأكّد من استئناف الاستماع سواء أغلق المستخدم الإعلان أو تعذّر عرض الإعلان، أضِف متتبِّع الأحداث AppState مرة أخرى في دالتي الاستدعاء onAdDismissedFullScreenContent وonAdFailedToShowFullScreenContent.

للاطّلاع على مثال مُكتمل على التحكّم في وقت إيقاف متتبِّعات أحداث فتح التطبيق في المقدّمة مؤقتًا واستئنافها، يُرجى الاطّلاع على عملية تنفيذ AppOpenAdManager.

التعرّف على عمليات التشغيل على البارد وشاشات التحميل

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

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

حذف الموارد

عندما لا يعود التحميل المُسبق مطلوبًا لشاشة أو معرّف وحدة إعلانية، مثلاً عند الانتقال من شاشة تحمّل الإعلانات مُسبقًا، يمكنك استدعاء طريقة AppOpenAdPreloader.destroy لإصدار موارد التحميل المُسبق ومنع الاحتفاظ بعناصر الإعلانات غير المستخدَمة في الذاكرة:

export function destroyAppOpenAdPreloader(preloadId: string) {
  AppOpenAdPreloader.destroy(preloadId);
}

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

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

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

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

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

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

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

  const handleShowAd = () => {
    setStatus('Showing preloaded ad...');
    showPreloadedAppOpenAd(PRELOAD_ID, {
      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 App Open 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={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

غيِّر القيم في السلسلة على الشكل التالي:

  • APP_OPEN_AD_UNIT_ID بمعرّف الوحدة الإعلانية.
  • PRELOAD_ID برقم تعريف أداة التحميل المُسبَق.

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

بعد دمج "الإعلانات على شاشة فتح التطبيق"، استكشِف المواضيع التالية: