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

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

قبل البدء

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

• إعداد GMA Next-Gen SDK
• استخدِم معرّف الوحدة الإعلانية الاختبارية "للإعلانات مقابل مكافأة" ca-app-pub-3940256099942544/5224354917.
  • عند إنشاء تطبيقك واختباره، تأكَّد من استخدام الإعلانات الاختبارية بدلاً من الإعلانات النهائية المباشرة. إذا لم تستخدم معرّف الوحدة الإعلانية الاختبارية، يمكن أن تعلّق Google حسابك.
  • قبل نشر تطبيقك، استبدِل هذا المعرّف بمعرّف الوحدة الإعلانية.
  • للحصول على تفاصيل حول الإعلانات الاختبارية في GMA Next-Gen SDK، يُرجى الاطّلاع على مقالة تفعيل الإعلانات الاختبارية.

فهم ميزة "التحميل المسبَق للإعلان" (إصدار تجريبي)

تؤدي ميزة "التحميل المسبَق للإعلان" في GMA Next-Gen SDK إلى تحميل الإعلانات وتخزينها مؤقتًا بشكل تلقائي.

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

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

بدء التحميل المسبَق للإعلانات

لبدء التحميل المُسبق للإعلانات، يمكنك استدعاء طريقة start مرة واحدة عند إعداد GMA Next-Gen SDK. بعد استدعاء طريقة start، يحمّل GMA Next-Gen SDK الإعلانات مسبقًا تلقائيًا ويعيد محاولة الطلبات التي تعذّر تنفيذها للإعدادات المحمَّلة مسبقًا.

يوضّح المثال التالي كيفية بدء تحميل الإعلانات مسبقًا:

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig);

استبدِل AD_UNIT_ID بمعرّف الوحدة الإعلانية.

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

لا تتيح ميزة "التحميل المُسبَق للإعلان" تغيير مَعلمات الاستهداف أو طلبات عرض الإعلان. إذا كنت بحاجة إلى تغيير معلمات الاستهداف بين الطلبات، استخدِم التحميل الفردي.

الحصول على الإعلان المحمَّل مسبقًا وعرضه

قبل عرض الإعلان، استدعِ الطريقة pollAd. لا تخزِّن عنصر الإعلان المحمَّل مسبقًا. عند استدعاء طريقة pollAd، يستردّ GMA Next-Gen SDK إعلانًا متاحًا ويحمّل الإعلان التالي تلقائيًا في الخلفية. في حال عدم توفّر أي إعلان، لا يعرض GMA Next-Gen SDK أي إعلانات.

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

عندما يصل تطبيقك إلى موضع إعلان ويمكنه طلب الإجراء show، اطلب الإجراء pollAd. لا تستدعِ طريقة pollAd في عمليات الاستدعاء للتحميل المُسبق أو بعد التحقّق من طريقة isAdAvailable لإيقاف عرض الإعلان مؤقتًا. إذا كنت بحاجة إلى فحص البيانات الوصفية للإعلان قبل عرضه، يمكنك قراءة معلومات الاستجابة بدون إزالة الإعلان من ذاكرة التخزين المؤقت.

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

قبل عرض الإعلان، استمِع إلى أحداث الإعلانات. يسجّل المثال التالي عمليات الاستدعاء لأحداث الإعلانات:

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedAd
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded ad did dismiss.
        rewardedAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded ad failed to show.
        Log.e(TAG, "Rewarded ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded ad did record a click.
      }
    }
}

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedAd == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.");
    return;
  }

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded ad did dismiss.
          rewardedAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            FullScreenContentError fullScreenContentError) {
          // Rewarded ad failed to show.
          Log.e(TAG, "Rewarded ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded ad did record a click.
        }
      });
}

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

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

• معلمة طلب البحث user_id: تحدّد المستخدم الذي ستتم مكافأته، مثل رقم تعريف حساب داخلي.
• معلمة طلب البحث custom_data: تحمل بيانات التطبيق، مثل موضع المكافأة أو مستوى اللعبة أو رقم خاص يتم إنشاؤه من خلال الخادم.

