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

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

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

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

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

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

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

تحميل إعلان

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

يحمّل المثال التالي "إعلان على شاشة فتح التطبيق" في حال نجاح العملية ويسجّل خطأ في حال فشلها:

export async function loadAppOpenAd(
  adUnitId: string,
): Promise<AppOpenAd | null> {
  try {
    const ad = await AppOpenAd.load({adUnitId});
    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load app open ad:', loadError.message);
    return null;
  }
}

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

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

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

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

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

عرض الإعلان

لعرض "إعلان على شاشة فتح التطبيق"، استخدِم طريقة show:

export function showAppOpenAd(ad: AppOpenAd) {
  ad.show();
}

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

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

ينشئ المثال التالي مثيلاً من SingleLoadAppOpenAdManager يحمّل إعلانًا ويستمع إلى أحداث الإعلانات ويتحقّق من توفّر الإعلانات:

export class SingleLoadAppOpenAdManager {
  private ad: AppOpenAd | null = null;
  private loadTime = 0;
  private isShowingAd = false;

  async loadAd(adUnitId: string) {
    // Avoid re-loading if an ad is already loaded or showing.
    if (this.ad) {
      return;
    }
    try {
      this.ad = await AppOpenAd.load({adUnitId});
      this.loadTime = Date.now();
      this.ad.adEventCallback = {
        onAdDismissedFullScreenContent: () => {
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          // Preload the next ad for future foreground transitions.
          this.loadAd(adUnitId);
        },
        onAdFailedToShowFullScreenContent: () => {
          // An ad object that fails to present is consumed and cannot be reused.
          // Clean up native resources and preload a new ad for future events.
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          this.loadAd(adUnitId);
        },
      };
    } catch (error) {
      console.error('Failed to load app open ad:', error);
    }
  }

  showAdIfAvailable() {
    if (!this.ad || !this.isAdAvailable()) {
      console.warn(
        'App open ad cannot be shown: ad is not loaded or has expired.',
      );
      return;
    }
    if (this.isShowingAd) {
      console.warn('App open ad cannot be shown: an ad is already displaying.');
      return;
    }

    this.ad.show();
    this.isShowingAd = true;
  }

  isAdAvailable(): boolean {
    // App Open ads expire after 4 hours per Google Mobile Ads policy.
    const FOUR_HOURS_IN_MS = 4 * 60 * 60 * 1000;
    return this.ad !== null && Date.now() - this.loadTime < FOUR_HOURS_IN_MS;
  }
}

يساعدك حساب المدير على مستوى التطبيق في إجراء ما يلي:

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

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

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

  1. تسجيل أداة معالجة الحدث AppState للحدث 'change'
  2. عندما تنتقل الحالة إلى 'active'، يمكنك استدعاء الطريقة showAdIfAvailable في مثيل مدير الإعلانات.

يستمع المثال التالي إلى أحداث فتح التطبيق ويعرض إعلانًا إذا كان متاحًا:

export function setupAppOpenAdForegroundListener(adManager: {
  showAdIfAvailable: () => void;
}): NativeEventSubscription {
  return AppState.addEventListener('change', (nextAppState: AppStateStatus) => {
    if (nextAppState === 'active') {
      adManager.showAdIfAvailable();
    }
  });
}

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

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

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

إعداد شاشة اختبار

لاختبار الإعلانات بشكل تفاعلي أو عرضها على شاشة معيّنة، يمكنك إدارة مثيل الإعلان في حالة المكوّن.

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

export function AppOpenSingleLoadScreen() {
  const [ad, setAd] = useState<AppOpenAd | null>(null);
  const [isLoaded, setIsLoaded] = useState(false);
  const [status, setStatus] = useState<string>('Idle');

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

  const handleLoad = async () => {
    setStatus('Loading App Open ad...');
    const loadedAd = await loadAppOpenAd(APP_OPEN_AD_UNIT_ID);
    if (loadedAd) {
      registerAdEvents(loadedAd);
      const onDismiss =
        loadedAd.adEventCallback?.onAdDismissedFullScreenContent;
      loadedAd.adEventCallback = {
        ...loadedAd.adEventCallback,
        onAdDismissedFullScreenContent: () => {
          onDismiss?.();
          setStatus('Ad dismissed.');
        },
      };
      setAd((prevAd) => {
        prevAd?.destroy();
        return loadedAd;
      });
      setIsLoaded(true);
      setStatus('App Open ad loaded!');
    } else {
      setStatus('Failed to load App Open ad.');
    }
  };

  const handleShow = () => {
    if (ad) {
      showAppOpenAd(ad);
      setIsLoaded(false);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>App Open Ad</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <View style={styles.buttonGroup}>
        <Button title="Load Ad" onPress={handleLoad} />
        <View style={styles.spacerSmall} />
        <Button title="Show Ad" onPress={handleShow} disabled={!isLoaded} />
      </View>
    </View>
  );
}

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

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