المتطلبات الأساسية
أكمِل إعداد الأحداث المخصّصة.
طلب "إعلان مدمج مع المحتوى"
عند الوصول إلى بند عرض الحدث المخصّص في سلسلة "توسّط العرض الإعلاني بدون انقطاع"، يتم استدعاء الطريقة 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، وهي فئة "الإعلان المدمج مع المحتوى" التي تستخدمها حزمة 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 هذه السمة في مادة العرض "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()); }
أحداث الظهور والنقر
يجب أن تعرف كلّ من 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.