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

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

أكمِل إعداد الأحداث المخصّصة.

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

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

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

جافا

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

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

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

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

لتتبُّع مرّات الظهور والنقرات، قد تحتاج حزمة تطوير البرامج (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.