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

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

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

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

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

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

Android 

ca-app-pub-3940256099942544/5354046379

iOS 

ca-app-pub-3940256099942544/6978759866

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

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

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

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

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

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

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

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 دالة الاستدعاء onAdsExhausted.

حدود التحميل المُسبَق لذاكرة التخزين المؤقت

يفرض Google Mobile Ads SDK for React Native حدًا أقصى على مستوى التطبيق لإجمالي عدد الإعلانات التي يتم تحميلها مسبقًا:

  • الحدّ التلقائي: تحتفظ Google بستة إعلانات محمَّلة مسبقًا كحدّ أقصى في الذاكرة. ويتم تطبيق هذا الحدّ على جميع أشكال الإعلانات ومعرّفات التحميل المُسبق.
  • العدد المقترَح: إعلانان محمَّلان مسبقًا لكل معرّف تحميل مسبق.

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

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

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

لعرض إعلان، يمكنك استدعاء طريقة show باستخدام دالة رد اتصال onUserEarnedReward لمنح المكافأة عندما ينتهي المستخدم من مشاهدة الإعلان. للاستماع إلى أحداث العرض، مثل إغلاق الإعلانات أو أخطاء العرض، اضبط السمة adEventCallback على مثيل الإعلان قبل استدعاء الطريقة 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);
}

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

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

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

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

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

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

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

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

حذف الموارد

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

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

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