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

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

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

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

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

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

في مثال الحدث المخصّص، SampleCustomEvent تنفّذ the Adapter interface ثم تفوض إلى 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 interface

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

يتم تضمين المعلمة الاختيارية المحددة في Ad Manager واجهة المستخدم في إعداد الإعلان. يمكن الوصول إلى المَعلمة من خلال 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 المختلفة على أشكال فريدة خاصة بها للإعلانات المدمجة مع المحتوى. على سبيل المثال، قد يعرض أحدهما كائنات تحتوي على حقل "title"، بينما قد يحتوي عنصر آخر على "headline". بالإضافة إلى ذلك، يمكن أن تختلف الطرق المستخدمة لتتبع مرات الظهور ومعالجة النقرات من حزمة 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، بينما يستخدمAd Manager 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 المستندة إلى التوسّط مواد عرض إضافية تتجاوز مواد العرض المتوفّرة في Ad Manager شكل الإعلانات المدمجة مع المحتوى. تتضمن الفئة UnifiedNativeAdMapper الإجراء setExtras() الذي يُستخدم لتمرير مواد العرض هذه إلى الناشرين. تستفيد السمة SampleNativeAdMapper من هذا الإجراء في مادة عرض "مستوى الروعة" في نموذج حزمة تطوير البرامج (SDK):

Java

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

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

AdChoices

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

Java

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

الأحداث الناتجة عن مرات الظهور والنقرات

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

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

إذا لم تنفِّذ حزمة SDK المعتمَدة على التوسّط تتبُّع مرات الظهور والنقرات الخاصة بها، ولكنها توفّر طرقًا لتسجيل النقرات ومرات الظهور، يمكن لحزمة SDK لإعلانات Google على الأجهزة الجوّالة تتبُّع هذه الأحداث وإرسال إشعار إلى المحوّل. UnifiedNativeAdMapper interface تتضمن طريقتين: 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 لإعلانات Google على الأجهزة الجوّالة". في ما يلي مثال على استخدام عمليات معاودة الاتصال:

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