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

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

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

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

عند الوصول إلى عنصر العرض الخاص بالحدث المخصّص في سلسلة "توسّط العرض الإعلاني بدون انقطاع"، يتم استدعاء الطريقة 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);

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

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

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

Java

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

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

يجب أن تعرف كلّ من حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة وحزمة تطوير البرامج (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) الخاصة بـ &quot;إعلانات Google على الأجهزة الجوّالة&quot;.

لتتبُّع مرّات الظهور والنقرات، من المحتمل أنّ حزمة 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.