تمت ترجمة هذه الصفحة بواسطة 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));
}

الإعلانات المدمجة مع المحتوى على "خرائط Google"

تتضمّن حِزم 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 يوضّح كيفية توفير رمز AdChoices:

Java

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

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

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

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

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

الأحداث المخصّصة للإعلانات المدمجة مع المحتوى تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

Java

Java

Java

الإعلانات المدمجة مع المحتوى على "خرائط Google"

Java

الاحتفاظ بمرجع لعنصر "الإعلان المدمج مع المحتوى" الذي يتم التوسط فيه

ضبط خصائص مواد العرض التي تم ربطها

Java

مواد عرض صور الخرائط

Java

Java

إضافة حقول إلى حزمة الإضافات

Java

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

Java

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

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

Java

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

Java

Java

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

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