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

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

 

 

 

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

 

 

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

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

مقالات و آموزش های مرتبط