پیش نیازها
راه اندازی رویدادهای سفارشی را کامل کنید.
درخواست آگهی بومی
هنگامی که آیتم خط رویداد سفارشی در زنجیره واسطه آبشار به دست میآید، متد 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 شخص ثالثی که آداپتور شما پیادهسازی میکند، پیادهسازی میشود. برای این مثال، Sample 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 های مختلف فرمت های منحصر به فرد خود را برای تبلیغات بومی دارند. یکی ممکن است اشیایی را که حاوی یک فیلد "عنوان" هستند، برای مثال، برگرداند، در حالی که دیگری ممکن است دارای "headline" باشد. علاوه بر این، روشهای مورد استفاده برای ردیابی نمایشها و پردازش کلیکها میتواند از یک 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
را می پذیرد، کلاس تبلیغاتی بومی که توسط 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 بازگردانده شوند. مقیاس پیکسل به dpi آنها نیز می تواند متفاوت باشد.
برای کمک به مدیریت این جزئیات، 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));
فیلدها را به بسته نرم افزاری اضافه کنید
برخی از SDK های واسطه دارایی های اضافی فراتر از دارایی های موجود در قالب تبلیغات بومی AdMob ارائه می دهند. کلاس UnifiedNativeAdMapper
شامل یک متد setExtras()
است که برای ارسال این دارایی ها به ناشران استفاده می شود. SampleNativeAdMapper
از این برای دارایی "درجه عالی" Sample SDK استفاده می کند:
جاوا
Bundle extras = new Bundle(); extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness()); this.setExtras(extras);
ناشران می توانند داده ها را با استفاده از متد getExtras()
کلاس NativeAd
بازیابی کنند.
AdChoices
رویداد سفارشی شما مسئول ارائه نماد AdChoices با استفاده از روش setAdChoicesContent()
در UnifiedNativeAdMapper
است. در اینجا یک قطعه از SampleNativeAdMapper
است که نحوه ارائه نماد AdChoices را نشان می دهد:
جاوا
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()
به Google Mobile Ads SDK، رویدادهای سفارشی که ردیابی کلیک و نمایش را نادیده می گیرند، لازم است.
برای ردیابی نمایشها و کلیکها، 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()
متناظر را ارائه میکند که رویدادهای سفارشی میتوانند آن را لغو کنند تا هر گونه ارجاع به view را آزاد کند و آن را از شیء تبلیغاتی اصلی جدا کند.
رویدادهای میانجی را به Google Mobile Ads SDK بازارسال کنید
میتوانید تمام تماسهایی را که میانجیگری پشتیبانی میکند در اسناد MediationNativeAdCallback
پیدا کنید.
مهم است که رویداد سفارشی شما تا آنجایی که ممکن است این تماسهای پاسخگو را فوروارد کند تا برنامه شما این رویدادهای مشابه را از Google Mobile Ads SDK دریافت کند. در اینجا مثالی از استفاده از callback آورده شده است:
این پیاده سازی رویدادهای سفارشی را برای تبلیغات بومی تکمیل می کند. نمونه کامل در GitHub موجود است.