مستندات راه‌اندازی تبلیغات تپسل در Construct2

(نسخه پلاگین: ۱.۰.۳ – نسخه اندروید: ۳.۰.۳۴ – نسخه iOS: ـ۳.۰.۵ ) توجه پلاگین تپسل، در نسخه‌های ۳.۰.۰ و بالاتر cordova قابل استفاده است. اگر نسخه cordova شما خارج از این محدوده باشد، امکان استفاده از این پلاگین را نخواهید داشت. نسخه کتابخانه اندروید مورد نیاز ]جهت استفاده از SDK تپسل می‌بایست از build tools نسخه 23 و بالاتر استفاده کنید. فهرست مطالب

پیاده‌سازی تپسل در Construct 2

گام ۱: دریافت و نصب پلاگین تپسل برای Construct 2

ابتدا فایل پلاگین تپسل برای Construct 2 را از آدرس زیر را دانلود کنید.

دانلود پلاگین

نرم افزار Construct 2 را باز کرده و در پروژه خود، فایل پلاگین را داخل نرم‌افزار drag and drop کنید. با این روش پلاگین تپسل در نرم‌افزار نصب می‌شود.

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

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

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

برای شروع کار با پلاگین تپسل باید یک شی از نوع TapsellSDKv3 در پروژه خود ایجاد کنید. برای این کار در قسمت Projects کلیک راست کرده و از طریق پنجره Insert New Object این شی را ایجاد کنید.

سپس با کلیک روی شی ایجاد شده در تب Porjects، مشخصات آن در تب Properties باز می شود. در بخش appkey، کلید تپسل که در مرحله قبل دریافت نمودید را وارد نمایید. در پلاگین تپسل دو اکشن و پنج رویداد (Event) قابل استفاده هستند. این موارد در تصویر زیر قابل مشاهده هستند.

اکشن‌ها و رویدادهای فوق برای دریافت و نمایش تبلیغ استفاده می‌شوند.

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

نمایش یک تبلیغ ویدئویی در اپلیکیشن به دو صورت ممکن است صورت پذیرد. یک روش، نمایش تبلیغ بصورت stream می‌باشد. در این حالت، همزمان که کاربر درحال مشاهده بخشی از تبلیغ است، ادامه آن از اینترنت لود می‌گردد. ممکن است به دلیل کندی سرعت اینترنت، در این حالت کاربر با مکث‌های متعددی در هنگام دریافت و مشاهده تبلیغ مواجه شود. برای اینکه کاربر در هنگام نمایش تبلیغ منتظر نماند و تجربه کاربر در استفاده از اپلیکیشن بهبود یابد،روش دیگری نیز در SDK تپسل تعبیه شده است که در آن ابتدا فایل ویدئوی تبلیغاتی بطور کامل بارگذاری شده و سپس تبلیغ نمایش داده می‌شود. همچنین در تپسل، تبلیغ می تواند در ناحیه‌های مختلفی از برنامه شما (مانند فروشگاه، انتهای هر مرحله، ابتدای مرحله جهت دریافت امتیاز دوبرابر، دریافت بنزین/لایف و ...) پخش شود. در تپسل به این ناحیه‌ها zone گفته می شود. ناحیه‌های هر اپلیکیشن در پنل تپسل تعریف می شوند. جهت دریافت یک تبلیغ، باید از اکشن requestAd استفاده کنید. ورودی اول ( Caching options) تعیین کننده کش شدن/نشدن تبلیغ است. ورودی دوم ( ZoneId) شناسه تبلیغگاه مورد نظر در اپلیکیشن شماست که در داشبور تپسل در صفحه اپلیکیشن شما قابل تعریف است.

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

جدول ۱ مقادیر مختلف پارامتر Caching options در درخواست تبلیغ

مقدار	توضیحات
Cached	دریافت ویدئو و نمایش آن پس از دانلود کامل
Streamed	نمایش ویدئو بصورت برخط (stream)

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

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

تابع	توضیحات (زمان اجرا)
onError	هنگامی که هر نوع خطایی در پروسه‌ی دریافت تبلیغ برای تبلیغگاه مورد نظر بوجود بیاید
onAdAvailable	زمانی که تبلیغ برای تبلیغگاه مورد نظر دریافت شده و آماده‌ی نمایش باشد.
onNoAdAvailable	در صورتی که تبلیغی برای نمایش در تبلیغگاه مورد نظر وجود نداشته باشد.
onNoNetwork	زمانی که دسترسی به شبکه موجود نباشد.
onExpiring	زمانی که تبلیغ منقضی شود. هر تبلیغ مدت زمان مشخصی معتبر است و در صورتی که تا قبل از آن نمایش داده نشود منقضی شده و دیگر قابل نمایش نخواهد بود.
onOpened	زمانی که تبلیغ شروع به پخش شود
onClosed	زمانی که تبلیغ پایان یافته و کاربر در لحظه بازگشت به اپلیکیشن است

