الأحداث المخصّصة لإعلانات البانر

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

أكمِل إعداد الأحداث المخصّصة.

طلب إعلان بانر

عند الوصول إلى عنصر العرض الخاص بالحدث المخصّص في سلسلة "توسّط العرض الإعلاني بدون انقطاع"، يتم استدعاء الطريقة loadBannerAd() في اسم الفئة الذي قدّمته عند إنشاء حدث مخصّص. في هذه الحالة، تكون الطريقة في SampleCustomEvent، والتي تستدعي بعد ذلك الطريقة loadBannerAd() في SampleBannerCustomEventLoader.

لطلب إعلان بانر، أنشئ أو عدِّل فئة توسّع Adapter لتنفيذ loadBannerAd(). بالإضافة إلى ذلك، أنشئ فئة جديدة لتنفيذ MediationBannerAd.

في مثال الحدث المخصّص، توسّع SampleCustomEvent الفئة Adapter ثم تفوّض إلى SampleBannerCustomEventLoader.

Java

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.MediationAdConfiguration;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationBannerAd;
import com.google.android.gms.ads.mediation.MediationBannerAdCallback;
...

public class SampleCustomEvent extends Adapter {
  private SampleBannerCustomEventLoader bannerLoader;
  @Override
  public void loadBannerAd(
      @NonNull MediationBannerAdConfiguration adConfiguration,
      @NonNull MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback> callback) {
    bannerLoader = new SampleBannerCustomEventLoader(adConfiguration, callback);
    bannerLoader.loadAd();
  }
}

تتحمّل "SampleBannerCustomEventLoader" مسؤولية المهام التالية:

  • تحميل "إعلان البانر" واستدعاء طريقة MediationAdLoadCallback بعد اكتمال التحميل

  • تنفيذ واجهة MediationBannerAd

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

يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة المستخدم في إعدادات الإعلان. يمكن الوصول إلى المَعلمة من خلال adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD). تكون هذه المَعلمة عادةً معرّف وحدة إعلانية تتطلّبه حزمة تطوير البرامج (SDK) لشبكة إعلانية عند إنشاء مثيل لكائن إعلان.

Java

package com.google.ads.mediation.sample.customevent;

import com.google.android.gms.ads.mediation.Adapter;
import com.google.android.gms.ads.mediation.MediationBannerAdConfiguration;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationBannerAd;
import com.google.android.gms.ads.mediation.MediationBannerAdCallback;
...

public class SampleBannerCustomEventLoader extends SampleAdListener implements MediationBannerAd {

  /** View to contain the sample banner ad. */
  private SampleAdView sampleAdView;

  /** Configuration for requesting the banner ad from the third-party network. */
  private final MediationBannerAdConfiguration mediationBannerAdConfiguration;

  /** Callback that fires on loading success or failure. */
  private final MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback>
      mediationAdLoadCallback;

  /** Callback for banner ad events. */
  private MediationBannerAdCallback bannerAdCallback;

  /** Constructor. */
  public SampleBannerCustomEventLoader(
      @NonNull MediationBannerAdConfiguration mediationBannerAdConfiguration,
      @NonNull MediationAdLoadCallback<MediationBannerAd, MediationBannerAdCallback>
              mediationAdLoadCallback) {
    this.mediationBannerAdConfiguration = mediationBannerAdConfiguration;
    this.mediationAdLoadCallback = mediationAdLoadCallback;
  }

  /** Loads a banner ad from the third-party ad network. */
  public void loadAd() {
    // All custom events have a server parameter named "parameter" that returns
    // back the parameter entered into the UI when defining the custom event.
    Log.i("BannerCustomEvent", "Begin loading banner ad.");
    String serverParameter =
        mediationBannerAdConfiguration.getServerParameters().getString(
        MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD);

    Log.d("BannerCustomEvent", "Received server parameter.");

    Context context = mediationBannerAdConfiguration.getContext();
    sampleAdView = new SampleAdView(context);

    // Assumes that the serverParameter is the ad unit of the Sample Network.
    sampleAdView.setAdUnit(serverParameter);
    AdSize size = mediationBannerAdConfiguration.getAdSize();

    // Internally, smart banners use constants to represent their ad size, which
    // means a call to AdSize.getHeight could return a negative value. You can
    // accommodate this by using AdSize.getHeightInPixels and
    // AdSize.getWidthInPixels instead, and then adjusting to match the device's
    // display metrics.
    int widthInPixels = size.getWidthInPixels(context);
    int heightInPixels = size.getHeightInPixels(context);
    DisplayMetrics displayMetrics = Resources.getSystem().getDisplayMetrics();
    int widthInDp = Math.round(widthInPixels / displayMetrics.density);
    int heightInDp = Math.round(heightInPixels / displayMetrics.density);

    sampleAdView.setSize(new SampleAdSize(widthInDp, heightInDp));
    sampleAdView.setAdListener(this);

    SampleAdRequest request = createSampleRequest(mediationBannerAdConfiguration);
    Log.i("BannerCustomEvent", "Start fetching banner ad.");
    sampleAdView.fetchAd(request);
  }

  public SampleAdRequest createSampleRequest(
      MediationAdConfiguration mediationAdConfiguration) {
    SampleAdRequest request = new SampleAdRequest();
    request.setTestMode(mediationAdConfiguration.isTestRequest());
    request.setKeywords(mediationAdConfiguration.getMediationExtras().keySet());
    return request;
  }
}

استنادًا إلى ما إذا تم جلب الإعلان بنجاح أو حدث خطأ، عليك استدعاء onSuccess() أو onFailure(). يتم استدعاء onSuccess() من خلال تمرير مثيل للفئة التي تنفّذ MediationBannerAd.

عادةً، يتم تنفيذ هذه الطرق داخل عمليات ردّ الاتصال من حزمة تطوير البرامج (SDK) التابعة لجهة خارجية التي ينفّذها المحوّل. في هذا المثال، تحتوي حزمة تطوير البرامج (SDK) النموذجية على SampleAdListener مع عمليات رد اتصال ذات صلة:

Java

@Override
public void onAdFetchSucceeded() {
  bannerAdCallback = mediationAdLoadCallback.onSuccess(this);
}

@Override
public void onAdFetchFailed(SampleErrorCode errorCode) {
  mediationAdLoadCallback.onFailure(SampleCustomEventError.createSampleSdkError(errorCode));
}

يتطلّب MediationBannerAd تنفيذ طريقة الحصول على View:

Java

@Override
@NonNull
public View getView() {
  return sampleAdView;
}

إعادة توجيه أحداث التوسّط إلى حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"

بعد استدعاء onSuccess()، يمكن للمحوّل استخدام العنصر MediationBannerAdCallback الذي تم عرضه لإعادة توجيه أحداث العرض من حزمة تطوير البرامج (SDK) التابعة لجهة خارجية إلى حزمة تطوير البرامج (SDK) لـ "إعلانات Google على الأجهزة الجوّالة". يمتد الصف SampleBannerCustomEventLoader إلى الواجهة SampleAdListener لإعادة توجيه عمليات رد الاتصال من شبكة الإعلانات النموذجية إلى حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.

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

Java

@Override
public void onAdFullScreen() {
  bannerAdCallback.onAdOpened();
  bannerAdCallback.reportAdClicked();
}

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

بهذا يكتمل تنفيذ الأحداث المخصّصة لـ "إعلانات البانر". يتوفّر المثال الكامل على GitHub. يمكنك استخدامها مع شبكة إعلانية متوافقة أو تعديلها لعرض إعلانات بانر للأحداث المخصّصة.