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

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

اختيار النظام الأساسي: Android (إصدار تجريبي)

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

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

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

يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة مستخدم "مدير إعلانات 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));
}

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

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

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

لمساعدتك في إدارة هذه التفاصيل، توفّر GMA Next-Gen SDK الفئة 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);

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

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

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

جافا

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

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

يجب أن تعرف كلّ من GMA Next-Gen SDK وحزمة تطوير البرامج (SDK) المستخدَمة في التوسّط وقت حدوث مرّة ظهور أو نقرة، ولكن يجب أن تتتبّع إحدى حِزم تطوير البرامج (SDK) هذه الأحداث. هناك طريقتان مختلفتان يمكن أن تستخدمهما الأحداث المخصّصة، وذلك حسب ما إذا كانت حزمة SDK للوسيطة تتيح تتبُّع مرّات الظهور والنقرات بشكلٍ مستقل.

تتبُّع النقرات ومرّات الظهور باستخدام GMA Next-Gen SDK

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

جافا

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

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

بما أنّ SampleNativeAdMapper يتضمّن مرجعًا إلى عنصر الإعلان الأصلي في حزمة تطوير البرامج (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() مقابلة يمكن للأحداث المخصّصة تجاهلها لإزالة أي مراجع إلى طريقة العرض وفصلها عن عنصر الإعلان المدمج مع المحتوى.

إعادة توجيه أحداث التوسّط إلى GMA Next-Gen SDK

يمكنك العثور على جميع الدوالّ التي تتوافق مع التوسّط في مستندات MediationNativeAdCallback.

من المهم أن يعيد توجيه الحدث المخصّص أكبر عدد ممكن من عمليات معاودة الاتصال هذه، كي يتلقّى تطبيقك الأحداث المكافئة من GMA Next-Gen SDK. في ما يلي مثال على استخدام عمليات معاودة الاتصال:

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

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

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

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

جافا

جافا

جافا

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

جافا

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

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

جافا

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

جافا

جافا

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

جافا

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

جافا

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

تتبُّع النقرات ومرّات الظهور باستخدام GMA Next-Gen SDK

جافا

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

جافا

جافا

إعادة توجيه أحداث التوسّط إلى GMA Next-Gen SDK

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