טעינה של מודעה אחת בפתיחת אפליקציה

בחירת פלטפורמה: Android (גרסה קודמת) React Native

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

הנחיות ושיטות מומלצות לשימוש במודעות בפתיחת אפליקציה

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

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

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

• מגדירים את Google Mobile Ads SDK for 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 שנטען. המאזין הזה מקבל קריאות חוזרות (callbacks) של אירועים במחזור החיים של המודעה, כמו הצגת המודעה במסך או לחיצה של המשתמש על המודעה. אפשר לראות את הקריאות החוזרות הזמינות ב-AdEventCallback.

בדוגמה הבאה מוגדרות קריאות חוזרות (callback) כדי להאזין לאירועי מודעות:

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}`,
      );
    },
  };
}

בדוגמה הזו נעשה שימוש גם ב-method‏ 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;
  }
}

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

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

האזנה לאירועים של אפליקציות שפועלות בחזית

כדי להציג מודעות כשהאפליקציה חוזרת לחזית, משתמשים במודול AppState כדי להאזין לשינויים במצב האפליקציה ברמה הבסיסית (root) של האפליקציה, למשל בקובץ App.tsx. בצע את הפעולות הבאות:

1. רושמים פונקציית listener מסוג AppState לאירוע 'change'.
2. כשהמצב משתנה ל-'active', צריך להפעיל את השיטה showAdIfAvailable במופע של מנהל המודעות.

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

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

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

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

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

הגדרת מסך בדיקה

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

בדוגמה הבאה משולבת מודעה בפתיחת אפליקציה ברכיב React Native עם הוק (hook) לניקוי useEffect. אם הרכיב מוסר לפני שהמודעה מוצגת, ה-hook הזה משחרר משאבים מקוריים.

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>
  );
}

השלבים הבאים

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

• הכנסות מפרסום לפי חשיפות (iLAR)
• פרטיות המשתמשים והסכמה