تنفيذ محوِّل إعلان يضم مكافأة

ملاحظة مهمة: استخدامك لحزمة SDK لإعلانات Google على الأجهزة الجوّالة في ما يتعلق بخدمات التوسّط يخضع لبنود خدمة التوسّط.

ويتلقى محوِّل التوسّط الرسائل والطلبات من حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة، كما يتواصل مع حزمة تطوير البرامج (SDK) للشبكة التابعة لجهة خارجية من أجل تلبية هذه الطلبات.

هذا الدليل مخصّص لشبكات الإعلانات التي تتطلّع إلى إنشاء محوّل توسّط للإعلانات التي تضم مكافأة من أجل توسّط إعلانات Google على الأجهزة الجوّالة. يُستخدم نموذج SDK في مقتطفات الرمز أدناه لأغراض العرض التوضيحي. يمكنك العثور على تنفيذ كامل لمُعدِّل تم تصميمه لنموذج حزمة تطوير البرامج (SDK) هذا في مشروع Android التوسّط. يشرح هذا الدليل كيفية إنشاء المحوّل.

تحديد اسم فئة المحوِّل ومعلمات الخادم

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

قبل تطوير محوّل توسّط، يجب تزويد Google باسم فئة المحوِّل والمَعلمات الأخرى المطلوبة حتى تتمكّن من الوصول إلى شبكة المواقع الإعلانية.

تنفيذ فئة المحوِّل

الخطوة الأولى هي تنفيذ الفئة المجرّدة Adapter:

...
import com.google.android.gms.ads.mediation.Adapter;
...

public class SampleAdapter extends Adapter {
 ...
}

يضمن هذا التغيير في صفك تنفيذ العديد من الطرق التي تمت مناقشتها أدناه.

الإبلاغ عن أرقام الإصدارات

يجب أن يقدّم المحوِّل تقريرًا إلى "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" عن إصدار المعدِّل نفسه وإصدار حزمة تطوير البرامج (SDK) التابعة لجهة خارجية. يتم الإبلاغ عن الإصدارات باستخدام VersionInfo.

تستخدم المحوّلات المفتوحة المصدر والمحوِّلات ذات الإصدارات من Google نظام إصدار للمحوّل مكوّن من 4 أرقام، لكن VersionInfo تسمح فقط باستخدام 3 أرقام. لتفادي ذلك، يوصى بدمج آخر رقمين في إصدار التصحيح، كما هو موضح أدناه:

...
import com.google.android.gms.ads.VersionInfo;
...

public class SampleAdapter extends Adapter implements SampleRewardedAdListener {
  ...
  @Override
  public VersionInfo getVersionInfo() {
    String versionString = BuildConfig.VERSION_NAME;
    String[] splits = versionString.split("\\.");

    if (splits.length >= 4) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]) * 100 + Integer.parseInt(splits[3]);
      return new VersionInfo(major, minor, micro);
    }

    return new VersionInfo(0, 0, 0);
  }

  @Override
  public VersionInfo getSDKVersionInfo() {
    String versionString = SampleAdRequest.getSDKVersion();
    String[] splits = versionString.split("\\.");

    if (splits.length >= 3) {
      int major = Integer.parseInt(splits[0]);
      int minor = Integer.parseInt(splits[1]);
      int micro = Integer.parseInt(splits[2]);
      return new VersionInfo(major, minor, micro);
    }

    return new VersionInfo(0, 0, 0);
  }
  ...
}

تهيئة المحوّل

عند إعداد حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة في أحد التطبيقات، يتم استدعاء initialize() في جميع المحوِّلات التي تم إعدادها للتطبيق ضمن واجهة مستخدم AdMob.

