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

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

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

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

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

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

تحميل إعلان

لتحميل "إعلان مقابل مكافأة"، استخدِم طريقة load في فئة RewardedAd.

يحمّل المثال التالي إعلانًا مقابل مكافأة في حال نجاح العملية ويسجّل خطأً في حال فشلها:

export async function loadRewardedAd(
  adUnitId: string,
): Promise<RewardedAd | null> {
  try {
    const ad = await RewardedAd.load({adUnitId});
    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load rewarded ad:', loadError.message);
    return null;
  }
}

الاستماع إلى أحداث الإعلانات

قبل عرض الإعلان، اضبط أداة الاستماع adEventCallback على مثيل RewardedAd الذي تم تحميله. يتلقّى هذا المستمع عمليات استدعاء لأحداث يتم في مراحل نشاط الإعلان، مثل ظهور الإعلان على الشاشة أو نقر المستخدم على الإعلان. للاطّلاع على عمليات الاستدعاء المتاحة، يُرجى مراجعة AdEventCallback.

يضبط المثال التالي عمليات الاستدعاء لرصد أحداث الإعلانات:

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

يستدعي هذا المثال أيضًا الإجراء destroy عندما يغلق المستخدم الإعلان أو عندما يتعذّر عرض الإعلان. تؤدي هذه العملية إلى تحرير الموارد التي استخدمها الإعلان.

عرض الإعلان

لعرض "إعلان مقابل مكافأة"، استخدِم طريقة show مع ردّ اتصال لمعالجة المكافأة التي حصل عليها المستخدم:

export function showRewardedAd(
  ad: RewardedAd,
  onRewardEarned: (reward: Reward) => void,
) {
  ad.show(onRewardEarned);
}

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

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

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

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

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

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

عرض المثال الكامل

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

يدمج المثال التالي الإعلان في مكوّن React Native، ويدير مثيل الإعلان في الحالة، ويوفّر عناصر تحكّم لتحميل الإعلان وعرضه:

export function RewardedSingleLoadScreen() {
  const [ad, setAd] = useState<RewardedAd | null>(null);
  const [isLoaded, setIsLoaded] = useState(false);
  const [status, setStatus] = useState<string>('Idle');
  const [reward, setReward] = useState<string | null>(null);

  useEffect(() => {
    return () => {
      ad?.destroy();
    };
  }, [ad]);

  const handleLoad = async () => {
    setReward(null);
    setStatus('Loading Rewarded ad...');
    const loadedAd = await loadRewardedAd(REWARDED_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('Rewarded ad loaded!');
    } else {
      setStatus('Failed to load Rewarded ad.');
    }
  };

  const handleShow = () => {
    if (ad) {
      showRewardedAd(ad, (userReward) => {
        setReward(`${userReward.amount} ${userReward.type}`);
      });
      setIsLoaded(false);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Rewarded Ad (Single Load)</Text>
      <Text style={styles.status}>Status: {status}</Text>
      {reward && <Text style={styles.rewardText}>Earned: {reward}</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>
  );
}

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

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