حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" في وضع الصيانة للحصول على آخر التحديثات والميزات، عليك migrate وإعداد "الجيل التالي من SDK لإعلانات Google على الأجهزة الجوّالة".

تستخدم 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
تلقّي عمليات ردّ الاتصال الخاصة بأحداث الإعلانات وإعداد تقارير عنها إلى Google Mobile Ads SDK (Legacy)

يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة مستخدم 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 التي يتم التوسط فيها ليتوافق مع الواجهة التي تتوقّعها Google Mobile Ads SDK (Legacy). يجب أن توسّع الأحداث المخصّصة هذه الفئة لإنشاء أدوات الربط الخاصة بها والمخصّصة لحزمة 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، وهي فئة الإعلانات المدمجة مع المحتوى التي تستخدمها حزمة Sample 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. ويمكن أن تختلف مقاييس البكسل إلى نقطة في البوصة.

لمساعدتك في إدارة هذه التفاصيل، توفّر Google Mobile Ads SDK (Legacy) فئة 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 من ذلك في مادة عرض "درجة الروعة" الخاصة بحزمة 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());
}

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

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

تتبُّع النقرات ومرّات الظهور باستخدام Google Mobile Ads SDK (Legacy)

إذا كانت حزمة SDK الخاصة بالوسيط لا تتتبّع مرّات الظهور والنقرات، ولكنّها توفّر طرقًا لتسجيل النقرات ومرّات الظهور، يمكن أن تتتبّع Google Mobile Ads SDK (Legacy) هذه الأحداث وتُرسِل إشعارًا إلى برنامج التكييف. يتضمّن الصف 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() مقابلة يمكن للأحداث المخصّصة تجاهلها لإلغاء أي مراجع إلى طريقة العرض وفصلها عن عنصر الإعلان المدمج مع المحتوى.

إعادة توجيه أحداث التوسّط إلى Google Mobile Ads SDK (Legacy)

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

من المهم أن يعيد توجيه الحدث المخصّص أكبر عدد ممكن من عمليات الاستدعاء هذه، كي يتلقّى تطبيقك الأحداث المكافئة من Google Mobile Ads SDK (Legacy). في ما يلي مثال على استخدام عمليات الرجوع:

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

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

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

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

جافا

جافا

جافا

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

جافا

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

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

جافا

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

جافا

جافا

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

جافا

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

جافا

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

تتبُّع النقرات ومرّات الظهور باستخدام Google Mobile Ads SDK (Legacy)

جافا

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

جافا

جافا

إعادة توجيه أحداث التوسّط إلى Google Mobile Ads SDK (Legacy)

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