tapselladnet/TapsellSDK_UnrealEngine_Sample

Tapsell Unreal Engine sdk android sample project

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

تنظیمات اولیه پروژه Unreal Engine (اندروید)

گام ۱: دریافت SDK تپسل

ابتدا فایل zip مربوط به SDK تپسل را از آدرس زیر دانلود کرده و در پوشه Plugins موجود در روت پروژه خود Extract کنید. اگر این پوشه وجود نداشت آنرا ایجاد کنید.

دریافت فایل

سپس برنامه را یک بار ریستارت کنید.

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

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

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

گام ۳:تنظیمات اولیه Sdk

از منو Edit -> Project Settings -> Platforms -> Android ، دسترسی های زیر را به پروژه اندروید خود اضافه کنید. افزودن مواردی که optional (اختیاری) هستند باعث افزایش کیفیت و بهینه بودن تبلیغات می شود که میتواند بعدا در میزان درآمد شما نیز تاثیر داشته باشند.

android.permission.ACCESS_NETWORK_STATE
android.permission.INTERNET
android.permission.READ_PHONE_STATE   (optional)
android.permission.VIBRATE   (optional)
android.permission.ACCESS_COARSE_LOCATION   (optional)

 

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

خطوط زیر را به انتهای فایل DefaultEngine.ini موجود در فولدر Config پروژه خود اضافه کنید:

[Advertisement]
TapsellAppID=appKey

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

Edit -> Plugins -> Project -> Advertising پلاگین تپسل را Enable کنید و محیط توسعه را ریستارت کنید.

پلاگین تپسل از Blueprint برای اجرا استفاده میکند. برای شروع کار با Sdk تپسل در شروع برنامه کامپوننت آنرا مانند شکل زیر اضافه کنید:

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

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

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

با فراخوانی تابع زیر، می توانید یک درخواست تبلیغ به تپسل ارسال کرده و یک تبلیغ دریافت نمایید:

هر درخواست شامل یک ورودی zoneId است که باید آن را از داشبورد تپسل در صفحه اپلیکیشن خود دریافت کنید. دقت کنید که این پارامتر نباید خالی باشد. ورودی isCached نشان می دهد که آیا تبلیغ باید ابتدا دانلود شده و سپس به کاربر نشان داده شود یا خیر.

