پیاده سازی تبلیغات همسان Native ADS برای اندروید

تنظیمات اولیه کتابخانه:

در فایل gradle اصلی پروژه ریپازیتوری تپلیغ را به صورت زیر به لیست ریپازیتوریهای خود اضافه کنید:

 

maven { url  "https://dl.bintray.com/tapligh/Tapligh-SDK" }

خروجی نهایی فایل باید به صورت شکل زیر باشد.

در مرحله بعد دیپندنسی تپلیغ را به صورت زیر به لیست دیپندنسی های ماژول اپ خود اضافه کنید:

// for gradle 3.0 and above
implementation 'com.tapligh.sdk:native-sdk:1.+'
// for gradle before version 3.0
compile 'com.tapligh.sdk:native-sdk:1.+'

بعد از اینکه gradle پروژه خود را یک بار سینک کنید کتابخانه تپلیغ به پروژه شما اضافه خواهد شد.

 

مرحله دوم: ساخت کلاس Application:

 

این کلاس، extend شده ی کلاس Application هست به کمک این کلاس میتوانیم به lifecycle اپلیکیشن خود دسترسی پیدا کنیم. مثلاً اگر میخواهیم تابعی با اجرا شدن برنامه و یا حتی پیش از اجرای اولین activity شروع شده و با بستن آن خاتمه پیدا کند آن را در این کلاس قرار میدهیم.

برای ساختن این کلاس کافیست یک کلاس به نام دلخواه (به طور مثال App) را در ریشه پروژه خود ایجاد نمایید و آن را از کلاس application ، extends کنید

حال در فایل AndroidManifest.xml بایستی این کلاس را معرفی کنیم. به همین منظور داخل تگ application نام این کلاس را به attribute به نام android:name اضافه میکنیم.

مرحله سوم: معرفی کتابخانه تپلیغ به برنامه

برای معرفی کتابخانه تپلیغ به اپ خود بایستی تنظیمات آن  را در متد oncreate() کلاس  Application برنامه خودتون اضافه کنید.

new Tapligh.Builder(application, "Your-App-Token")
   .setTestMode(false)
   .build();

ورودی اول این کلاس یک رفرنس از کلاس application و ورودی دوم رشته توکنی است که پس از تعریف برنامه خود از پنل تپلیغ دریافت نموده اید. در صورتی که اپ خود را هنوز در پنل تپلیغ تعریف نکرده‌اید، آن را ایجاد نمایید.

 

توجه: در صورتی که قصد تست برنامه خود را دارید ورودی متد  setTestMode را برابر true قرار داده و در انتهای تست خود مقدار آن را false نمایید.

جهت تست پروژه خود ترجیحا از Emulator ها استفاده ننمایید.

نمونه پروژه پیاده سازی تبلیغات همسان

پیاده‌سازی نمایش تبلیغ همسان به صورت تکی:

 

مرحله اول: ساخت layout تبلیغ

تبلیغات همسان برای نمایش نیاز به layout دارد که این layout توسط توسعه‌دهنده ساخته میشود. شما در این layout محدودیتی از جهت تعداد آیتم، رنگ، شکل، و سایر مشخصات ظاهری نداشته و تنها بایستی لی اوت رووت آن را TaplighNativeAdView تعریف کرده و یک آی دی به آن اختصاص دهید.

 این کلاس extends شده از کلاس RelativeLayout است. این لی اوت تبلیغ حتماً باید حداقل دارای عنوان و یک تصویر (آیکن و یا بنر) باشد. آیتم هایی که در تبلیغ همسان پشتیبانی می‌شود :

عنوان تبلیغ

آیکون تبلیغ

بنر تبلیغ

توضیح تبلیغ

آیکون مارکت

لینک فرود

توجه: در صورتی که میخواهید از cardView برای ویوی تبلیغ خود استفاده کنید به دلیل ویژگی‌هایی  که این ویو از نظر z-order دارد آن را  رووت لی اوت خود گذاشته و تگ TaplighNativeAdView را در زیر آن قرار دهید.

 

 

مرحله دوم: معرفی layout ساخته شده به تپلیغ

 

در کلاس جاوایی که قصد نمایش تپلیغ همسان دارید کلاس TaplighNativeAdView را از طریق آی دی ای که به آن اختصاص داده بودید تعریف کنید.

nativeAdView = findViewById(R.id.native_ad_root);

حال بایستی آیتم هایی را که برای نمایش درlayout قرار داده بودید به کتابخانه تپلیغ معرفی کنید. این تعریف را از طریق کلاس AdViewBinding  انجام دهید.. در این کلاس آی دی هر آیتم به صورت متناظر بایست تعریف شود.