إذا لم تضبط قيمة، ستحذف Google مَعلمة طلب البحث هذه من طلب معاودة الاتصال للتحقّق من صحة الخادم.

يضبط المثال التالي بيانات مخصّصة على عنصر إعلان قبل عرض الإعلان:

RewardedAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedAd) {
      rewardedAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedAd?.setServerSideVerificationOptions(options)
    }
  },
)

RewardedAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedAd ad) {
        rewardedAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedAd.setServerSideVerificationOptions(options);
      }
    });

استبدِل SAMPLE_CUSTOM_DATA_STRING ببياناتك المخصّصة.

نقطة أساسية: مَعلمة طلب البحث custom_data هي مُرمَّزة بالنسبة المئوية. قبل تحليل القيمة، عليك فك ترميز عنوان URL للسلسلة على الخادم والتحقّق من توقيع معاودة الاتصال قبل الوثوق بمعلمات طلب البحث user_id أو custom_data.

اختياري: الاستماع إلى أحداث التحميل المُسبق

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

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

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

عند تعذُّر تحميل إعلان، يحمّل GMA Next-Gen SDK الإعلانات مسبقًا تلقائيًا ويعيد محاولة الطلبات التي تعذّر تنفيذها للإعدادات المحمَّلة مسبقًا. لا تستدعِ طلبات التحميل اليدوية في عمليات الاستدعاء التي تعذّر إجراؤها. في طرق رد الاتصال الخاصة بأحداث التحميل المُسبق، لا تستدعِ الطرق pollAd أو destroy أو start. يمكن أن يؤدي استدعاء هذه الطرق في عمليات الاستدعاء إلى استدعاء حلقات تحميل متكررة.

اختياري: التحقّق من توفّر الإعلانات

إذا كنت بحاجة إلى معرفة ما إذا كان هناك إعلان متاح، تحقَّق من توفّر الإعلانات. يتحقّق المثال التالي مما إذا كان هناك إعلان محمَّل مسبقًا:

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedAdPreloader.isAdAvailable(adUnitId)
}

private boolean isAdAvailable(String adUnitId) {
  return RewardedAdPreloader.isAdAvailable(adUnitId);
}

اختياري: ضبط حجم المخزن المؤقت

يتحكّم حجم ذاكرة التخزين المؤقت في عدد الإعلانات المحمَّلة مسبقًا والمحفوظة في الذاكرة. تُحسِّن Google تلقائيًا حجم المخزن المؤقت لتحقيق التوازن بين استهلاك الذاكرة ووقت استجابة عرض الإعلانات. يمكنك ضبط حجم ذاكرة التخزين المؤقت المخصّص من أجل زيادة أو تقليل عدد الإعلانات المحفوظة في الذاكرة. ننصح باستخدام حجم ذاكرة التخزين المؤقت الذي يتسع لإعلانَين محمّلَين مسبقًا. إذا كانت معظم الزيارات تأتي من أجهزة ذات ذاكرة منخفضة، يمكنك تقليل حجم ذاكرة التخزين المؤقت.

يوضّح المثال التالي كيفية ضبط حجم المخزن المؤقت:

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
RewardedAdPreloader.start(adUnitId, preloadConfig);

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

يفرض GMA Next-Gen SDK حدًا أقصى على مستوى التطبيق لإجمالي عدد الإعلانات التي يتم تحميلها مسبقًا في جميع الوحدات الإعلانية وأرقام تعريف التحميل المُسبق:

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

اختياري: إيقاف التحميل المُسبق للإعلانات

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

يوضّح المثال التالي كيفية إيقاف التحميل المُسبَق للإعلانات:

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.destroy(adUnitId)
}

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.destroy(adUnitId);
}

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

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

يوضّح المثال التالي كيفية قراءة معلومات استجابة الإعلان التالي الذي تم تحميله مسبقًا:

val responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

ResponseInfo responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());