إعداد "الإعلانات مقابل مكافأة"

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

لإزالة وقت الاستجابة في العرض والتأكّد من توفّر الإعلان عندما يحصل المستخدم على مكافأة، تستخدم Google Mobile Ads SDK for React Native ميزة التحميل المسبَق للإعلانات لإدارة التحميل في الخلفية والتخزين المؤقت وتجديد المخزن المؤقت.

يوضّح لك هذا الدليل كيفية دمج "الإعلانات مقابل مكافأة" في تطبيق React Native.

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

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

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

فهم التحميل المسبَق للإعلانات

تؤدي ميزة "التحميل المسبَق للإعلان" في Google Mobile Ads SDK for React Native إلى تحميل الإعلانات وتخزينها مؤقتًا بشكل تلقائي.

يوفّر التحميل المسبَق للإعلانات المزايا التالية:

  • إدارة المراجع: تحتفظ بالمراجع إلى أن يتم عرض الإعلانات.
  • إعادة التحميل التلقائي: يتم تحميل إعلان جديد عند استرداد إعلان من ذاكرة التخزين المؤقت.
  • عمليات إعادة المحاولة المُدارة: يتم تحميل إعلان جديد عندما يتعذّر تحميل إعلان.
  • التعامل مع انتهاء الصلاحية: يتم إعادة تحميل الإعلانات قبل انتهاء صلاحيتها.
  • تحسين ذاكرة التخزين المؤقت: يحسّن ترتيب ذاكرة التخزين المؤقت لعرض الإعلان ذي الأولوية القصوى.

لتحميل الإعلانات يدويًا، يُرجى الاطّلاع على المقالة تحميل إعلان واحد مقابل مكافأة.

بدء التحميل المُسبَق

لبدء تحميل الإعلانات مسبقًا، استخدِم طريقة RewardedAdPreloader.start ومرِّر قيمة preloadId وإعدادات الضبط وعمليات الاستدعاء للأحداث من أجل مراقبة تغييرات حالة التخزين المؤقت:

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 بستة إعلانات محمَّلة مسبقًا كحدّ أقصى في الذاكرة. ويتم تطبيق هذا الحدّ على جميع أشكال الإعلانات ومعرّفات التحميل المُسبق.
  • حجم ذاكرة التخزين المؤقت المقترَح: اثنان لكل معرّف تحميل مسبق.

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

استطلاع الإعلان وعرضه

قبل عرض إعلان، تأكَّد من توفّره من خلال استدعاء الطريقة RewardedAdPreloader.isAdAvailable. لاسترداد الإعلان، استخدِم طريقة RewardedAdPreloader.pollAd.

للاستماع إلى أحداث العرض، مثل إغلاق الإعلانات أو تعذُّر عرضها، اضبط السمة adEventCallback في مثيل الإعلان قبل استدعاء الطريقة 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);
}

لإخلاء الذاكرة والموارد، استدعِ طريقة ad.destroy في دالّتَي الاستدعاء onAdDismissedFullScreenContent و onAdFailedToShowFullScreenContent.

قراءة معلومات الردّ

لفحص معلومات الاستجابة للإعلان التالي الذي تم تحميله مسبقًا بدون إزالة الإعلان من ذاكرة التخزين المؤقت، يمكنك استدعاء الطريقة 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 يحتوي على معلومات عن مصدر الإعلان الذي تم تحميله ومحوّلات الشبكة.

اختياري: التحقّق من صحة عمليات معاودة الاتصال في عملية التحقّق من جهة الخادم

إذا كان تطبيقك يتطلّب مَعلمات مخصّصة لعملية التحقّق، مثل رقم تعريف المستخدم أو البيانات الوصفية المخصّصة للمكافأة، في طلبات معاودة الاتصال من خلال عملية التحقّق من جهة الخادم، اضبط السمة serverSideVerificationOptions في مثيل الإعلان الذي تم استطلاعه قبل طلب show.

يتم تمرير القيم التي تضبطها إلى معلمات طلب البحث لردّ الاتصال من خلال SSV:

  • userId: يتم تمريرها إلى مَعلمة طلب البحث user_id لتحديد المستخدم.
  • customData: يتم تمريرها إلى مَعلمة طلب البحث custom_data لإعادة توجيه البيانات الوصفية المخصّصة.

يضبط المثال التالي ServerSideVerificationOptions (customData و userId) على عنصر "إعلان مقابل مكافأة" قبل عرض الإعلان:

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

حذف الموارد

إذا لم تعُد بحاجة إلى عرض إعلانات لمعرّف تحميل مسبق معيّن لبقية الجلسة، يمكنك استدعاء الطريقة 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 برقم تعريف أداة التحميل المُسبَق.

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

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