[ht_message mstyle="danger" title="کش کردن ویدئو" " show_icon="" id="" class="" style="" ]تنها در ناحیه‌هایی که کاربر با احتمال زیادی پس از باز کردن اپلیکیشن تبلیغ آن را مشاهده می‌کند، از تبلیغ Cached استفاده کنید. جهت توضیحات بیشتر درباره روش انتخاب متد دریافت مناسب، اینجا را مطالعه کنید.[/ht_message]

برای دریافت نتیجه درخواست تبلیغ باید Event های مربوط به آنها را در هنگام شروع برنامه Bind کنید. نتیجه درخواست تبلیغ به Event های Bind شده برگردانده می شود. در اکشن onAdAvailable شناسه یک تبلیغ به شما برگردانده می شود که می بایست جهت نمایش تبلیغ از آن استفاده کنید. نمونه پیاده سازی:

شمای کلی:

توضیحات اکشن های مختلف و شرایط اجرا شدن آن ها در جدول ۱ آمده است.

 

جدول ۱ اکشن های دریافت نتیجه درخواست تبلیغ

تابع	توضیحات (زمان اجرا)
onErrorAction	هنگامی که هر نوع خطایی در پروسه‌ی دریافت تبلیغ بوجود بیاید
onAdAvailableAction	زمانی که تبلیغ دریافت شده و آماده‌ی نمایش باشد.
onNoAdAvailableAction	در صورتی که تبلیغی برای نمایش وجود نداشته باشد.
onNoNetworkAction	زمانی که دسترسی به شبکه موجود نباشد.
onExpiring	زمانی که تبلیغ منقضی شود. هر تبلیغ مدت زمان مشخصی معتبر است و در صورتی که تا قبل از آن نمایش داده نشود منقضی شده و دیگر قابل نمایش نخواهد بود.

 

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

جهت نمایش تبلیغ، می‌توانید از تابع زیر استفاده نمایید (این تابع حداکثر یک بار برای هر تبلیغ قابل اجراست) :

ورودی Ad Id شناسه تبلیغی است که در گام قبل و در اکشن onAdAvailable به شما داده شده‌است. ورودی Zone Id نیز مربوط به شناسه zone ای است که برای آن درخواست تبلیغ داده اید. توضیحات سایر ورودی ها در جدول ۲ آورده شده است.

 

جدول ۲ ورودی های Tapsell Show Ad

متغیر (نوع)	توضیحات
Back Disabled	در هنگام پخش تبلیغ دکمه‌ی بازگشت گوشی فعال باشد یا خیر
Immmersive Mode	فعال‌سازی حالت Immersive در هنگام پخش تبلیغ (فقط در اندروید)
Rotation Mode	تعیین وضعیت گوشی در هنگام پخش تبلیغ به یکی از سه حالت: LOCKED PORTRAIT LOCKED LANDSCAPE UNLOCKED LOCKED REVERSED PORTRAIT LOCKED REVERSED LANDSCAPE
Show Dialog	نمایش دیالوگ اخطار در هنگام بازگشت از تبلیغات جایزه‌دار

 

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

در صورتیکه در اپلیکیشن خود از تبلیغات جایزه‌دار استفاده می‌کنید، جهت دریافت نتیجه نمایش تبلیغ‌ها، باید یک Event مطابق زیر Bind کنید.

پس از نمایش تبلیغ، اکشن onAdShowFinished اجرا می‌شود. درصورتیکه تبلیغ نمایش داده شده جایزه‌دار باشد، متغیر Rewarded دارای مقدار true خواهد بود. همچنین درصورتیکه تبلیغ تا انتها دیده شود، متغیر Completed دارای مقدار true خواهد بود. در صورتی که تبلیغ جایزه‌دار باشد و مشاهده ویدئو تا انتها انجام شده باشد، باید جایزه درون برنامه (سکه، اعتبار، بنزین یا ...) را به کاربر بدهید.

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

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

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

مقدار zoneId کلیدی ست که بعد از ساخت اپلیکیشن در پنل و ثبت یک zone از نوع بنری استاندارد دریافت میکنید. ورودی Banner Type اندازه های مختلف را بیان میکند. ورودی Horizontal Gravity نشان میدهد که آیا تبلیغ، بالا یا پایین صفحه باشد، همچنین Vertical Gravity بیان میکند که تبلیغ از جهت عرضی در کجای صفحه باشد.

موارد پیشرفته‌تر در SDK

دریافت نسخه SDK تپسل

درصورتی که نیازمند به دانستن نسخه تپسل پیاده‌سازی شده در اپلیکیشن خود هستید، می‌توانید با فراخوانی تابع زیر عنوان نسخه را دریافت نمایید:

تنظیمات کشینگ (اندروید)

همانطور که گفته شد، از نسخه ۳ به بعد تپسل قابلیت نمایش ویدئو بصورت استریم و همینطور نمایش ویدئو بعد از دانلود فایل (کشینگ) را دارد. با این قابلیت، قبل از نمایش تبلیغ و در هنگامی که کاربر مشغول استفاده از اپلیکیشن است، ویدئو بطور کامل دریافت می‌شود و کاربر بدون هیچگونه مکثی می‌تواند ویدئو را تماشا کند.

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

جهت جلوگیری از اشغال پهنای باند زیاد توسط تپسل، شما می‌توانید درصد مشخصی از کل پهنای باند موجود را به دانلود ویدئو اختصاص دهید. جهت انجام این عمل، تابع زیر را در آغاز برنامه (قبل از درخواست تبلیغ) فراخوانی کنید:

در این تابع، ورودی Max Percentage حداکثر درصدی از پهنای باند در دسترس اپلیکیشن است که SDK تپسل از آن برای دریافت ویدئو استفاده می‌کند.

همچنین درصورتی که از سرعت دانلود واقعی کاربر در اپلیکیشن خود اطلاع دارید می‌توانید به کمک تابع زیر، مقدار حداکثر پهنای باند قابل استفاده برای دانلود ویدئو را به کمک تابع زیر تنظیم کنید.

ورودی این تابع، میزان حداکثر سرعت دانلود ویدئو است که باید به واحد بایت بر ثانیه داده شود.

در صورتی که در بخشی از اپلیکیشن خود می‌خواهید تنظیمات مربوط به محدودیت سرعت دانلود را غیرفعال نمایید، از تابع زیر استفاده کنید:

توضیحات بیشتر درباره کشینگ و استریمینگ در SDK تپسل را اینجا بخوانید.

 

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

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

در حالت AUTO زمان درخواست تبلیغ درصورت عدم وجود دسترسی مورد نیاز، دیالوگ دریافت دسترسی به کاربر نمایش داده می‌شود. اگر کاربر دسترسی را به اپلیکیشن بدهد تبلیغ دریافت می‌شود و در صورت رد کردن تبلیغ دریافت نمی‌شود. در این حالت اگر کاربر گزینه Don't show again را انتخاب کند دیگر دیالوگ دریافت دسترسی به وی نشان داده نمی‌شود. در حالت AUTO INSIST حتی اگر کاربر گزینه Don't show again را نیز انتخاب کند باز یک دیالوگ به کاربر نمایش داده می‌شود که وی را به صفحه تنظیمات اپ برای تغییر دسترسی مورد نیاز می‌برد.

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

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

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