توفر الوسيطة List<MediationConfiguration> معلومات حول جميع مواضع الإعلانات التي تم ضبطها لشبكة الإعلانات ضمن واجهة مستخدم AdMob. استخدِم هذه المعلومات لإعداد حزمة تطوير البرامج (SDK) لشبكتك الإعلانية بعد إعداد حزمة تطوير البرامج (SDK) لشبكة المواقع الإعلانية، أبلِغ حزمة SDK لإعلانات Google على الأجهزة الجوّالة بعملية الإعداد الناجحة أو التي تعذّر إتمامها من خلال استدعاء طريقة onInitializationSucceeded() أو onInitializationFailed() في InitializationCompleteCallbackالوسيطة المتوفّرة في طلب initialize().

...
import com.google.android.gms.ads.mediation.InitializationCompleteCallback;
import com.google.android.gms.ads.mediation.MediationConfiguration;
...

public class SampleAdapter extends Adapter {
  ...
  @Override
  public void initialize(
      Context context,
      InitializationCompleteCallback initializationCompleteCallback,
      List<MediationConfiguration> mediationConfigurations) {
    if (context == null) {
      initializationCompleteCallback.onInitializationFailed(
          "Initialization Failed: Context is null.");
      return;
    }

    // The Sample SDK doesn't have an initialization method, so this example
    // immediately reports a success callback.
    initializationCompleteCallback.onInitializationSucceeded();
  }
  ...
}

طلب إعلان يضم مكافأة

استخدِم طريقة loadRewardedAd() لطلب إعلان يضم مكافأة. احتفظ بمرجع إلى MediationAdLoadCallback، الذي يتيح لك الإبلاغ عن تحميل إعلان ناجح أو فاشل إلى حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.

سيتوفّر العنصر MediationRewardedAdCallback بعد استدعاء onSuccess()، الذي ستستخدمه لاحقًا لإحالة أحداث إعلانات أخرى مثل النقرات أو المكافآت الممنوحة.

...
import com.google.ads.mediation.sample.sdk.SampleAdRequest;
import com.google.ads.mediation.sample.sdk.SampleRewardedAd;
import com.google.ads.mediation.sample.sdk.SampleRewardedAdListener;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationRewardedAd;
import com.google.android.gms.ads.mediation.MediationRewardedAdCallback;
...

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...

  /**
   * A MediationAdLoadCallback that handles any callback when a Sample rewarded
   * ad finishes loading.
   */
  private MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback> adLoadCallBack;

  /**
   * Represents a SampleRewardedAd.
   */
  private SampleRewardedAd sampleRewardedAd;

  /**
   * Used to forward rewarded video ad events to the Google Mobile Ads SDK..
   */
  private MediationRewardedAdCallback rewardedAdCallback;

  ...

  // Hold a reference to the MediationAdLoadCallback object to report ad load
  // events to the Google Mobile Ads SDK.
  @Override
  public void loadRewardedAd(
      MediationRewardedAdConfiguration mediationRewardedAdConfiguration,
      MediationAdLoadCallback<MediationRewardedAd, MediationRewardedAdCallback>
          mediationAdLoadCallback) {
    adLoadCallBack = mediationAdLoadCallback;
    MediationRewardedAdConfiguration adConfiguration = mediationRewardedAdConfiguration;

    String adUnitId = adConfiguration.getServerParameters().getString(SAMPLE_AD_UNIT_KEY);

    sampleRewardedAd = new SampleRewardedAd(adUnitId);
    SampleAdRequest request = new SampleAdRequest();
    sampleRewardedAd.setListener(this);
    sampleRewardedAd.loadAd(request);
  }

  // Hold a reference to the MediationRewardedAdCallback object to report ad
  // lifecycle events to the Google Mobile Ads SDK.
  @Override
  public void onRewardedAdLoaded() {
    rewardedAdCallback = mediationAdLoadCallBack.onSuccess(this);
  }

  @Override
  public void onRewardedAdFailedToLoad(SampleErrorCode error) {
    mediationAdLoadCallBack.onFailure(error.toString());
  }
  ...
}

عرض الإعلان

