تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

اختيار النظام الأساسي: Android iOS 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

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

جافا

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

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

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

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

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