تمت ترجمة هذه الصفحة بواسطة 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 على الأجهزة الجوّالة"

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

Java

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

ويمكن للناشرين استرداد البيانات باستخدام طريقة getExtras() لفئة 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.