1. خانه
  2. پیاده‌سازی تبلیغات ویدئویی در پروژه 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 می‌باشد که نشان می‌دهد که آیا تبلیغ باید ابتدا دانلود شده و سپس به کاربر نشان داده شود یا خیر.

کش کردن ویدئو

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

نتیجه درخواست بصورت 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 باشند، ، باید جایزه درون برنامه (سکه، اعتبار، بنزین یا …) را به کاربر بدهید.

 

 

نمونه پیاده‌سازی

یک نمونه پیاده‌سازی SDK تپسل در B4A در repository زیر آمده است.

 

 

 

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

 

 

 

بعدی: پیاده‌سازی تبلیغات بنری استاندارد در پروژه B4A
قبلی: تنظیمات پروژه B4A

آیا این این آموزش مفید بود؟