الأحداث المخصّصة للإعلانات المدمجة مع المحتوى

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

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

طلب إعلان مدمج مع المحتوى

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

لطلب إعلان مدمج مع المحتوى، أنشئ فئة أو عدِّلها تمتد من Adapter لتطبيق loadNativeAd(). إذا كان هناك فئة تمديد Adapter، نفِّذ loadNativeAd() فيها. بالإضافة إلى ذلك، قم بإنشاء فئة جديدة لتنفيذها UnifiedNativeAdMapper

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

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.MediationNativeAdCallback;
...
public class SampleCustomEvent extends Adapter {
  private SampleNativeCustomEventLoader nativeLoader;

  @Override
  public void loadNativeAd(
      @NonNull MediationNativeAdConfiguration adConfiguration,
      @NonNull MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback> callback) {
    nativeLoader = new SampleNativeCustomEventLoader(adConfiguration, callback);
    nativeLoader.loadAd();
  }
}

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

• يتم تحميل الإعلان المدمج مع المحتوى.

• جارٍ تنفيذ الفئة UnifiedNativeAdMapper.

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

المعلمة الاختيارية المحددة في واجهة مستخدم AdMob هي مضمّنة في إعدادات الإعلان. يمكن الوصول إلى المعلمة من خلال 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.MediationNativeAdConfiguration;
import com.google.android.gms.ads.mediation.MediationAdLoadCallback;
import com.google.android.gms.ads.mediation.MediationNativeAdCallback;
...

public class SampleNativeCustomEventLoader extends SampleNativeAdListener {
  /** Configuration for requesting the native ad from the third-party network. */
  private final MediationNativeAdConfiguration mediationNativeAdConfiguration;

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

  /** Callback for native ad events. */
  private MediationNativeAdCallback nativeAdCallback;

  /** Constructor */
  public SampleNativeCustomEventLoader(
      @NonNull MediationNativeAdConfiguration mediationNativeAdConfiguration,
      @NonNull MediationAdLoadCallback<MediationNativeAd, MediationNativeAdCallback>
              mediationAdLoadCallback) {
    this.mediationNativeAdConfiguration = mediationNativeAdConfiguration;
    this.mediationAdLoadCallback = mediationAdLoadCallback;
  }

  /** Loads the native ad from the third-party ad network. */
  public void loadAd() {
    // Create one of the Sample SDK's ad loaders to request ads.
    Log.i("NativeCustomEvent", "Begin loading native ad.");
    SampleNativeAdLoader loader =
        new SampleNativeAdLoader(mediationNativeAdConfiguration.getContext());

    // All custom events have a server parameter named "parameter" that returns
    // back the parameter entered into the UI when defining the custom event.
    String serverParameter = mediationNativeAdConfiguration
        .getServerParameters()
        .getString(MediationConfiguration
        .CUSTOM_EVENT_SERVER_PARAMETER_FIELD);
    Log.d("NativeCustomEvent", "Received server parameter.");

    loader.setAdUnit(serverParameter);

    // Create a native request to give to the SampleNativeAdLoader.
    SampleNativeAdRequest request = new SampleNativeAdRequest();
    NativeAdOptions options = mediationNativeAdConfiguration.getNativeAdOptions();
    if (options != null) {
      // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should
      // send just the URLs for the images.
      request.setShouldDownloadImages(!options.shouldReturnUrlsForImageAssets());

      request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages());
      switch (options.getMediaAspectRatio()) {
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE);
          break;
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_PORTRAIT:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT);
          break;
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_SQUARE:
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_ANY:
        case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_UNKNOWN:
        default:
          request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_ANY);
      }
    }

    loader.setNativeAdListener(this);

    // Begin a request.
    Log.i("NativeCustomEvent", "Start fetching native ad.");
    loader.fetchAd(request);
  }
}

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

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

Java

@Override
public void onNativeAdFetched(SampleNativeAd ad) {
  SampleUnifiedNativeAdMapper mapper = new SampleUnifiedNativeAdMapper(ad);
  mediationNativeAdCallback = mediationAdLoadCallback.onSuccess(mapper);
}

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

ربط الإعلانات المدمجة مع المحتوى

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

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

Java

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

import com.google.android.gms.ads.mediation.UnifiedNativeAdMapper;
import com.google.android.gms.ads.nativead.NativeAd;
...

public class SampleUnifiedNativeAdMapper extends UnifiedNativeAdMapper {

  private final SampleNativeAd sampleAd;

