پیاده‌سازی تبلیغات ویدئویی (Interstitial/Rewarded Video) و بنری تمام صفحه (Interstitial Banner) در پروژه Cordova

 

گام ۱: افزودن پلاگین تپسل به پروژه cordova

ابتدا command prompt را باز کرده و به پوشه مربوط به پروژه خود بروید. سپس دستور زیر را در آن اجرا کنید.

 cordova plugin add tapsell-v3-cordova-plugin

با انجام این دستور، پلاگین تپسل در پروژه شما افزوده می‌گردد.  

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

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

ورود به داشبورد تپسل

 

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

در گام دوم با ثبت برنامه خود در پنل تپسل، یک عبارت با عنوان کلید تپسل در اختیار شما قرار می‌گیر. برای استفاده از تپسل ابتدا
باید این کلید را به برنامه خود معرفی نمایید. لذا در بخش onDeviceReady فایل javascript خود، تابع زیر را با کلید تپسل برنامه
خود فراخوانی نمایید.

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 ) بکار می‌رود و مقادیر مختلف قابل استفاده برای آن در جدول ۲ آمده است.
 

جدول ۲ مقادیر قابل استفاده برای 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

 

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

جهت دریافت نتیجه نمایش تبلیغات، باید یک تابع 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 زیر مشاهده کنید.

مشاهده پروژه نمونه

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

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

گام ۱: افزودن پلاگین تپسل به پروژه cordova

ابتدا command prompt را باز کرده و به پوشه مربوط به پروژه خود بروید. سپس دستور زیر را در آن اجرا کنید.

 cordova plugin add tapsell-v3-cordova-plugin

با انجام این دستور، پلاگین تپسل در پروژه شما افزوده می‌گردد.  

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

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

ورود به داشبورد تپسل

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

در گام دوم با ثبت برنامه خود در پنل تپسل، یک عبارت با عنوان کلید تپسل در اختیار شما قرار می‌گیر. برای استفاده از تپسل ابتدا
باید این کلید را به برنامه خود معرفی نمایید. لذا در بخش onDeviceReady فایل javascript خود، تابع زیر را با کلید تپسل برنامه
خود فراخوانی نمایید.

tapsell.initialize(appKey);

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

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

جهت نمایش بنر استاندارد، باید محلی برای نمایش آن در صفحه در نظر بگیرید. بنر استاندارد، دارای سایزهای استانداردی است که در
SDK تپسل مشخص شده اند. جهت نمایش بنر، از تابع زیر استفاده کنید:

tapsell.requestBannerAd(zoneId, BannerType, horizontalGravity, verticalGravity);

مقدار zoneId کلیدی ست که بعد از ساخت اپلیکیشن در پنل و ثبت یک zone از نوع بنری استاندارد دریافت میکنید.ورودی BannerType
اندازه های مختلف را بیان میکند و شامل مقادیر tapsell_banner_320x100 ,tapsell_banner_320x50 , tapsell_banner_300x250 , tapsell_banner_250x250
میباشد. ورودی horizontalGravity نشان میدهد که آیا تبلیغ، بالا یا پایین صفحه باشد و شامل tapsell_top, tapsell_bottom می باشد،
همچنین verticalGravity بیان میکند که تبلیغ از جهت عرضی در کجای صفحه باشد و میتواند شامل مقادیر tapsell_left , tapsell_right
, tapsell_center باشد. یک نمونه پیاده سازی کد به شکل زیر است:

tapsell.requestBannerAd("5a0041c8e995ee0001937574",tapsell_banner_320x50,tapsell_top,tapsell_center);

موارد پیشرفته‌تر در 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 تپسل را
اینجا بخوانید.  

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

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

tapsell.setAutoHandlePermissions (false);

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

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

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

tapsell.setDebugMode (true);

سپس با استفاده از نرم‌افزار Android Studio، از بخش Android Monitor، قسمت logcat را باز کرده و لاگ‌های نوشته شده را بررسی
کنید.