No description, website, or topics provided.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Files
libs
.gitignore
InterstitialActivity.bas
LICENSE.md
NativeBannerActivity.bas
NativeVideoActivity.bas
README.md
StandardBannerActivity.bas
Starter.bas
TapsellSDK_B4A.b4a

README.md



تنظیمات اولیه پروژه

جهت راه اندازی تبلیغات تپسل در اپلیکیشن شما، ابتدا باید مراحل زیر را در پروژه خود انجام دهید.

[ht_message mstyle="danger" title="نکته Build پروژه" " show_icon="" id="" class="" style="" ]برای Build کردن پروژه حتما نوع Build را در حالت Release قرار دهید.[/ht_message]

گام ۱: دریافت SDK تپسل

فایل حاوی SDK تپسل را از آدرس زیر دریافت کنید و محتویات آن را در پوشه‌ای ذخیره کنید.

دریافت فایل

 

گام ۲: افزودن SDK تپسل به کتابخانه B4A

فایل‌های TapsellSDK.jar و TapsellSDK.xml را از SDK تپسل به پوشه‌ی Libraries در محل نصب B4A اضافه کنید. پروژه B4A خود را باز کنید و در بخش Libraries Manager، کلیک راست کرده و گزینه Refresh را انتخاب کنید تا فهرست به‌روزرسانی شود. سپس کتابخانه‌ی تپسل را از لیست پیدا کرده و آن را به پروژه خود اضافه کنید.

B4A

 

گام ۳: افزودن فایل فونت

فایل bkoodb.ttf موجود در پوشه assets از SDK تپسل را در پوشه‌ی Files در محل قرارگیری پروژه B4A خود کپی کنید. سپس در نرم‌افزار B4A در بخش Files Manager کلیک راست کرده و گزینه Sync Folder را انتخاب کنید. پس از نمایش فایل فونت کپی شده در فهرست، تیک مربوط به آن را بزنید تا به پروژه افزوده شود.

B4A

 

گام ۴: اضافه کردن کتابخانه‌های مورد نیاز

اگر قبلا برای پروژه های خود محل Additional Libraries را تعیین کرده اید لازم هست محتویات پوشه‌ی libs از SDK تپسل را در آدرسی که در Tools->Configure Paths->Additional Libraries تعیین کرده‌اید کپی کنید. در غیر اینصورت پوشه‌ی libs را در محل پروژه‌ی B4A خود و در کنار پوشه‌های Files و Objects کپی کنید.

B4A

سپس این پوشه را به عنوان پوشه‌ی Additional Libraries در پروژه خود انتخاب کنید.

B4A

 

گام ۵: تنظیمات Activity Attributes و Project Attributes

در محدوده Activity Attributes از پروژه خود، خطوط زیر را اضافه کنید.
#Region Activity Attributes
    ...
    #AdditionalJar : tapsellsdk-b4a-4.0.4.jar
    #AdditionalJar : gson-2.8.5.jar
#End Region
در صورتی که پروژه‌ی خود را در حالت debug اجرا می‌کنید خط زیر را در بخش Project Attributes فایل اصلی پروژه خود اضافه کنید:
#Region Project Attributes
    ...
    #DebuggerForceStandardAssets : true
#End Region
  B4A

 

گام ۶: آپدیت فایل Manifest

از منو Project گزینه Manifest Editor را انتخاب کرده و خطوط زیر را به manifest برنامه خود اضافه کنید.
AddManifestText(
    …
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>)
    …
'End of default text.
AddApplicationText(
    <!-- Required Activity -->
    <activity
        android:name="ir.tapsell.sdk.TapsellAdActivity"
        android:configChanges="keyboardHidden|orientation|screenSize"/>
    )
در کد فوق سترسی‌ موقعیت (ACCESS_COARSE_LOCATION) اختیاری است اما درصورتیکه این دسترسی را نیز در برنامه خود قرار دهید، تبلیغات نشان‌داده‌شده به کاربر از کیفیت بالاتری برخوردار خواهد بود.

B4A

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

پیاده‌سازی تبلیغات ویدئویی (جایزه دار-بینابینی) و تبلیغات بنری تمام صفحه در پروژه B4A

گام ۱: دریافت کلید تپسل

ابتدا وارد پنل مدیریت تپسل شده و با تعریف یک اپلیکیشن جدید با عنوان پکیج اپلیکیشن اندرویدی خود، یک کلید تپسل دریافت کنید.

 

گام ۲: شروع کار با SDK تپسل

برای ارتباط با کتابخانه‌ی تپ‌سل باید از کلاس Tapsell استفاده کنید. کافیست یک شیء از آن داشته باشید. این دسترسیبا نوشتن خط زیر در بخش Globals قابل انجام است:
Sub Globals
 Private tapsell As Tapsell
End Sub
 

سپس در activity اصلی برنامه‌ی خود در قسمت Activity_Create خط زیر را اضافه کنید:

tapsell.initialize(appKey)

ورودی appKey کلید تپسلی است که در گام قبل از پنل تپسل دریافت کردید.

 

گام ۳: دریافت تبلیغ

نمایش یک تبلیغ ویدئویی در اپلیکیشن به دو صورت ممکن است صورت پذیرد. یک روش، نمایش تبلیغ بصورت stream می‌باشد. در این حالت، همزمان که کاربر درحال مشاهده بخشی از تبلیغ است، ادامه آن از اینترنت لود می‌گردد. ممکن است به دلیل کندی سرعت اینترنت، در این حالت کاربر با مکث‌های متعددی در هنگام دریافت و مشاهده تبلیغ مواجه شود. برای اینکه کاربر در هنگام نمایش تبلیغ منتظر نماند و تجربه کاربر در استفاده از اپلیکیشن بهبود یابد،روش دیگری نیز در SDK تپسل تعبیه شده است که در آن ابتدا فایل ویدئوی تبلیغاتی بطور کامل بارگذاری شده و سپس تبلیغ نمایش داده می‌شود.

همچنین در تپسل، تبلیغ می تواند در ناحیه‌های مختلفی از برنامه شما (مانند فروشگاه، انتهای هر مرحله، ابتدای مرحله جهت دریافت امتیاز دوبرابر، دریافت بنزین/لایف و ...) پخش شود. در تپسل به این ناحیه‌ها zone گفته می شود. ناحیه‌های هر اپلیکیشن در پنل تپسل تعریف می شوند.

با اجرای تابع زیر، می‌توانید یک درخواست تبلیغ به تپسل ارسال کرده و یک تبلیغ دریافت نمایید:

tapsell.requestAd(zoneId,isCached)

 

هر درخواست شامل یک ورودی zoneId است که برای استفاده از ناحیه پیش فرض می توانید از یک رشته خالی استفاده نمایید. اطلاعات بیشتر درباره نواحی نمایش تبلیغ را می توانید از تیم فنی تپسل دریافت کنید. ورودی isCached یک متغیر Boolean می‌باشد که نشان می‌دهد که آیا تبلیغ باید ابتدا دانلود شده و سپس به کاربر نشان داده شود یا خیر.

[ht_message mstyle="danger" title="کش کردن ویدئو" " show_icon="" id="" class="" style="" ]تنها در ناحیه‌هایی که کاربر با احتمال زیادی پس از باز کردن اپلیکیشن تبلیغ آن را مشاهده می‌کند، از تبلیغ Cached استفاده کنید. جهت توضیحات بیشتر درباره روش انتخاب متد دریافت مناسب، اینجا را مطالعه کنید.[/ht_message]

نتیجه درخواست بصورت Event به یک Sub در برنامه شما بازگردانده می‌شود. در صورت وجود یک تبلیغ، شناسه آن تبلیغ به یک ساب‌روتین (Sub) با نام Tapsell_onAdAvailable در کد شما داده می‌شود و می‌بایست آن را جهت نمایش تبلیغ ذخیره نمایید. در گام بعدی همه روتین‌های مورد استفاده در تپسل آورده و توضیح داده شده‌اند.

 

گام ۴: اضافه کردن Sub های دریافت نتیجه درخواست تبلیغ

در Activity پروژه خطوط زیر را اضافه کنید:
Sub Tapsell_onAdAvailable (zoneId As String, adId As String)
    ' ad is available to show, store adId to show it later
    ad = adId
End Sub

Sub Tapsell_onNoAdAvailable (zoneId As String) ' No ad available now End Sub

Sub Tapsell_onNoNetwork (zoneId As String) ' No network End Sub

Sub Tapsell_onError (zoneId As String, error As String) ' Encountered and error while connecting to tapsell End Sub

Sub Tapsell_onExpiring (zoneId As String, adId As String) ' The stored ad with given adId is expiring and cannot be shown anymore ad = Null End Sub

Sub Tapsell_onOpened (zoneId As String, adId As String) ' The ad is being opened (shown) End Sub

Sub Tapsell_onClosed (zoneId As String, adId As String) ' The ad is being closed and ad show has finished, returning to user's Activity End Sub

توضیحات روتین‌های مختلف و شرایط اجرا شدن آن‌ها در جدول ۱ آمده است.

 

جدول ۱ Sub های مربوط به دریافت نتیجه درخواست تبلیغ
تابع توضیحات (زمان اجرا)
Tapsell_onError (String) هنگامی که هر نوع خطایی در پروسه‌ی دریافت تبلیغ بوجود بیاید
Tapsell_onAdAvailable (String, String) زمانی که تبلیغ دریافت شده و آماده‌ی نمایش باشد.
Tapsell_onNoAdAvailable (String) در صورتی که تبلیغی برای نمایش وجود نداشته باشد.
Tapsell_onNoNetwork (String) زمانی که دسترسی به شبکه موجود نباشد.
Tapsell_onExpiring (String, String) زمانی که تبلیغ منقضی شود. هر تبلیغ مدت زمان مشخصی معتبر است و در صورتی که تا قبل از آن نمایش داده نشود منقضی شده و دیگر قابل نمایش نخواهد بود.
Tapsell_onOpened (String, String) زمانی که تبلیغ شروع به پخش شود.
Tapsell_onClosed (String, String) زمانی که پخش تبلیغ تمام شود و کاربر به اکتیویتی برنامه/بازی باز می گردد.
 

گام ۵: نمایش تبلیغ

جهت نمایش تبلیغ، می‌توانید از تابع زیر استفاده نمایید (این تابع حداکثر یک بار برای هر شناسه تبلیغ قابل اجراست) :
tapsell.showAd(adId,back_disabled,immersive_mode,rotation_mode,show_dialog)
 

ورودی adId شناسه تبلیغ است که در گام قبل و در روتین Tapsell_onAdAvailable به شما داده شده‌است. ورودی‌های disable_back و immersive_mode از نوع Boolean هستند که جهت قفل کردن کلید back گوشی در هنگام نمایش تبلیغ جایزه‌دار و همینطور نمایش تبلیغ در حالت Immersive Mode (عدم نمایش دکمه‌های روی اسکرین و نمایش ویدئو بصورت Fullscreen در اندروید 4.4 و بالاتر) بکار می‌روند. ورودی show_dialog نیز یک متغیر Boolean است که در صورتی که مقدار آن برابر True باشد، در هنگام زدن دکمه Back در زمان نمایش ویدئو جایزه‌دار، یک اخطار به کاربر نشان داده می‌شود. ورودی rotation_mode برای تعیین جهت‌ نمایش ویدئو در دستگاه ( Orientation ) بکار می‌رود و مقادیر مختلف قابل استفاده برای آن در جدول ۲ آمده است.

 

جدول ۲ مقادیر قابل استفاده برای rotation_mode
مقدار توضیحات
tapsell.ROTATION_LOCKED_PORTRAIT
نمایش ویدئو در حالت Portrait
tapsell.ROTATION_LOCKED_LANDSCAPE
نمایش ویدئو در حالت Landscape
tapsell.ROTATION_UNLOCKED
تعدم قفل کردن چرخش گوشی
tapsell.ROTATION_LOCKED_REVERSED_PORTRAIT
نمایش ویدئو در حالت Reversed Portrait
tapsell.ROTATION_LOCKED_REVERSED_LANDSCAPE
نمایش ویدئو در حالت Reversed Landscape
 

گام ۶: دریافت نتیجه نمایش تبلیغ

نتیجه نمایش تبلیغ، در یک Sub با نام Tapsell_onAdShowFinished در Activity به شما برگردانده می‌شود. لذا باید این Sub را به کد خود اضافه کنید.
Sub Tapsell_onAdShowFinished (zoneId As String, adId As String, completed As Boolean, rewarded As Boolean)
    ' showing ad was finished
End Sub
در نتیجه‌ی دریافت شده، adId و zoneId شناسه مربوط به تبلیغ و محل نمایش آن در اپلیکیشن است. دو متغیر completed و rewarded از نوع Boolean بوده و نشان دهنده‌ی این است که کاربر ویدئو را تا انتها مشاهده کرده است یا خیر و تبلیغ نمایش داده شده از نوع جایزه‌دار بوده است یا خیر. در صورتی که کاربر تبلیغی از نوع جایزه دار را تا انتها مشاهده کند و هردو مقدار completed و rewarded برابر با True باشند، ، باید جایزه درون برنامه (سکه، اعتبار، بنزین یا ...) را به کاربر بدهید.

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

گام ۱: دریافت کلید تپسل

ابتدا وارد پنل مدیریت تپسل شده و با تعریف یک اپلیکیشن جدید با عنوان پکیج اپلیکیشن اندرویدی خود، یک کلید تپسل دریافت کنید.

 

گام ۲: شروع کار با SDK تپسل

برای ارتباط با کتابخانه‌ی تپ‌سل باید از کلاس Tapsell استفاده کنید. کافیست یک شیء از آن داشته باشید. این دسترسیبا نوشتن خط زیر در بخش Globals قابل انجام است:
Sub Globals
 Private tapsell As Tapsell
End Sub
 

سپس در activity اصلی برنامه‌ی خود در قسمت Activity_Create خط زیر را اضافه کنید:

tapsell.initialize(appKey)

ورودی appKey کلید تپسلی است که در گام قبل از پنل تپسل دریافت کردید.

 

گام ۳: نمایش تبلیغ بنری استاندارد

جهت نمایش بنر استاندارد، باید محلی برای نمایش آن در صفحه در نظر بگیرید. بنر استاندارد، دارای سایزهای استانداردی است که در SDK تپسل مشخص شده اند. جهت نمایش بنر، از تابع زیر استفاده کنید:
tapsell.fillBannerAd(adPanel, zoneId, bannerSize)
 

ورودی adPanel از جنس Panel بوده و نشان دهنده محلی است که برای نمایش تبلیغ انتخاب کرده‌اید. پارامترzoneId شناسه تبلیغ‌گاه بنر استاندارد است که آن را می‌توانید از داشبورد تپسل دریافت کنید. ورودی آخر، نوع بنر را مشخص می‌کند. مقادیر قابل قبول انواع بنر، در کلاس Tapsell بصورت tapsell.BANNER_WxH آورده شده‌اند که W و H به ترتیب عرض و طول بنر استاندارد هستند.

 

گام ۴: تنظیم Callback

اگر میخواهید callback های مربوط به نمایش بنر را مدیریت کنید میتوانید از قطعه کد زیر استفاده کنید:
Sub Tapsell_onNoBannerAdAvailable (zoneId As String)
    //Todo
End Sub

Sub Tapsell_onBannerNoNetwork (zoneId As String) //Todo End Sub

Sub Tapsell_onBannerAdRequestFilled (zoneId As String) //Todo End Sub

Sub Tapsell_onBannerAdMadeHidden (zoneId As String) //Todo End Sub

Sub Tapsell_onBannerAdError (zoneId As String, error As String) /Todo End Sub

گام ۵: مخفی کردن و نمایش بنر

به صورت پیش فرض زمانی که تبلیغات بنری دریافت میشود به صفحه اضافه میگردد و Visible می شود. اگر بنا به هر دلیلی میخواهید بنر را مخفی کنید یا بنر مخفی شده را نمایش دهید از این کد استفاده کنید:

پیاده‌سازی تبلیغات بنری هم‌نما (Native Banner) در پروژه B4A

گام ۱: دریافت کلید تپسل

ابتدا وارد پنل مدیریت تپسل شده و با تعریف یک اپلیکیشن جدید با عنوان پکیج اپلیکیشن اندرویدی خود، یک کلید تپسل دریافت کنید.

 

گام ۲: شروع کار با SDK تپسل

برای ارتباط با کتابخانه‌ی تپ‌سل باید از کلاس Tapsell استفاده کنید. کافیست یک شیء از آن داشته باشید. این دسترسیبا نوشتن خط زیر در بخش Globals قابل انجام است:
Sub Globals
 Private tapsell As Tapsell
End Sub
 

سپس در activity اصلی برنامه‌ی خود در قسمت Activity_Create خط زیر را اضافه کنید:

tapsell.initialize(appKey)

ورودی appKey کلید تپسلی است که در گام قبل از پنل تپسل دریافت کردید.

 

گام ۳: ایجاد Layout تبلیغ هم‌نما

در تبلیغات هم‌نما، شما قادر هستید ویژگی‌های ظاهری هر یک از اجزای تبلیغ (اندازه، محل قرارگیری، رنگ فونت و…) را بصورتی که هماهنگ با محتوای اپلیکیشن شما باشد تعیین کنید. لذا باید Layout هم‌نما اپلیکیشن خود را که مدنظرتان است ایجاد نموده و از آن برای نمایش تبلیغ استفاده نمایید. این Layout می‌تواند شامل یک لوگو، یک عنوان، توضیحات، یک نشانگر آگهی بودن، یک بنر و یک دکمه برای دعوت از کاربر به انجام عمل تبلیغ باشد. جهت نمایش تبلیغ باید این اجزا را به SDK تپسل بدهید تا تبلیغ را در آن نمایش دهد.

جهت ایجاد Layout تبلیغ هم‌نما می‌توانید از Designer استفاده کرده و یک قالب مانند زیر آماده کنید.

 

گام ۴: درخواست تبلیغ بنری هم‌نما

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

با اجرای تابع زیر، می‌توانید یک درخواست تبلیغ به تپسل ارسال کرده و یک تبلیغ دریافت نمایید:

tapsell.requestNativeBannerAd(zoneId)

 

هر درخواست شامل یک ورودی شناسه تبلیغ‌گاه (zoneId) است که نشانگر محل نمایش تبلیغ در اپلیکیشن شماست. تبلیغ‌گاه مرتبط با این شناسه در داشبورد تپسل باید از نوع بنری هم‌نما باشد.

نتیجه درخواست بصورت Event به یک Sub در برنامه شما بازگردانده می‌شود. در صورت وجود یک تبلیغ، شناسه آن تبلیغ به یک ساب‌روتین (Sub) با نام Tapsell_onNativeBannerAdAvailable در کد شما داده می‌شود و می‌بایست آن را جهت نمایش تبلیغ ذخیره نمایید. در گام بعدی همه روتین‌های مورد استفاده در تپسل آورده و توضیح داده شده‌اند.

 

گام ۵: اضافه کردن روتین‌های دریافت نتیجه درخواست تبلیغ

در Activity اصلی خود خطوط زیر را اضافه کنید:
Sub Tapsell_onNativeBannerAdAvailable (zoneId As String, adId As String)
    ' Native ad is available and ready to show
    ad = adId
End Sub

Sub Tapsell_onNoNativeBannerAdAvailable (zoneId As String) ' No ad available now End Sub

Sub Tapsell_onNoNetwork (zoneId As String) ' No network End Sub

Sub Tapsell_onError (zoneId As String, error As String) ' Encountered and error while connecting to tapsell End Sub

توضیحات روتین‌های مختلف و شرایط اجرا شدن آن‌ها در جدول ۱ آمده است.

 

جدول ۱ روتین‌های مربوط به دریافت نتیجه درخواست تبلیغ هم‌نما
تابع توضیحات (زمان اجرا)
Tapsell_onError (String) هنگامی که هر نوع خطایی در پروسه‌ی دریافت تبلیغ بوجود بیاید
Tapsell_onNativeBannerAdAvailable (String, String) زمانی که تبلیغ دریافت شده و آماده‌ی نمایش باشد.
Tapsell_onNoNativeBannerAdAvailable (String) در صورتی که تبلیغی برای نمایش وجود نداشته باشد.
Tapsell_onNoNetwork (String) زمانی که دسترسی به شبکه موجود نباشد.
 

گام ۶: نمایش تبلیغ

جهت نمایش تبلیغ، می‌توانید از تابع زیر استفاده نمایید (این تابع حداکثر یک بار برای هر شناسه تبلیغ قابل اجراست) :
tapsell.fillNativeBannerAd(adId,lblTitle,lblDescription,ivBanner,ivLogo,btnCallToAction,lblSponsored,adContainer)
 

ورودی adId شناسه تبلیغ است که در گام قبل و در روتین Tapsell_onNativeBannerAdAvailable به شما داده شده‌است. ورودی‌های بعدی از نوع ImageView، Label، Panel و یا Button هستند که به ترتیب نشانگر عنوان تبلیغ، توضیحات تبلیغ، پنل نمایش ویدئو، لوگو، دکمه دعوت از کاربر و نشانگر آگهی بودن می‌باشند. آخرین ورودی نیز Panel دربرگیرنده تبلیغ هست که اختیاری بوده و می‌تواند Null باشد. برای نمایش تبلیغ حتما باید عنوان و یکی از دو مورد دکمه دعوت از کاربر و Panel دربرگیرنده به SDK ارسال شوند.

 

پیاده‌سازی تبلیغات ویدئویی هم‌نما (Native Video) در پروژه B4A

گام ۱: دریافت کلید تپسل

ابتدا وارد پنل مدیریت تپسل شده و با تعریف یک اپلیکیشن جدید با عنوان پکیج اپلیکیشن اندرویدی خود، یک کلید تپسل دریافت کنید.

 

گام ۲: شروع کار با SDK تپسل

برای ارتباط با کتابخانه‌ی تپ‌سل باید از کلاس Tapsell استفاده کنید. کافیست یک شیء از آن داشته باشید. این دسترسیبا نوشتن خط زیر در بخش Globals قابل انجام است:
Sub Globals
 Private tapsell As Tapsell
End Sub
 

سپس در activity اصلی برنامه‌ی خود در قسمت Activity_Create خط زیر را اضافه کنید:

tapsell.initialize(appKey)

ورودی appKey کلید تپسلی است که در گام قبل از پنل تپسل دریافت کردید.

 

گام ۳: ایجاد Layout تبلیغ هم‌نما

در تبلیغات هم‌نما، شما قادر هستید ویژگی‌های ظاهری هر یک از اجزای تبلیغ (اندازه، محل قرارگیری، رنگ فونت و…) را بصورتی که هماهنگ با محتوای اپلیکیشن شما باشد تعیین کنید. لذا باید Layout هم‌نما اپلیکیشن خود را که مدنظرتان است ایجاد نموده و از آن برای نمایش تبلیغ استفاده نمایید. این Layout می‌تواند شامل یک لوگو، یک عنوان، توضیحات، یک نشانگر آگهی بودن، یک بنر و یک دکمه برای دعوت از کاربر به انجام عمل تبلیغ باشد. جهت نمایش تبلیغ باید این اجزا را به SDK تپسل بدهید تا تبلیغ را در آن نمایش دهد.

جهت ایجاد Layout تبلیغ هم‌نما می‌توانید از Designer استفاده کرده و یک قالب مانند زیر آماده کنید.

 

گام ۴: درخواست تبلیغ ویدئویی هم‌نما

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

با اجرای تابع زیر، می‌توانید یک درخواست تبلیغ به تپسل ارسال کرده و یک تبلیغ دریافت نمایید:

tapsell.requestNativeVideoAd(zoneId)

 

هر درخواست شامل یک ورودی شناسه تبلیغ‌گاه (zoneId) است که نشانگر محل نمایش تبلیغ در اپلیکیشن شماست. تبلیغ‌گاه مرتبط با این شناسه در داشبورد تپسل باید از نوع بنری هم‌نما باشد.

نتیجه درخواست بصورت Event به یک Sub در برنامه شما بازگردانده می‌شود. در صورت وجود یک تبلیغ، شناسه آن تبلیغ به یک ساب‌روتین (Sub) با نام Tapsell_onNativeBannerAdAvailable در کد شما داده می‌شود و می‌بایست آن را جهت نمایش تبلیغ ذخیره نمایید. در گام بعدی همه روتین‌های مورد استفاده در تپسل آورده و توضیح داده شده‌اند.

 

گام ۵: اضافه کردن روتین‌های دریافت نتیجه درخواست تبلیغ

در Activity اصلی خود خطوط زیر را اضافه کنید:
Sub Tapsell_onNativeVideoAdAvailable (zoneId As String, adId As String)
    ' Native ad is available and ready to show
    ad = adId
End Sub

Sub Tapsell_onNoNativeVideoAdAvailable (zoneId As String) ' No ad available now End Sub

Sub Tapsell_onNoNetwork (zoneId As String) ' No network End Sub

Sub Tapsell_onError (zoneId As String, error As String) ' Encountered and error while connecting to tapsell End Sub

توضیحات روتین‌های مختلف و شرایط اجرا شدن آن‌ها در جدول ۱ آمده است.

 

جدول ۱ روتین‌های مربوط به دریافت نتیجه درخواست تبلیغ هم‌نما
تابع توضیحات (زمان اجرا)
Tapsell_onError (String) هنگامی که هر نوع خطایی در پروسه‌ی دریافت تبلیغ بوجود بیاید
Tapsell_onNativeVideoAdAvailable (String, String) زمانی که تبلیغ دریافت شده و آماده‌ی نمایش باشد.
Tapsell_onNoNativeVideoAdAvailable (String) در صورتی که تبلیغی برای نمایش وجود نداشته باشد.
Tapsell_onNoNetwork (String) زمانی که دسترسی به شبکه موجود نباشد.
 

گام ۶: نمایش تبلیغ

جهت نمایش تبلیغ، می‌توانید از تابع زیر استفاده نمایید (این تابع حداکثر یک بار برای هر شناسه تبلیغ قابل اجراست) :
tapsell.fillNativeVideoAd(adId,autoStartVideo,fullscreenOnClick,lblTitle,lblDescription,pVideoContainer,ivLogo,btnCallToAction,lblSponsored,adContainer)
 

ورودی adId شناسه تبلیغ است که در گام قبل و در روتین Tapsell_onNativeBannerAdAvailable به شما داده شده‌است. ورودی های autoStartVideo و fullscreenOnClick از نوع Boolean هستند. autoStartVideo مشخص کننده این است که ویدئو بعد از لود شدن در صفحه بصورت اتوماتیک اجرا شود یا خیر. همچنین fullscreenOnClick تعیین کننده این است که آیا زمان کلیک کردن کاربر روی ویدئو باید ویدئو بصورت تمام صفحه نمایش داده شود یا خیر. ورودی‌های بعدی از نوع ImageView، Label، Panel و یا Button هستند که به ترتیب نشانگر عنوان تبلیغ، توضیحات تبلیغ، پنل نمایش ویدئو، لوگو، دکمه دعوت از کاربر و نشانگر آگهی بودن می‌باشند. آخرین ورودی نیز Panel دربرگیرنده تبلیغ هست که اختیاری بوده و می‌تواند Null باشد. برای نمایش تبلیغ حتما باید عنوان و یکی از دو مورد دکمه دعوت از کاربر و Panel دربرگیرنده به SDK ارسال شوند.

موارد پیشرفته‌تر در SDK

 

بررسی وجود تبلیغ دریافت شده

در صورتیکه در SDK برای یک ناحیه درخواست دریافت تبلیغ از سرور انجام داده باشید، علاوه بر action داده شده در تابع requestAd، می‌توانید از تابع زیر نیز برای چک کردن وجود تبلیغ دریافت شده استفاده کنید.
tapsell.isAdReadyToShow(zoneId As String)
ورودی zoneId در این تابع، شناسه ناحیه نمایش تبلیغ است که از پنل تپسل دریافت نموده‌اید.

 

دریافت نسخه SDK تپسل

درصورتی که نیازمند به دانستن نسخه تپسل پیاده‌سازی شده در اپلیکیشن خود هستید، می‌توانید با فراخوانی تابع زیر عنوان نسخه را دریافت نمایید.
tapsell.Version
 

تنظیمات کشینگ

همانطور که در بخش پیاده‌سازی SDK تپسل در اپلیکیشن گفته شد، از نسخه ۳ به بعد تپسل قابلیت نمایش ویدئو بصورت استریم و همینطور نمایش ویدئو بعد از دانلود فایل (کشینگ) را دارد. با این قابلیت، قبل از نمایش تبلیغ و در هنگامی که کاربر مشغول استفاده از اپلیکیشن است، ویدئو بطور کامل دریافت می‌شود و کاربر بدون هیچگونه مکثی می‌تواند ویدئو را تماشا کند.

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

جهت جلوگیری از اشغال پهنای باند زیاد توسط تپسل، شما می‌توانید درصد مشخصی از کل پهنای باند موجود را به دانلود ویدئو اختصاص دهید. جهت انجام این عمل، تابع زیر را در آغاز برنامه و تابع initialize (قبل از درخواست تبلیغ) فراخوانی کنید.

tapsell.MaxAllowedBandwidthUsagePercentage  = maxPercentage

که ورودی maxPercentage حداکثر درصدی از پهنای باند در دسترس اپلیکیشن است که SDK تپسل از آن برای دریافت ویدئو استفاده می‌کند. این پارامتر باید عددی بین 0 تا 100 باشد.

همچنین درصورتی که از سرعت دانلود واقعی کاربر در اپلیکیشن خود اطلاع دارید می‌توانید به کمک تابع زیر، مقدار حداکثر پهنای باند قابل استفاده برای دانلود ویدئو را به کمک تابع زیر تنظیم کنید.

tapsell.MaxAllowedBandwidthUsage = maxBpsSpeed

ورودی دوم این تابع، میزان حداکثر سرعت دانلود ویدئو است که باید به واحد بایت بر ثانیه داده شود.

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

tapsell.clearBandwidthUsageConstrains()

 

توضیحات بیشتر درباره کشینگ و استریمینگ در SDK تپسل را اینجا بخوانید.

 

تنظیمات دسترسی‌های زمان اجرا (Run Time Permissions)

از نسخه اندروید 6 و بالاتر، برخی دسترسی‌ها در اندروید در زمان اجرا باید از کاربر درخواست شوند. یکی از این دسترسی‌ها، دسترسی READ_PHONE_STATE است که توسط تپسل استفاده می‌شود و بدون این دسترسی، SDK تپسل قابل استفاده نیست. برای سهولت پیاده‌سازی، SDK تپسل بصورت اتوماتیک دسترسی‌ها را از کاربر درخواست می‌کند و هربار درخواست تبلیغی ارسال شود، درصورتی که دسترسی مورد نیاز موجود نباشد، این دسترسی از کاربر خواسته می شود.

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

tapsell.AutoHandlePermissions = true

با این دستور، درخواست دسترسی توسط SDK تپسل به کاربر نشان داده نمی‌شود و می‌توانید بصورت مطلوب خود آن را پیاده‌سازی نمایید.

 

حالت دیباگ (Debug Mode)

در هنگام پیاده‌سازی SDK، ممکن است بدلیل عدم رعایت نکات گفته شده و یا خطاهای دیگر، تبلیغات قابل دریافت و نمایش نباشند. حالت دیباگ جهت تسهیل فرآیند عیب‌یابی در هنگام پیاده‌سازی تعبیه شده است. با فعالسازی این حالت، می‌توانید گزارش‌های لاگ نمایش داده شده توسط SDK را در logcat مشاهده کنید. برای فعالسازی حالت دیباگ کافیست از تابع زیر در آغاز برنامه استفاده کنید.
tapsell.DebugMode =true
سپس با استفاده از نرم‌افزار Android Studio، از بخش Android Monitor، قسمت logcat را باز کرده و لاگ‌های نوشته شده را بررسی کنید. برای مشاهده لاگ‌های برنامه unity، در بخش فیلتر کلمه unity را وارد کنید.