المتطلبات الأساسية
أكمِل عملية إعداد الأحاف المخصّصة.
طلب إعلان مدمج مع المحتوى
عند الوصول إلى بند حدث مخصّص في سلسلة توسّط العرض الإعلاني بدون انقطاع،
يتم استدعاء الطريقة 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
يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة مستخدم 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)); }
ربط الإعلانات المدمجة مع المحتوى
تتضمّن حِزَم SDK المختلفة أشكالها الفريدة للإعلانات المدمجة مع المحتوى. على سبيل المثال، قد تعرض إحدى حِزَم SDK كائنات تحتوي على حقل "العنوان"، بينما قد تحتوي حزمة SDK أخرى على "العنوان الرئيسي". بالإضافة إلى ذلك، يمكن أن تختلف الطرق المستخدَمة لتتبُّع مرّات الظهور ومعالجة النقرات من حزمة SDK إلى أخرى.
UnifiedNativeAdMapper مسؤول عن التوفيق بين هذه الاختلافات و
تكييف كائن الإعلان المدمج مع المحتوى في حزمة SDK التي يتم التوسّط فيها لتتطابق مع الواجهة التي تتوقّعها
Google Mobile Ads 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. يمكن أن تختلف أيضًا مقاييس وحدات البكسل لكل بوصة.
لمساعدتك في إدارة هذه التفاصيل، Google Mobile Ads 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));
إضافة حقول إلى حزمة extras
توفّر بعض حِزَم SDK التي يتم التوسّط فيها مواد عرض إضافية بخلاف تلك الموجودة في شكل الإعلان المدمج مع المحتوى في AdMob. تتضمّن فئة 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()); }
أحداث مرّات الظهور والنقرات
تحتاج كلّ من Google Mobile Ads SDK وحزمة SDK التي يتم التوسّط فيها إلى معرفة متى تحدث مرّة ظهور أو نقرة، ولكن تحتاج حزمة SDK واحدة فقط إلى تتبُّع هذه الأحداث. هناك طريقتان مختلفتان يمكن أن تستخدِمهما الأحداث المخصّصة، اعتمادًا على ما إذا كانت حزمة SDK التي يتم التوسّط فيها تتيح تتبُّع مرّات الظهور والنقرات من تلقاء نفسها.
تتبُّع النقرات ومرّات الظهور باستخدام Google Mobile Ads SDK
إذا كانت حزمة SDK التي يتم التوسّط فيها لا تتتبّع مرّات الظهور والنقرات من تلقاء نفسها ولكنها توفّر طرقًا لتسجيل النقرات ومرّات الظهور، يمكن لـ Google Mobile Ads 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() مقابلة يمكن للأحداث المخصّصة إلغاؤها لإزالة أي مراجع لطريقة العرض وفصلها عن كائن الإعلان المدمج مع المحتوى.
إعادة توجيه أحداث التوسّط إلى Google Mobile Ads SDK
يمكنك العثور على جميع عمليات معاودة الاتصال التي يتيحها التوسّط في الـ
MediationNativeAdCallback مستندات.
من المهم أن يعيد الحدث المخصّص توجيه أكبر عدد ممكن من عمليات معاودة الاتصال هذه، حتى يتلقّى تطبيقك هذه الأحداث المكافئة من Google Mobile Ads SDK. في ما يلي مثال على استخدام عمليات معاودة الاتصال:
بهذا نكون قد أكملنا عملية تنفيذ الأحداث المخصّصة للإعلانات المدمجة مع المحتوى. يتوفّر المثال الكامل على GitHub.