הגדרת מודעות בפתיחת האפליקציה

מודעות בפתיחת האפליקציה מופיעות כשהמשתמשים פותחים את האפליקציה או חוזרים אליה. המשתמשים יכולים לסגור את המודעות האלה בכל שלב. כדי לייצר הכנסות ממסך הטעינה של האפליקציה, אפשר להשתמש במודעות בפתיחת האפליקציה. פרטים נוספים זמינים במאמר הנחיות ושיטות מומלצות לשימוש במודעות בפתיחת אפליקציה.

במדריך הזה מוסבר איך לשלב מודעות בפתיחת האפליקציה באפליקציית React Native.

דרישות מוקדמות

לפני שממשיכים, צריך לבצע את הפעולות הבאות:

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

הסבר על טעינת מודעה מראש

טעינת מודעות מראש ב-Google Mobile Ads SDK for React Native מאפשרת לטעון מודעות ולשמור אותן במטמון באופן אוטומטי.

היתרונות של טעינת מודעות מראש:

  • ניהול קובצי עזר: שמירה על קובצי העזר עד להצגת המודעות.
  • טעינה מחדש אוטומטית: טעינה של מודעה חדשה כשאחת מהמודעות נשלפת מהמטמון.
  • ניסיונות חוזרים מנוהלים: טעינה של מודעה חדשה אם טעינת המודעה הקודמת נכשלה.
  • טיפול בתפוגה: רענון המודעות לפני שהתוקף שלהן פג.
  • אופטימיזציה של המטמון: אופטימיזציה של סדר המטמון כדי להציג את המודעה בעלת העדיפות הגבוהה ביותר.

כדי לטעון מודעות באופן ידני, אפשר לעיין במדריך טעינה של מודעה אחת בפתיחת האפליקציה.

התחלת הטעינה מראש

כדי להתחיל לטעון מראש מודעות, צריך להפעיל את השיטה AppOpenAdPreloader.start ולהעביר את הערך של preloadId, את הגדרות התצורה ואת פונקציות ה-callback של האירועים כדי לעקוב אחרי שינויים במצב המאגר:

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 מפעיל את פונקציית ה-callback‏ onAdsExhausted.

מגבלות על טעינה מראש למטמון

Google Mobile Ads SDK for React Native אוכפת מגבלה על המספר הכולל של מודעות שנטענות מראש בכל האפליקציה:

  • מגבלת ברירת המחדל: Google שומרת בזיכרון עד שש מודעות שנטענו מראש.
  • מומלץ להגדיר שטח אחסון זמני של שני מזהים לכל מזהה טעינה מראש.

אם האפליקציה מגיעה למגבלה שחלה על כל האפליקציה, בקשות ברקע למודעות שנטענו מראש מושהות עד שהמודעות הקיימות נדגמות ומוצגות או מושמדות.

דגימה והצגה של המודעה

כדי לבדוק אם יש מודעות שנטענו מראש ולקבל מופע של מודעה, מפעילים את ה-method‏ AppOpenAdPreloader.pollAd.

כדי להאזין לאירועי הצגה במסך מלא, צריך לרשום קריאות חוזרות (callbacks) במאפיין 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 בקריאות החוזרות (callbacks) onAdDismissedFullScreenContent ו- onAdFailedToShowFullScreenContent כשהמשתמש סוגר את המודעה או כשהמודעה לא מוצגת.

קוראים את פרטי התשובה

כדי לבדוק את הפרטים של המודעה הבאה שנטענה מראש בלי להסיר אותה מהמטמון, מפעילים את ה-method‏ 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.

לשימוש במנהל ברמת האפליקציה יש כמה יתרונות מרכזיים:

  • שומר על מצב הטעינה מראש ללא תלות בניווט במסך ספציפי ובמחזור החיים של הרכיב.
  • מרכז את הקריאות החוזרות (callbacks) של אירועי המודעות, המעקב אחרי המצב והניקוי במופע משותף אחד באפליקציה.
  • ההגדרה הזו קובעת מתי מתבצעת האזנה לאירועים שפועלים בחזית, כדי למנוע הצגה כפולה של מודעות אחרי שהמשתמש סוגר אותן.

בדוגמה הבאה מוטמע מנהל ברמת האפליקציה באמצעות האובייקט 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. לדוגמה, קוראים ל-method‏ start במופע של מנהל המודעות ברכיב App.tsx.

הצגת שכבות-על של מודעות או דפי נחיתה, כמו הצגת מודעות במסך מלא או לחיצה על מודעת באנר, מעבירה את האפליקציה לרקע. כשהמשתמש חוזר לאפליקציה, האפליקציה מקבלת אירוע חדש של מצב active. כדי למנוע הצגה לא מכוונת של מודעה או לולאה שבה החזרה ממודעה מציגה מודעה בפתיחת האפליקציה מהמטמון, צריך לבצע את הפעולות הבאות:

  1. צריך להסיר את רכיב ה-event listener של AppState לפני שמציגים מודעה במסך מלא.
  2. כדי לוודא שההאזנה תתחדש גם אם המשתמש סוגר את המודעה וגם אם המודעה לא מוצגת, מוסיפים שוב את רכיב ה-event listener של AppState בקריאות החוזרות (callbacks) של onAdDismissedFullScreenContent ושל onAdFailedToShowFullScreenContent.

כדי לראות דוגמה מלאה לשליטה על ההשהיה וההפעלה מחדש של פונקציות event listener שפועלות בחזית, עיינו בהטמעה של AppOpenAdManager.

מידע על הפעלות במצב התחלתי (cold start) ומסכי טעינה

הפעלה קרה מתרחשת כשהאפליקציה מופעלת מאפס, למשל כשמשתמש פותח את האפליקציה בפעם הראשונה או אחרי שהמכשיר סוגר את האפליקציה כדי לפנות זיכרון. במצב התחלתי, אין לכם מודעה בפתיחת האפליקציה שנטענה מראש כדי להציג אותה.

בגלל עיכובים בבקשות להצגת מודעות, יכול להיות שהמשתמשים יבצעו פעולות באפליקציה לפני שהמודעה תופיע. להציג מודעות בפתיחת האפליקציה בהפעלה במצב התחלתי רק ממסך טעינה בזמן שנכסי האפליקציה נטענים. אם טעינת הנכסים מסתיימת והמשתמש מגיע לתוכן הראשי לפני שהמודעה נטענת, אל תציגו את המודעה.

מחיקת משאבים

כשכבר לא צריך לטעון מראש מודעות במסך או במזהה יחידת מודעות מסוים, למשל כשעוברים ממסך שבו המודעות נטענות מראש, מפעילים את השיטה 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 במזהה של הטעינה מראש.

השלבים הבאים

אחרי שמשלבים מודעות בפתיחת האפליקציה, כדאי לעיין בנושאים הבאים: