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

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

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

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

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

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

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

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 على الأجهزة الجوّالة".

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

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 مع استدعاءات ذات صلة:

@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 التي تعتمد على التوسط. إليك نموذج مصمم خرائط إعلانات من مثال على مشروع الحدث المخصص:

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

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

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

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

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

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

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

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

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 فئة الصور التي تمّ ربطها في هذا الخط لضبط مادة عرض صورة رمز مصمم الخرائط:

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

إضافة حقول إلى حزمة العناصر الإضافية

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

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

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

@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.