AdViewBinding adBinding =
new AdViewBinding.Builder()
   .setTitleRes(R.id.native_title)
   .setIconRes(R.id.native_icon)
   .setBannerRes(R.id.native_banner)
   .setDescriptionRes(R.id.native_desc)
   .setMarketIconRes(R.id.native_market)
   .setActionTextRes(R.id.native_cta)
   .build();

موارد اختیاری:

۱)  کلاس  AdViewBinding از طریق کلاس AdViewBindingOption می‌تواند تنظیمات دریافت کند. در صورتی که از بنر برای نمایش تبلیغات استفاده می‌کنید از طریق این کلاس می‌توانید نسبت تصویر آن (‌Aspect ratio) را مشخص کنید. بنرها میتوانند یکی از نسبت‌های 1*1 ، 16*9 و 9*16 را داشته باشند. اگر از بنر استفاده میکنید و این Option را مشخص نکرده باشید به صورت پیش‌فرض بنر ۱*۱ لود میشود. همچنین در صورت دلخواه میتوانید برای بنر و آیکون خود placeHolder تعریف کنید تا پیش از لود شدن عکس تبلیغ نمایش داده شوند. تمامی این تنظیمات را میتوانید از طریق این کلاس تعریف کرده و در نهایت به آبجکت AdViewBinding اختصاص دهید.

AdViewBindingOption option = new AdViewBindingOption();
option.setBannerAR(AspectRatio.AR16x9);
option.setBannerPlaceHolder(your-banner-placeHolder);
option.setIconPlaceHolder(your-icon-placHolder);

) برای تغییر جایگاه نمایش badge تبلیغات میتوانید از طریق متد setAdPlacement داخل کلاس TaplighNativeAdView این کار را انجام دهید. Badge تبلیغات میتواند در یکی از جایگاه های top_left ، top_right ، bottom_left و bottom_right قرار گیرد. تمامی این مقادیر از طریق کلاس  BadgePosition قابل دستیابی هستند.

در انتها این آبجکت را داخل آبجکت کلاس TaplighNativeAdView که تعریف کرده بودید set کنید.

nativeAdView.setAdViewBinder(adBinding);

مرحله سوم:‌ درخواست تبلیغ

به کمک کلاس NativeAdLoader میتوانید یک درخواست تبلیغ (تبلیغات) همسان را ثبت کنید. برای ساختن این درخواست باید از کلاس Builder داخل کلاس NativeAdLoader استفاده کنید. این کلاس دو ورودی دارد . ورودی اول رفرنسی از Context و ورودی دوم رشته کد مربوط به واحد تبلیغی است که برای نمایش تبلیغ همسان در پنل تعریف کرده اید. در صورتی که این واحد تبلیغ را تعریف نکرده‌اید آن را ایجاد نمایید. شما میتوانید در هر بار درخواست حداکثر تعداد ۵ تبلیغ را دریافت کنید. تعیین این مقدار بر عهده شما و وابسته به عمل‌کرد برنامه شما است. این کنترل را از طریق متد setRequestNumber میتوانید انجام دهید. نتیجه این درخواست از طریق callback ای که در این builder تعریف میکنید برگردانده می شود. این callback دو متد دارد. متد onAdLoaded زمانی فراخوانی می‌شود که نتیجه درخواست تبلیغ موفقیت آمیز باشد. در اینصورت تبلیغات لود شده در ورودی این متد قابل دریافت هستند.

NativeAdLoader loader = new NativeAdLoader
   .Builder(context, "unit-code")
   .setRequestNumber(1)
   .setListener(new NativeAdLoadingListener() {
@Override
public void onAdLoaded(List<TaplighNativeAd> ads) {
}
@Override
public void onLoadError(LoadErrorStatus status) {
}
}).build();
loader.loadAd();

نکته مهم:‌ توجه کنید که تعداد تبلیغاتی که متد onAdLoaded برمیگرداند لزوماً با تعداد تبلیغاتی در متد setRequestNumber معین می‌شود برابر نیستند، یعنی به طور مثال شما درخواست ۵ تبلیغ را داده‌اید اما سرور تبلیغ ممکن است۲ تبلیغ به شما بدهد.

در صورتی که نتیجه درخواست تبلیغ موفقیت آمیز نباشد متد onLoadError فراخوانی میشود. ورودی این متد وضعیت خطای رخ داده را نشان میدهد. این وضعیت‌ها یکی از مقادیر زیر ممکن است باشند:

noInternetAccess: در صورتی که اتصال به اینترنت برقرار نباشد

appNotFound: این مقدار در صورتی برگردانده می‌شود که توکن داده شده به کلاس Tapligh در کلاس Application اشتباه باشد.

 adUnitNotFound:این مقدار در صورتی برگردانده می‌شود که رشته کد واحد تبلیغی که به کلاس Builder داده باشید اشتباه باشد.

adUnitDisabled: در صورتی که واحد تبلیغ غیر فعال شده باشد این مقدار برگردانده می شود.

NoAdReady: اگر در حال حاضر تبلیغی برای نمایش وجود نداشته باشد این مقدار برگردانده می شود.

InternalError: در صورتی که هر گونه خطایی خارج از موارد ذکر شده (همچون تایم اوت شدن ریکویست، در دسترس نبودن سرور، اختلال در عمل‌کرد داخلی کتابخانه و… ) رخ دهد این مقدار برگردانده میشود.

مرحله چهارم: نمایش تبلیغ

برای نمایش تبلیغ کافیست آبجکتTaplighNativeAd را از طریق متد showAd به آبجکت TaplighNativeAdView بدهید.

nativeAdView.showAd(ads.get(0));

پیاده‌سازی نمایش تبلیغ همسان در یک لیست

مرحله اول: ساخت layout تبلیغ

تبلیغات همسان برای نمایش نیاز به layout دارد که این layout توسط توسعه‌دهنده ساخته میشود. شما در این layout محدودیتی از جهت تعداد آیتم، رنگ، شکل، و سایر مشخصات ظاهری نداشته و تنها بایستی لی اوت رووت آن را TaplighNativeAdView تعریف کرده و یک آی دی به آن اختصاص دهید.

 این کلاس extends شده از کلاس RelativeLayout است. این لی اوت تبلیغ حتماً باید حداقل دارای عنوان و یک تصویر (آیکن و یا بنر) باشد. آیتم هایی که در تبلیغ همسان پشتیبانی می‌شوند:

عنوان تبلیغ

آیکون تبلیغ

بنر تبلیغ

توضیح تبلیغ

آیکون مارکت

لینک فرود

توجه: در صورتی که میخواهید از cardView برای ویوی تبلیغ خود استفاده کنید به دلیل ویژگی‌هایی  که این ویو از نظر z-order دارد آن را  رووت لی اوت خود گذاشته و تگ TaplighNativeAdView را در زیر آن قرار دهید.

مرحله دوم: تعیین استراتژی نمایش تبلیغات

شما با استفاده از کلاس AdPlacementStrategy می‌توانید استراتژی نمایش تبلیغات در لیست را تعیین نمایید. این استراتژی به دو صورت میتواند تعریف شود.

AdPlacementStrategy placementStrategy = new AdPlacementStrategy();

۱) نمایش تبلیغات در جایگاه های ثابت :‌به عنوان مثال در آیتم ۲ ، ۸ ، ۱۸ . در این صورت میتوانید با استفاده از متد addFixedPosition این جایگاه ها را تعیین کنید. به عنوان مثال مورد ذکر شده به صورت زیر خواهد بود:

placementStrategy
  .addFixedPosition(2)
  .addFixedPosition(8)
  .addFixedPosition(18);

۲) نمایش تبلیغات به صورت تکرار شونده: در صورتی که میخواهید تبلیغ در فاصله های  یکسان نمایش داده شود از متد enableRepeatingMode استفاده کنید. به عنوان مثال در صورتی که میخواهید تبلیغات با فاصله ثابت هر ۸ آیتم یکبار نمایش داده شوند مقدار این متد را به صورت زیر تعیین نمایید:

placementStrategy.enableRepeatingMode(8);

مرحله سوم: ایجاد Adapter تپلیغ

برای نمایش تبلیغات درون لیست نیازی نیست تا تغییری در آبجکت Adapter اصلی خود ایجاد نمایید. بلکه تنها نیاز است تا یک نمونه از کلاس TaplighRecyclerAdapter را ایجاد کنید.

TaplighRecyclerAdapter mTaplighAdapter = new TaplighRecyclerAdapter(activity, originalAdapter, placementStrategy);

 ساخت این آبجکت نیاز به ۳ ورودی دارد. ورودی اول رفرنس activity ، ورودی دوم آبجکت adapter اصلی لیست که پیش از اضافه کردن تپلیغ استفاده می‌شد و ورودی سوم آبجکت AdPlacementStrategy که در مرحله قبل ایجاد نمودید.

