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

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

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

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

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

يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة مستخدم "مدير إعلانات 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) التوسّطية مواد عرض إضافية غير تلك الواردة في شكل الإعلان المدمج في "مدير إعلانات Google". تتضمّن فئة UnifiedNativeAdMapper طريقة setExtras() التي تُستخدَم لتمرير مواد العرض هذه إلى الناشرين. يستخدم SampleNativeAdMapper هذه السمة لمادة عرض "درجة روعة" في حزمة SDK النموذجية:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

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

لتتبُّع مرّات الظهور والنقرات، قد تحتاج حزمة تطوير البرامج (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 لإعلانات Google على الأجهزة الجوّالة. في ما يلي مثال على استخدام وظائف الاستدعاء:

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