הגדרת מודעות מעברון מתגמלות

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

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

כדי למנוע עיכוב בהצגת המודעות ולוודא שהמודעה זמינה כשהמעבר מתרחש, Google Mobile Ads SDK for React Native משתמש בטעינת מודעות מראש כדי לנהל את הטעינה ברקע, את השמירה במטמון ואת חידוש המלאי במאגר הנתונים הזמני.

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

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

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

• מגדירים את Google Mobile Ads SDK for React Native.
• מפעילים מודעות בדיקה ומשתמשים ביחידת המודעות הייעודית לבדיקה הבאה:

Android

ca-app-pub-3940256099942544/5354046379

iOS

ca-app-pub-3940256099942544/6978759866

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

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

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

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

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

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

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

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

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

כשהאפליקציה שולפת מודעה שנטענה מראש מהמאגר, 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‏ RewardedInterstitialAdPreloader.isAdAvailable. כדי לאחזר את המודעה, צריך לבצע קריאה ל-method‏ RewardedInterstitialAdPreloader.pollAd.

כדי להציג מודעה, קוראים ל-method‏ show עם קריאה חוזרת (callback) של onUserEarnedReward כדי להעניק את התגמול כשהמשתמש מסיים לצפות במודעה. כדי להאזין לאירועי הצגה, כמו סגירת מודעות או כשלים בהצגה, מגדירים את המאפיין adEventCallback במופע המודעה לפני שקוראים ל-method‏ show.

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

export function showPreloadedRewardedInterstitialAd(
  preloadId: string,
  onRewardEarned: (reward: Reward) => void,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!RewardedInterstitialAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded rewarded interstitial ad available right now.');
    return;
  }

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

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

  ad.show(onRewardEarned);
}

כדי לפנות זיכרון ומשאבים, צריך להפעיל את ה-method‏ ad.destroy בקריאות החוזרות (callbacks) של onAdDismissedFullScreenContent ו-onAdFailedToShowFullScreenContent.

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

כדי לבדוק את פרטי התגובה של המודעה הבאה שנטענה מראש בלי להסיר את המודעה מהמטמון, מפעילים את ה-method‏ RewardedInterstitialAdPreloader.peekAdResponseInfo:

export function peekRewardedInterstitialAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo =
    RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log(
      'Next preloaded rewarded interstitial ad response info:',
      responseInfo,
    );
  }
  return responseInfo;
}

אם יש מודעה זמינה, השיטה peekAdResponseInfo מחזירה אובייקט ResponseInfo שמכיל מידע על מקור המודעות שנטען ועל מתאמי הרשת.

אופציונלי: אימות קריאות חוזרות של SSV

אם האפליקציה שלכם צריכה פרמטרים מותאמים אישית לאימות, כמו מזהה משתמש או מטא-נתונים מותאמים אישית של תגמול, בקריאות חוזרות (callback) של אימות בצד השרת (SSV), צריך להגדיר את המאפיין serverSideVerificationOptions במופע המודעה שנדגם לפני שקוראים ל-method‏ show.

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

• ‫userId: מועבר לפרמטר השאילתה user_id כדי לזהות את המשתמש.
• ‫customData: מועבר לפרמטר השאילתה custom_data כדי להעביר מטא-נתונים מותאמים אישית.

בדוגמה הבאה מוגדרים ServerSideVerificationOptions (customData וגם userId) באובייקט של מודעת מעברון מתגמלת לפני הצגת המודעה:

export function setServerSideVerificationRewardedInterstitial(
  ad: RewardedInterstitialAd,
) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

נקודה חשובה: הערך של הפרמטר custom_data של השאילתה כולל תו בריחה (escape) באחוזים, או מקודד בכתובת URL. כשמטפלים בקריאה החוזרת (callback) של SSV בשרת, צריך לפענח את כתובת ה-URL של המחרוזת הזו לפני העיבוד.

מחיקת משאבים

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

הדוגמה הבאה מפסיקה את הטעינה מראש:

export function destroyRewardedInterstitialAdPreloader(preloadId: string) {
  RewardedInterstitialAdPreloader.destroy(preloadId);
}

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

לצפייה בדוגמה המלאה

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

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

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedInterstitialAd(
      PRELOAD_ID,
      (userReward) => {
        setReward(`${userReward.amount} ${userReward.type}`);
      },
      {
        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 Rewarded Interstitial Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      {reward && <Text style={styles.rewardText}>Earned: {reward}</Text>}
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

השלבים הבאים

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

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