(نسخه پلاگین: ۳.۰.۴۵ – نسخه اندروید: ۳.۰.۳۶ – نسخه iOS: ـ۳.۰.۵ ) توجه پلاگین تپسل، در نسخههای ۳.۰.۰ و بالاتر cordova قابل استفاده است. اگر نسخه cordova شما خارج از این محدوده باشد، امکان استفاده از این پلاگین را نخواهید داشت.نسخه کتابخانه اندروید مورد نیاز جهت استفاده از SDK تپسل میبایست از build tools نسخه 23 و بالاتر استفاده کنید. فهرست مطالب مستندات راهاندازی تبلیغات تپسل در Cordova
- پیادهسازی تبلیغات ویدئویی (Interstitial/Rewarded Video) و بنری تمام صفحه (Interstitial Banner) در پروژه Cordova
- پیادهسازی تبلیغات بنری استاندارد در پروژه Cordova
- موارد پیشرفتهتر در SDK
- پروژه نمونه
پیادهسازی تبلیغات ویدئویی (Interstitial/Rewarded Video) و بنری تمام صفحه (Interstitial Banner) در پروژه Cordova
ابتدا command prompt را باز کرده و به پوشه مربوط به پروژه خود بروید. سپس دستور زیر را در آن اجرا کنید. گام ۱: افزودن پلاگین تپسل به پروژه cordova
cordova plugin add tapsell-v3-cordova-pluginبا انجام این دستور، پلاگین تپسل در پروژه شما افزوده میگردد.
وارد پنل مدیریت تپسل شده و با تعریف یک اپلیکیشن جدید با عنوان پکیج اپلیکیشن اندرویدی خود، یک کلید تپسل دریافت کنید. گام ۲: دریافت کلید تپسل
در گام دوم با ثبت برنامه خود در پنل تپسل، یک عبارت با عنوان کلید تپسل در اختیار شما قرار میگیر. برای استفاده از تپسل ابتدا باید این کلید را به برنامه خود معرفی نمایید. لذا در بخش onDeviceReady فایل javascript خود، تابع زیر را با کلید تپسل برنامه خود فراخوانی نمایید. گام ۳: شروع کار با SDK تپسل
tapsell.initialize(appKey);ورودی
appKey
کلید تپسلی است که در گام قبل از پنل تپسل دریافت کردید.
نمایش یک تبلیغ ویدئویی در اپلیکیشن به دو صورت ممکن است صورت پذیرد. یک روش، نمایش تبلیغ بصورت استریم می باشد. در این حالت، همزمان که کاربر درحال مشاهده بخشی از تبلیغ است، ادامه آن از اینترنت لود می گردد. ممکن است به دلیل کندی سرعت اینترنت، در این حالت کاربر با مکث های متعددی در هنگام دریافت و مشاهده تبلیغ مواجه شود. برای اینکه کاربر در هنگام نمایش تبلیغ منتظر نماند و تجربه کاربر در استفاده از اپلیکیشن بهبود یابد،روش دیگری نیز در SDK تپسل تعبیه شده است که در آن ابتدا فایل ویدئوی تبلیغاتی بطور کامل بارگذاری شده و سپس تبلیغ نمایش داده می شود. همچنین در تپسل، تبلیغ می تواند در ناحیههای مختلفی از برنامه شما (مانند فروشگاه، انتهای هر مرحله، ابتدای مرحله جهت دریافت امتیاز دوبرابر، دریافت بنزین/لایف و ...) پخش شود. در تپسل به این ناحیهها گام ۴: دریافت تبلیغ
zone
گفته می شود. ناحیههای هر اپلیکیشن در پنل تپسل تعریف می شوند. با اجرای تابع زیر، می توانید یک درخواست تبلیغ به تپسل ارسال
کرده و یک تبلیغ دریافت نمایید:
tapsell.requestAd(zoneId, cached, function(result){ if(result['action']=='onAdAvailable') { zoneId = result['zoneId']; adId = result['adId']; // store this to show the ad later } else if( result['action']=='onNoAdAvailable' ) { zoneId = result['zoneId']; } else if( result['action']=='onNoNetwork' ) { zoneId = result['zoneId']; } else if( result['action']=='onError' ) { zoneId = result['zoneId']; error = result['error']; // description of error } else if(result['action']=='onExpiring') { zoneId = result['zoneId']; adId = result['adId']; // indicates that this ad cannot be shown anymore, you should // request a new add } });هر درخواست شامل یک ورودی
zoneId
است که برای استفاده از
zone
پیش فرض می توانید از مقدار
null
و یا یک رشته خالی استفاده نمایید. اطلاعات بیشتر درباره zone را می توانید از تیم فنی تپسل دریافت کنید. ورودی cached یک متغیر
bool (با مقدار True/False) می باشد که نشان می دهد که آیا تبلیغ باید ابتدا دانلود شده و سپس به کاربر نشان داده شود یا خیر.
کش کردن ویدئو تنها در ناحیههایی که کاربر با
احتمال زیادی پس از باز کردن اپلیکیشن تبلیغ آن را مشاهده میکند، از تبلیغ Cached استفاده کنید. جهت توضیحات بیشتر درباره روش
انتخاب متد دریافت مناسب،
اینجا را مطالعه کنید. تابع داده شده به عنوان
callback
نتیجه درخواست تبلیغ را در
result
به شما برمیگرداند. نتیجه درخواست در این متغیر و با کلید
action
آمده است. همانطور که در کد فوق ملاحظه میکنید، در صورتیکه
action
برگردانده شده برابر با
onAdAvailable
باشد، میبایست شناسه تبلیغ (
adId
) را برای نمایش آن ذخیره کنید. در صورتی که
action
بازگردانده شده
onExpiring
باشد، بدین معناست که تبلیغ دریافت شده دیگر معتبر نیست و زمان زیادی از دریافت آن گذشته است و میبایست یک تبلیغ جدید از تپسل
دریافت نمایید. توضیحات مقادیر مختلف متناظر با کلید
action
و شرایط اجرا شدن آنها در ادامه در جدول ۱ آمده است.
آرگومان action (سایر پارامترها) | توضیحات (زمان اجرا) |
---|---|
onError (zoneId, error) | هنگامی که هر نوع خطایی در پروسهی دریافت تبلیغ بوجود بیاید |
onAdAvailable (zoneId, adId) | زمانی که تبلیغ دریافت شده و آمادهی نمایش باشد. |
onNoAdAvailable (zoneId) | در صورتی که تبلیغی برای نمایش وجود نداشته باشد. |
onNoNetwork (zoneId) | زمانی که دسترسی به شبکه موجود نباشد. |
onExpiring (zoneId, adId) | زمانی که تبلیغ منقضی شود. هر تبلیغ مدت زمان مشخصی معتبر است و در صورتی که تا قبل از آن نمایش داده نشود منقضی شده و دیگر قابل نمایش نخواهد بود. |
جهت نمایش تبلیغ، نیاز به شناسه یک تبلیغ دارید که پس از فراخوانی گام ۵: نمایش تبلیغ
tapsell.requestAd
دریافت میکنید. جهت نمایش تبلیغ، از تابع زیر استفاده نمایید. (این تابع حداکثر یک بار برای هر شناسه تبلیغ قابل اجراست):
tapsell.showAd(adId, disable_back, immersive_mode, rotation_mode , show_dialog, function(result){ if(result['action']=='onOpened') { zoneId = result['zoneId']; adId = result['adId']; // id of the found ad console.log('tapsell onOpened'); } else if(result['action']=='onClosed') { zoneId = result['zoneId']; adId = result['adId']; // id of the found ad console.log('tapsell onClosed'); } } );ورودی
adId
شناسه تبلیغ است که پس از درخواست تبلیغ آن را دریافت نمودید. ورودیهای
disable_back
و
immersive_mode
از نوع
boolean
هستند که جهت قفل کردن کلید back گوشی در هنگام نمایش تبلیغ rewarded و همینطور نمایش تبلیغ در حالت Immersive Mode (عدم نمایش
دکمههای روی اسکرین و نمایش ویدئو بصورت تمام صفحه در اندروید 4.4 و بالاتر) بکار میروند. ورودی
show_dialog
، از نوع
boolean
است و تعیین کننده این موضوع است که آیا در تبلیغات جایزهدار، باید در زمان استفاده کاربر از دکمه back پیغام اخطار به وی نشان
داده شود یا خیر. ورودی
rotation_mode
برای تعیین جهت نمایش ویدئو در دستگاه ( Orientation ) بکار میرود و مقادیر مختلف قابل استفاده برای آن در جدول ۲ آمده است.
مقدار | توضیحات |
---|---|
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
|
جهت دریافت نتیجه نمایش تبلیغات، باید یک تابع Callback برای ارسال نتایج دریافت تبلیغ به SDK تپسل ارسال کنید. برای این کار، باید از تابع گام ۶: دریافت نتیجه نمایش تبلیغ
tapsell.setRewardCallback
استفاده نمایید.
tapsell.setRewardCallback(function (result){ if(result['action']=='onAdShowFinished') { console.log('showing ad was finished'); zoneId = result['zoneId']; adId = result['adId']; completed = result['completed']; rewarded = result['rewarded']; } });نتیجه نمایش تبلیغ در
callback
داده شده بصورت یک تابع برگردانده میشود. در نتیجه دریافت شده،
adId
و
zoneId
شناسه مربوط به تبلیغ و محل نمایش آن در اپلیکیشن است. دو متغیر
completed
و
rewarded
از نوع
boolean
بوده و نشان دهندهی این است که کاربر ویدئو را تا انتها مشاهده کرده است یا خیر و تبلیغ نمایش داده شده از نوع جایزهدار بوده
است یا خیر. در صورتی که کاربر تبلیغی از نوع جایزه دار را تا انتها مشاهده کند و هردو مقدار
completed
و
rewarded
برابر با
true
باشند، ، باید جایزه درون برنامه (سکه، اعتبار، بنزین یا ...) را به کاربر بدهید.
یک نمونه پیادهسازی تپسل در Cordova را میتوانید در repository زیر مشاهده کنید. نمونه پیادهسازی
موارد پیشرفتهتر در SDK تپسل (Cordova)
در صورتیکه در SDK برای یک ناحیه درخواست دریافت تبلیغ از سرور انجام داده باشید، علاوه بر بررسی وجود تبلیغ دریافت شده
action
داده شده در تابع
requestAd
، میتوانید از تابع زیر نیز برای چک کردن وجود تبلیغ دریافت شده استفاده کنید.
tapsell.isAdReadyToShow(zoneId, function(result){ if(result['action']=='isAdReadyToShow') { ready = result['isAdReady']; } });ورودی zoneId در این تابع، شناسه ناحیه نمایش تبلیغ است که از پنل تپسل دریافت نمودهاید.
درصورتی که نیازمند به دانستن نسخه تپسل پیادهسازی شده در اپلیکیشن خود هستید، میتوانید با فراخوانی تابع زیر عنوان نسخه را دریافت نمایید. دریافت نسخه SDK تپسل
tapsell.getVersion( function(result){ if(result['action']=='getVersion') { console.log('tapsell version: '+result['version']); } });
همانطور که در بخش تنظیمات کشینگپیادهسازی SDK تپسل در اپلیکیشن گفته شد، از نسخه ۳ به بعد تپسل قابلیت نمایش ویدئو بصورت استریم و همینطور نمایش ویدئو بعد از دانلود فایل (کشینگ) را دارد. با این قابلیت، قبل از نمایش تبلیغ و در هنگامی که کاربر مشغول استفاده از اپلیکیشن است، ویدئو بطور کامل دریافت میشود و کاربر بدون هیچگونه مکثی میتواند ویدئو را تماشا کند. از طرف دیگر، در اپلیکیشنها و بازیهای آنلاین، دریافت ویدئو در پس زمینه ممکن است در روند اصلی برنامه خلل ایجاد کند و آن را کند نماید. جهت جلوگیری از اشغال پهنای باند زیاد توسط تپسل، شما میتوانید درصد مشخصی از کل پهنای باند موجود را به دانلود ویدئو اختصاص دهید. جهت انجام این عمل، تابع زیر را در آغاز برنامه و تابع
initialize
(قبل از درخواست تبلیغ) فراخوانی کنید.
tapsell.setMaxAllowedBandwidthUsagePercentage(maxPercentage);در این تابع، ورودی
maxPercentage
حداکثر درصدی از پهنای باند در دسترس اپلیکیشن است که SDK تپسل از آن برای دریافت ویدئو استفاده میکند. این پارامتر باید عددی
بین 0 تا 100 باشد. همچنین درصورتی که از سرعت دانلود واقعی کاربر در اپلیکیشن خود اطلاع دارید میتوانید به کمک تابع زیر، مقدار
حداکثر پهنای باند قابل استفاده برای دانلود ویدئو را به کمک تابع زیر تنظیم کنید.
tapsell.setMaxAllowedBandwidthUsage(maxBpsSpeed)ورودی دوم این تابع، میزان حداکثر سرعت دانلود ویدئو است که باید به واحد بایت بر ثانیه داده شود. در صورتی که در بخشی از اپلیکیشن خود میخواهید تنظیمات مربوط به محدودیت سرعت دانلود را غیرفعال نمایید، از تابع زیر استفاده کنید.
tapsell.clearBandwidthUsageConstrains()توضیحات بیشتر درباره کشینگ و استریمینگ در SDK تپسل را اینجا بخوانید.
از نسخه اندروید 6 و بالاتر، برخی دسترسیها در اندروید در زمان اجرا باید از کاربر درخواست شوند. یکی از این دسترسیها، دسترسی تنظیمات دسترسیهای زمان اجرا (Run Time Permissions)
READ_PHONE_STATE
است که توسط تپسل استفاده میشود و بدون این دسترسی، SDK تپسل قابل استفاده نیست. برای سهولت پیادهسازی، SDK تپسل بصورت اتوماتیک
دسترسیها را از کاربر درخواست میکند و هربار درخواست تبلیغی ارسال شود، درصورتی که دسترسی مورد نیاز موجود نباشد، این دسترسی
از کاربر خواسته می شود. در صورتی که شما میخواهید درخواست دسترسیها از کاربر را به نحو دیگری در اپلیکیشن خود پیادهسازی نمایید،
میتوانید این ویژگی پیشفرض را در تپسل غیر فعال کنید. جهت انجام این عمل، کافیست از تابع زیر در زمان آغاز برنامه و بعد از
تابع
initialize
استفاده کنید.
tapsell.setAutoHandlePermissions (false);با این دستور، درخواست دسترسی توسط SDK تپسل به کاربر نشان داده نمیشود و میتوانید بصورت مطلوب خود آن را پیادهسازی نمایید.
در هنگام پیادهسازی SDK، ممکن است بدلیل عدم رعایت نکات گفته شده و یا خطاهای دیگر، تبلیغات قابل دریافت و نمایش نباشند. حالت دیباگ جهت تسهیل فرآیند عیبیابی در هنگام پیادهسازی تعبیه شده است. با فعالسازی این حالت، میتوانید گزارشهای لاگ نمایش داده شده توسط SDK را در logcat مشاهده کنید. برای فعالسازی حالت دیباگ کافیست از تابع زیر در آغاز برنامه استفاده کنید. حالت دیباگ (Debug Mode)
tapsell.setDebugMode (true);سپس با استفاده از نرمافزار Android Studio، از بخش Android Monitor، قسمت logcat را باز کرده و لاگهای نوشته شده را بررسی کنید.