المتطلبات الأساسية
أكمِل إعداد الأحداث المخصَّصة.
طلب إعلان مدمج مع المحتوى
عند الوصول إلى عنصر الحدث المخصّص في سلسلة توسّط العرض الإعلاني بدون انقطاع،
يتم استدعاء طريقة 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 على الأجهزة الجوّالة".
المعلمة الاختيارية المحددة في واجهة مستخدم "مدير الإعلانات" هي
مضمّنة في إعدادات الإعلان. يمكن الوصول إلى المعلمة من خلال
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)); }
ربط الإعلانات المدمجة مع المحتوى
تمتلك حِزم 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
، بينما
يستخدم "مدير إعلانات Google" 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) التي تعتمد على التوسّط مواد عرض إضافية غير تلك الموجودة في
شكل الإعلان المدمج مع المحتوى في "مدير الإعلانات". UnifiedNativeAdMapper
تتضمن الفئة طريقة setExtras()
تُستخدم لتمرير هذه الأصول إلى
للناشرين. يستفيد SampleNativeAdMapper
من ذلك في نموذج حزمة SDK.
"درجة من الروعة" مادة العرض:
Java
Bundle extras = new Bundle(); extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness()); this.setExtras(extras);
يمكن للناشرين استرداد البيانات باستخدام فئة NativeAd
. getExtras()
.
خيارات الإعلان
يكون الحدث المخصّص مسؤولاً عن توفير رمز "خيارات الإعلان" باستخدام
طريقة "setAdChoicesContent()
" على UnifiedNativeAdMapper
. إليك مقتطف من
SampleNativeAdMapper
الذي يعرض كيفية تقديم رمز "خيارات الإعلان":
Java
public SampleNativeAdMapper(SampleNativeAd ad) { ... setAdChoicesContent(sampleAd.getInformationIcon()); }
أحداث الظهور والنقرات
تحتاج كل من حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" وحزمة SDK التي تعتمد على التوسّط إلى معرفة متى مرّة ظهور أو نقرة، ولكن تحتاج حزمة تطوير برامج (SDK) واحدة فقط إلى تتبُّع هذه الأحداث. هناك طريقتان مختلفتان يمكن للأحداث المخصّصة استخدامهما، اعتمادًا على ما إذا كان تعمل حزمة SDK التي تعتمد على التوسّط على تتبع مرات الظهور والنقرات بشكل مستقل.
تتبُّع النقرات ومرات الظهور باستخدام "SDK لإعلانات Google على الأجهزة الجوّالة"
إذا لم تكن حزمة تطوير البرامج التي تعتمد على التوسّط ميزة تتبُّع مرات الظهور والنقرات الخاصة بها، ولكن
توفر طرقًا لتسجيل النقرات ومرات الظهور، ويمكن لحزمة SDK لإعلانات Google على الأجهزة الجوّالة
وتتبع هذه الأحداث وإبلاغ المحوّل. تشير رسالة الأشكال البيانية
تتضمّن الفئة 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);
يجب أن تتوفّر الأحداث المخصّصة التي تلغي تتبُّع النقرات ومرات الظهور من أجل:
إبلاغ Google للجوّال عن أحداث onAdClicked()
وonAdImpression()
حزمة تطوير البرامج (SDK) لعرض الإعلانات
لتتبع مرات الظهور والنقرات، ربما تحتاج حزمة 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 لإعلانات الأجهزة الجوّالة. إليك مثال على استخدام عمليات معاودة الاتصال:
وبذلك، تكون قد أكملت تنفيذ الأحداث المخصّصة للإعلانات المدمجة مع المحتوى. المثال الكامل متاح على GitHub.