قد تطلب حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة طريقة showAd() للمحوِّل في أي وقت بعد إشعار حزمة تطوير البرامج (SDK) بتحميل إعلانات ناجح. من المفترض أن يعرض المحوِّل الإعلان الذي يضم مكافأة إذا تعذّر عرض الإعلان لأي سبب من الأسباب، يُرجى الاتصال بمعاودة الاتصال بـ onAdFailedToShow().

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...
  @Override
  public void showAd(Context context) {
    if (!(context instanceof Activity)) {
      rewardedAdCallback.onAdFailedToShow(
          "An activity context is required to show Sample rewarded ad.");
      return;
    }
    Activity activity = (Activity) context;

    if (!sampleRewardedAd.isAdAvailable()) {
      rewardedAdCallback.onAdFailedToShow("No ads to show.");
      return;
    }
    sampleRewardedAd.showAd(activity);
  }
  ...
}

إعداد تقارير عن أحداث الإعلانات في "حزمة تطوير البرامج (SDK) لعرض الإعلانات للأجهزة الجوّالة"

بعد عرض الإعلان، يجب أن يُبلغ المحوِّل عن أحداث مراحل نشاط الإعلان على أنّها ملائمة لحزمة تطوير البرامج "SDK لإعلانات Google على الأجهزة الجوّالة" باستخدام العنصرMediationRewardedAdCallback المقدَّم في وقت تحميل الإعلان بنجاح.

عادةً ما تتم إعادة توجيه عمليات الاستدعاء هذه من طرق الاستدعاء التي تطلقها حزمة تطوير البرامج (SDK) لشبكة المواقع الإعلانية. ينفِّذ هذا المثال عمليات استدعاء نموذج حزمة تطوير البرامج (SDK) ويربطها بعمليات معاودة الاتصال المتاحة على MediationRewardedAdCallback.

public class SampleAdapter extends Adapter, SampleRewardedAdListener
    implements MediationRewardedAd {
  ...
  @Override
  public void onAdRewarded(final String rewardType, final int amount) {
    RewardItem rewardItem =
        new RewardItem() {
          @Override
          public String getType() {
            return rewardType;
          }

          @Override
          public int getAmount() {
            return amount;
          }
        };
    rewardedAdCallback.onUserEarnedReward(rewardItem);
  }

  @Override
  public void onAdClicked() {
    rewardedAdCallback.reportAdClicked();
  }

  @Override
  public void onAdFullScreen() {
    rewardedAdCallback.onAdOpened();
    rewardedAdCallback.onVideoStart();
    rewardedAdCallback.reportAdImpression();
  }

  @Override
  public void onAdClosed() {
    rewardedAdCallback.onAdClosed();
  }

  @Override
  public void onAdCompleted() {
    rewardedAdCallback.onVideoComplete();
  }
  ...
}

في ما يلي تفاصيل عن أحداث الإعلانات التي يجب إعداد تقارير بها لحزمة "SDK لإعلانات Google على الأجهزة الجوّالة":

حدث الإعلان	الوصف
onAdOpened()	تُعلِم حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة بأنّه سيتم فتح الإعلان.
onVideoStart()	يتم إرسال إشعار إلى حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة عند بدء عرض الإعلان الذي يضم مكافأة.
reportAdImpression()	يتم إرسال إشعار إلى حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة بحدوث مرة ظهور للإعلان.
onVideoComplete()	تُعلِم "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" بانتهاء عرض الإعلان الذي يضم مكافأة.
onUserEarnedReward()	يتم إرسال إشعار إلى حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة تفيد بأنّ المستخدم قد حصل على مكافأة.
reportAdClicked()	تُعلِم حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة بأنّه تم النقر على الإعلان.
onAdClosed()	تُعلِم حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة بأنّه تم إغلاق الإعلان.
onAdFailedToShow()	تُعلِم "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" بأنّه تعذّر عرض الإعلان.