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

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

قبل البدء

قبل المتابعة، يُرجى اتّباع الخطوات التالية:

• إعداد GMA Next-Gen SDK.
• استخدام رقم تعريف الوحدة الإعلانية الاختبارية "الإعلانات مقابل مكافأة"‏ /21775744923/example/rewarded
  • عند إنشاء تطبيقك واختباره، احرص على استخدام الإعلانات الاختبارية بدلاً من الإعلانات الفعلية المعروضة. إذا لم تستخدم رقم تعريف الوحدة الإعلانية الاختبارية، يمكن أن تعلّق Google حسابك.
  • قبل نشر تطبيقك، استبدِل هذا الرقم برقم تعريف وحدتك الإعلانية.
  • للاطّلاع على تفاصيل الإعلانات الاختبارية GMA Next-Gen SDK، يُرجى الاطّلاع على مقالة تفعيل الإعلانات الاختبارية.

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

تعمل ميزة التحميل المسبق للإعلانات (الإصدار التجريبي) في GMA Next-Gen SDK على أتمتة تحميل الإعلانات وتخزينها مؤقتًا.

تقدّم ميزة التحميل المسبق للإعلانات المزايا التالية:

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

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

لبدء التحميل المسبق للإعلانات، عليك استدعاء طريقة start مرة واحدة عند بدء التطبيق. بعد استدعاء طريقة 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. 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());
      });
}

إلى أن تصبح مستعدًا لعرض إعلان، تجنَّب استدعاء طريقة pollAd. لقراءة معلومات استجابة الإعلان بدون عرضه، يُرجى الاطّلاع على مقالة قراءة معلومات الاستجابة.

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

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

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.
        }
      });
}

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

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

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

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 ببياناتك المخصّصة.

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

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

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

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 تلقائيًا على التحميل المسبق للإعلانات وإعادة محاولة الطلبات التي تعذّر تنفيذها للإعدادات التي تم تحميلها مسبقًا.

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

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

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

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

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);
}

اختياري: قراءة معلومات الاستجابة

يمكنك قراءة معلومات استجابة الإعلان التالي الذي تم تحميله مسبقًا بدون إزالة الإعلان من ذاكرة التخزين المؤقت.

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

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());