تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

يكون الحدث المخصّص مسؤولاً عن توفير رمز "خيارات الإعلان" باستخدام طريقة 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 يحتوي على إشارة إلى عنصر الإعلان المضمّن في حِزمة تطوير البرامج Sample 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.