در تصویر زیر، پیاده‌سازی این توابع در پروژه نمونه، نمایش داده‌شده‌است.

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

پس از دریافت یک تبلیغ، بوسیله اکشن showAd می‌توانید تبلیغ را برای تبلیغگاه مورد نظر نمایش دهید. در این مرحله نیز باید شناسه تبلیغگاه مورد نظر ( ZoneId) را به عنوان ورودی اکشن بدهید. توضیحات ورودی‌های اکشن showAd در جدول ۳ در ادامه آمده است.

جدول ۳ ورودی‌های اکشن showAd

تابع	توضیحات
Back Button	فعال‌بودن/نبودن دکمه‌ی بازگشت گوشی در هنگام پخش تبلیغ
Immersive Mode	فعال‌بودن/نبودن حالت Immersive در هنگام پخش تبلیغ
Rotation Mode	تعیین وضعیت گوشی در هنگام پخش تبلیغ به یکی از حالات: ROTATION_LOCKED_PORTRAIT ROTATION_LOCKED_LANDSCAPE ROTATION_UNLOCKED ROTATION_LOCKED_REVERSED_PORTRAIT ROTATION_LOCKED_REVERSED_LANDSCAPE
Warning Dialog	نمایش دیالوگ اخطار در هنگام بازگشت از تبلیغات جایزه‌دار

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

جهت دریافت نتیجه نمایش تبلیغات، باید از رویدادهای onAdShowFinished و onAdShowCanceled استفاده نمایید و در آن‌ها شناسه تبلیغ‌گاه را به عنوان ورودی بدهید. در صورتیکه رویداد onAdShowFinished اجرا شد، می‌توانید جایزه درون برنامه کاربر (سکه/اعتبار/بنزین/...) را به کاربر بدهید.

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

یک نمونه پیاده‌سازی پلاگین تپسل در پروژه Construct 2 در repository زیر آمده است.

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

ایجاد پروژه Cordova و دریافت خروجی اندروید

گام ۱: گرفتن خروجی Cordova از پروژه Construct 2

برای استفاده از تپسل در پروژه Construct 2 لازم است از Cordova برای خروجی گرفتن استفاده کنید روش Build توسط سایت ها (به این دلیل که باید پلاگین تپسل به پروژه Cordova اضافه شود) معمولا جوابگو نیست. همچنین با این روش حجم فایل خروجی به نسبت خروجی سایت هایی مثل Cocoon به طرز محسوسی کمتر می باشد. در نرم افزار Construct 2، از تب Home گزینه Export Project را انتخاب کنید. در پنجره باز شده از قسمت Mobile، گزینه Cordova را انتخاب کنید و روی گزینه Next کلیک کنید. در پنجره‌ای که باز می‌شود، در قسمت Export files to پوشه www از پروژه Cordova خود را انتخاب کنید و روی گزینه Next کلیک کنید. در پنجره نهایی پس از وارد کردن تنظیمات مورد نظرتان، روی دکمه Export کلیک نمایید. پروژه Cordova شما آماده اجرا است.

گام ۲ : اضافه کردن پلاگین تپسل به پروژه Cordova

برای گرفتن خروجی اندروید، باید از Cordova استفاده کنید:

آموزش راه اندازی Cordova

جهت اضافه کردن SDK تپسل به پروژه Cordova، باید با command prompt به محل قرارگیری پروژه Cordova رفته و دستور زیر را اجرا کنید.

 cordova plugin add tapsell-construct2

با این دستور میتوانید خروجی اندروید از پروژه Cordova بگیرید:

cordova build android

اگر اجرای دستور بالا به مشکل خورد با دستور زیر یک پروژه Cordova جدید ایجاد کنید:

cordova create myAppName

و پلتفرم اندروید را به آن اضافه کنید:

cordova platform add android

پلاگین تپسل را اضافه کنید:

 cordova plugin add tapsell-construct2

فولدر www را از خروجی که قبلا گرفته بودید در محل پروژه جدید کپی کنید و دوباره خروجی بگیرید. لطفا نظرات

miadz / TapsellSDK_Construct2_Cordova_Sample