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

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

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

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

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

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

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

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

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

לפני שמציגים מודעה, צריך לוודא שיש מודעה זמינה על ידי הפעלת ה-method‏ RewardedAdPreloader.isAdAvailable. כדי לאחזר את המודעה, מפעילים את ה-method‏ RewardedAdPreloader.pollAd.

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

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

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

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

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

  ad.show(onRewardEarned);
}

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

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

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

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

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

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

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

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

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

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

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

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

מחיקת משאבים

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

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

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

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

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

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

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedAd(
      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 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>
  );
}

מחליפים את מה שכתוב בשדות הבאים:

• ‫REWARDED_AD_UNIT_ID במזהה יחידת המודעות.
• ‫PRELOAD_ID במזהה של הטעינה מראש.

השלבים הבאים

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

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