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

اختيار النظام الأساسي: Android iOS Unity Flutter Android (الإصدار القديم)

الإعلانات البينية مقابل مكافأة هي شكل إعلان يتيح لك تقديم مكافآت مقابل الإعلانات التي تظهر تلقائيًا أثناء عمليات الانتقال الطبيعية في التطبيق. على عكس "الإعلانات مقابل مكافأة"، لا يحتاج المستخدمون إلى الموافقة على مشاهدة "الإعلان البيني مقابل مكافأة".

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

قبل البدء

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

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

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

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

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

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

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

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

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

Kotlin

private fun startPreloading(adUnitId: String) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

جافا

private void startPreloading(String adUnitId) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

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

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

الحصول على الإعلان الذي تم تحميله مسبقًا وعرضه

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

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

Kotlin

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

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial 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 RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

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

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

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

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

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

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

Kotlin

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

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

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

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

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

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

جافا

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

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

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

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

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

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

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

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

يوضّح عينة تعليمات برمجية التالية كيفية ضبط بيانات مخصّصة على عنصر "إعلان بيني مقابل مكافأة" قبل عرض الإعلان:

Kotlin

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

جافا

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

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

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

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

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

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

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

جافا

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

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

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

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

Kotlin

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

جافا

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

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

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

يوضّح المثال التالي كيفية ضبط حجم ذاكرة التخزين المؤقت على إعلانَين تم تحميلهما مسبقًا:

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

جافا

private void setBufferSize(String adUnitId) {
  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);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

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

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

Kotlin

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

جافا

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

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

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

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

Kotlin

val responseInfo = RewardedInterstitialAdPreloader.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 = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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