  public SampleUnifiedNativeAdMapper(SampleNativeAd ad) {
    sampleAd = ad;
    setHeadline(sampleAd.getHeadline());
    setBody(sampleAd.getBody());
    setCallToAction(sampleAd.getCallToAction());
    setStarRating(sampleAd.getStarRating());
    setStore(sampleAd.getStoreName());
    setIcon(
        new SampleNativeMappedImage(
            ad.getIcon(), ad.getIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
    setAdvertiser(ad.getAdvertiser());

    List<NativeAd.Image> imagesList = new ArrayList<NativeAd.Image>();
    imagesList.add(new SampleNativeMappedImage(ad.getImage(), ad.getImageUri(),
        SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
    setImages(imagesList);

    if (sampleAd.getPrice() != null) {
      NumberFormat formatter = NumberFormat.getCurrencyInstance();
      String priceString = formatter.format(sampleAd.getPrice());
      setPrice(priceString);
    }

    Bundle extras = new Bundle();
    extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
    this.setExtras(extras);

    setOverrideClickHandling(false);
    setOverrideImpressionRecording(false);

    setAdChoicesContent(sampleAd.getInformationIcon());
  }

  @Override
  public void recordImpression() {
    sampleAd.recordImpression();
  }

  @Override
  public void handleClick(View view) {
    sampleAd.handleClick(view);
  }

  // The Sample SDK doesn't do its own impression/click tracking, instead relies on its
  // publishers calling the recordImpression and handleClick methods on its native ad object. So
  // there's no need to pass a reference to the View being used to display the native ad. If
  // your mediated network does need a reference to the view, the following method can be used
  // to provide one.

  @Override
  public void trackViews(View containerView, Map<String, View> clickableAssetViews,
      Map<String, View> nonClickableAssetViews) {
    super.trackViews(containerView, clickableAssetViews, nonClickableAssetViews);
    // If your ad network SDK does its own impression tracking, here is where you can track the
    // top level native ad view and its individual asset views.
  }

  @Override
  public void untrackView(View view) {
    super.untrackView(view);
    // Here you would remove any trackers from the View added in trackView.
  }
}

لنلقِ الآن نظرة فاحصة على رمز الدالة الإنشائية.

وضع إشارة إلى كائن "الإعلان المدمج مع المحتوى" الذي يستند إلى التوسّط

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

ضبط خصائص مواد العرض المرتبطة

تستخدم الدالة الإنشائية الكائن SampleNativeAd لتعبئة مواد العرض في UnifiedNativeAdMapper

يحصل هذا المقتطف على بيانات أسعار الإعلان الذي يتم التوسط له ويستخدمها لتحديد السعر:

Java

if (sampleAd.getPrice() != null) {
    NumberFormat formatter = NumberFormat.getCurrencyInstance();
    String priceString = formatter.format(sampleAd.getPrice());
    setPrice(priceString);
}

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

مواد عرض الصور على الخريطة

إنّ تعيين مواد عرض الصور أكثر تعقيدًا من ربط أنواع بيانات مثل double أو String قد يتم تنزيل الصور تلقائيًا أو يتم عرضها كقيم عناوين URL. قد تتفاوت أيضًا مقاييسها من بكسل إلى نقطة لكل بوصة.

لمساعدتك في إدارة هذه التفاصيل، توفر حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" صف واحد (NativeAd.Image). بالطريقة نفسها التي تحتاج فيها إلى إنشاء فئة فرعية من UnifiedNativeAdMapper لربط إعلان مدمج مع المحتوى يتمّ توسّطه، عليك أيضًا إنشاء فئة فرعية من NativeAd.Image عند ربط مواد عرض الصور.

في ما يلي مثال على فئة SampleNativeMappedImage للحدث المخصّص:

Java

public class SampleNativeMappedImage extends NativeAd.Image {

  private Drawable drawable;
  private Uri imageUri;
  private double scale;

  public SampleNativeMappedImage(Drawable drawable, Uri imageUri, double scale) {
    this.drawable = drawable;
    this.imageUri = imageUri;
    this.scale = scale;
  }

  @Override
  public Drawable getDrawable() {
    return drawable;
  }

  @Override
  public Uri getUri() {
    return imageUri;
  }

  @Override
  public double getScale() {
    return scale;
  }
}

يستخدم العنصر SampleNativeAdMapper فئة الصورة المُعرَّفة في هذا السطر لضبط مادة عرض رمز المعرِّف:

Java

setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(),
    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));

إضافة حقول إلى حزمة الميزات الإضافية

توفِّر بعض حِزم تطوير البرامج (SDK) التي تعتمد على التوسّط مواد عرض إضافية غير تلك الموجودة في شكل الإعلان المدمج مع المحتوى في AdMob. UnifiedNativeAdMapper تتضمن الفئة طريقة setExtras() تُستخدم لتمرير هذه الأصول إلى للناشرين. يستفيد SampleNativeAdMapper من ذلك في نموذج حزمة SDK. "درجة من الروعة" مادة العرض:

Java

Bundle extras = new Bundle();
extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
this.setExtras(extras);

يمكن للناشرين استرداد البيانات باستخدام فئة NativeAd. getExtras() .

خيارات الإعلان

يكون الحدث المخصّص مسؤولاً عن توفير رمز "خيارات الإعلان" باستخدام طريقة setAdChoicesContent() في UnifiedNativeAdMapper. في ما يلي مقتطف من SampleNativeAdMapper يوضّح كيفية عرض رمز "خيارات الإعلان":

Java

public SampleNativeAdMapper(SampleNativeAd ad) {
    ...
    setAdChoicesContent(sampleAd.getInformationIcon());
}

أحداث الظهور والنقر

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

تتبُّع النقرات ومرات الظهور باستخدام "SDK لإعلانات Google على الأجهزة الجوّالة"

إذا لم تكن حزمة SDK التي تعتمد على التوسط تعمل على تتبع مرات الظهور والنقرات الخاصة بها، ولكن توفر طرقًا لتسجيل النقرات ومرات الظهور، ويمكن استخدام SDK لإعلانات Google على الأجهزة الجوّالة وتتبع هذه الأحداث وإبلاغ المحوّل. تشير رسالة الأشكال البيانية تتضمّن الفئة UnifiedNativeAdMapper طريقتَين: recordImpression() وhandleClick() يمكن تنفيذ أحداث مخصصة لاستدعاء الطريقة المطابقة في وسيط عرض الإعلان عنصر الإعلان المدمج مع المحتوى:

Java

@Override
public void recordImpression() {
  sampleAd.recordImpression();
}

@Override
public void handleClick(View view) {
  sampleAd.handleClick(view);
}

لأنّ SampleNativeAdMapper تشير إلى الإصدار الأصلي من نموذج حزمة تطوير البرامج (SDK) كائن الإعلان، فيمكنه استدعاء الطريقة المناسبة على هذا الكائن للإبلاغ عن حدوث نقرة أو مرة ظهور. يُرجى العلم أنّ طريقة handleClick() تستخدم مَعلمة واحدة: العنصر View المقابل لمادة عرض الإعلان المدمج مع المحتوى التي نقرة.

تتبع النقرات ومرات الظهور باستخدام حزمة SDK التي تعتمد على التوسّط

قد تفضّل بعض حِزم تطوير البرامج (SDK) التوسّط في تتبُّع النقرات ومرّات الظهور بنفسها. ضِمن في هذه الحالة، يجب إلغاء التتبُّع التلقائي للنقرات ومرات الظهور إجراء الاستدعاءين التاليين في الدالة الإنشائية UnifiedNativeAdMapper:

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

إنّ الأحداث المخصّصة التي تلغي تتبُّع النقرات ومرّات الظهور مطلوبة لتسجيل حدثَي onAdClicked() وonAdImpression() في حزمة SDK لإعلانات Google على الأجهزة الجوّالة.

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

Java

@Override
public void trackViews(View containerView,
    Map<String, View> clickableAssetViews,
    Map<String, View> nonClickableAssetViews) {
  sampleAd.setNativeAdViewForTracking(containerView);
}

إذا كانت حزمة تطوير البرامج (SDK) المعتمَدة على التوسّط تتيح تتبُّع أصول فردية، يمكنها البحث في clickableAssetViews للاطّلاع على طرق العرض التي يجب أن تكون قابلة للنقر. هذه الخريطة مرتبطًا باسم مادة عرض في NativeAdAssetNames. يوفّر UnifiedNativeAdMapper طريقة untrackView() مقابلة يمكن للأحداث المخصّصة إلغاء أثرها لإلغاء أيّ إشارات إلى العرض وإلغاء ربطه بجسم الإعلان المدمج .

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

يمكنك العثور على جميع عمليات تسجيل المكالمات التي تتيحها التوسّط في ملفّات مستندات MediationNativeAdCallback.

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

يُكمِل ذلك تنفيذ الأحداث المخصّصة للإعلانات المدمجة مع المحتوى. المثال الكامل متاح على GitHub.