مرحله چهارم: معرفی layout ساخته شده به Adapter تپلیغ

در این مرحله بایستی آیتم هایی را که برای نمایش درlayout تبلیغ قرار داده بودید به کتابخانه تپلیغ معرفی کنید. این تعریف را از طریق کلاس AdViewBinding  انجام می‌شود. در این کلاس بایستی آی دی هر آیتم به صورت متناظر به متد مربوطه assign شود.

AdViewBinding adBinding =
new AdViewBinding.Builder()
   .setTitleRes(R.id.native_title)
   .setIconRes(R.id.native_icon)
   .setBannerRes(R.id.native_banner)
   .setDescriptionRes(R.id.native_desc)
   .setMarketIconRes(R.id.native_market)
   .setActionTextRes(R.id.native_cta)
   .build();

حال برای آنکه تبلیغات در لیست به درستی نمایش داده شوند بایستی layout و آیتم های view آن به لیست تعریف شود. به همین منظور یک نمونه از کلاس TaplighNativeRenderer بایستی به صورت زیر ساخته شود:

TaplighNativeRenderer  renderer = new TaplighNativeRenderer(int layoutResId, int rootId, AdViewBinding viewBinding)

برای ایجاد این آبجکت نیاز به ۳ ورودی است. ورودی اول آی دی layout تبلیغ، ورودی دوم آی دی تگ TaplighNativeAdView ، و ورودی سوم آبجکت AdViewBinding که پیش از این ساخته شد.

اختیاری: برای تغییر جایگاه نمایش badge تبلیغات میتوانید از متد setBadgePosition داخل کلاس TaplighNativeRenderer استفاده نمایید. Badge تبلیغات میتواند در یکی از جایگاه های top_left ، top_right ، bottom_left و bottom_right قرار گیرد. تمامی این مقادیر از طریق کلاس  BadgePosition قابل دستیابی هستند.

در انتها آبجکت  renderer را از طریق متد setAdRenderer به Adapter تپلیغ به صورت زیر معرفی کنید و این Adapter را به جای Adapter اصلی خود به RecyclerView بدهید.

mTaplighAdapter.setAdRenderer(renderer);
mRecyclerView.setAdapter(mTaplighAdapter);

مرحله پنجم: نمایش تبلیغات

برای نمایش تبلیغات از متد loadAd آبجکت TaplighRecyclerAdapter به صورت زیر استفاده کنید:

mTaplighAdapter.loadAd(unit-code);

ورودی این متد رشته کد مربوط به واحد تبلیغی است که برای نمایش تبلیغ همسان در پنل تعریف کرده اید.

در نهایت کد شما به این شکل خواهد بود:‌

‌AdPlacementStrategy placementStrategy = new AdPlacementStrategy();
placementStrategy.enableRepeatingMode(7);
AdViewBinding binder = new AdViewBinding.Builder()
   .setIconRes(icon_res_id)
   .setTitleRes(title_res_id)
   .setActionTextRes(cta_res_id)
   .build();
binder.setBindingOption(new AdViewBindingOption());
TaplighRecyclerAdapter mTaplighAdapter = new TaplighRecyclerAdapter(getActivity(), mOriginalAdapter, placementStrategy);
mTaplighAdapter.setAdRenderer(new TaplighNativeRenderer(
                              layout_res_id,
                              tapligh_native_ad_view_res_id,
                              binder)
                             .setBadgePosition(BadgePosition.top_left));
mRecyclerView.setAdapter(mTaplighAdapter);
mTaplighAdapter.loadAd(unit-code);

موارد پیشرفته تر:

تبلیغات در لیست در حالت نرمال به صورت یک آیتم تبلیغ در ادامه سایر آیتم های عادی لیست نمایش داده میشود. همانند شکل زیر :‌

اما اگر  نیاز دارید تا تبلیغات را به صورت بنری به پهنای تمام عرض صفحه (به خصوص در GridView) نمایش دهید (همانند شکل زیر) می‌توانید تا از این متد Adapter تپلیغ استفاده نمایید.

mTaplighAdapter.showAdAsBanner(true);

در این حالت تبلیغات به صورت بنری به پهنای تمام عرض صفحه نمایش داده خواهند شد. در صورتی که position تبلیغ در میانه لیست باشد، جایگاه نمایش تبلیغ به نحوی شیفت پیدا می‌کند تا در اول ردیف بعد قرار گیرد.

لطفا نظرات خود را در زمینه تجربه استفاده از SDK از طریق developers@tapligh.com ، شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۴۴۴ و یا تلگرام با ما در میان بگذارید.