پیاده سازی SDK در GameMaker

نحوه شروع به کار با کتابخانه GameMaker

برای شروع به کار با کتابخانه تپلیغ در ابتدا باید یک حساب کاربری در تپلیغ ایجاد کنید (راهنمای ثبت نام) . پس از ثبت نام جهت ثبت اپلیکیشن خود جهت فعال سازی کتابخانه از بخش راهنمای اضافه کردن برنامه نسبت به ثبت برنامه های خود اقدام کنید و سپس کد فعال سازی کتابخانه را برای آن دریافت نمایید. در این مرحله کتابخانه jar را از اینجا دانلود کنید و بعد از دانلود مراحل زیر را طی کنید :

ابتدا در GameMaker، بر روی پوشه Extensions راست کلیک کنید و سپس گزینه Import Extension را انتخاب کنید. فایل TaplighSDK.gmez را انتخاب کرده و به پروژه اضافه کنید.

به صورت اتوماتیک دسترسی های زیر به پروژه شما اضافه می شود و شما نیاز نیست کاری انجام دهید.

<span class="org-code"><uses-permission</span> <span class="prp-code">android</span>:name=<span class="grn-code">"android.permission.INTERNET"</span><span class="org-code">/></span>
<span class="org-code"><uses-permission</span> <span class="prp-code">android</span>:name=<span class="grn-code">"android.permission.ACCESS_NETWORK_STATE"</span><span class="org-code">/></span>
<span class="org-code"><uses-permission</span> <span class="prp-code">android</span>:name=<span class="grn-code">"android.permission.ACCESS_COARSE_LOCATION"</span><span class="org-code">/></span>

دسترسی INTERNET برای اتصالات کتابخانه به شبکه و دریافت تبلیغات درخواست شده است.

دسترسی ACCESS_NETWORK_STATE برای بررسی وضعیت اتصال دستگاه به شبکه اینترنت درخواست شده است.

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

شروع به کار با کتابخانه

ابتدا باید حتما در ابتدا توکن برنامه خود را به کتابخانه تپلیغ معرفی نمایید. برای این منظور از قطعه کد زیر استفاده کنید.

InitializeTapligh("YOUR-TOKEN");

حال برای نمایش تبلیغ بایستی ابتدا آن را دریافت نمایید. به همین منظور کد زیر را در جای مورد نظر کد خود قرار دهید.

LoadAd("UNIT-CODE");

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

اگر درباره مفهوم واحد تپلیغ هنوز اطلاعات زیادی ندارید، می توانید این پست بلاگ را مطالعه نمایید.

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

با استفاده از این ورودی که در هنگام درخواست تبلیغ تعیین می کنید می توانید از وجود یا عدم وجود تپلیغ اطلاع کسب کنید. پاسخ به درخواست‌ها در رویداد Asynchronous Social Event قابل مشاهده است. در این پاسخ رویداد یک ds_map به async_load اختصاص داده می‌شود. در ds_map برگردانده شده، کلید type نشان دهنده‌ی پاسخ برگردانده شده است. برای دریافت جواب ابتدا بر روی یکی از object های خود، در قسمت Eventها از طریق Asynchrounus ، یک Social به event های خود اضافه کنید.

سپس یک کد به این Event اضافه کنید و قطعه کد زیر را در آن بنویسید.

type = string(async_load[? "type"]);
if(type== TAPLIGH_AD_LOAD_RESULT)
{
    var loadAdResult = string(async_load[? "loadAdResult"]);
    var result = string(async_load[? "result"]);

    if(loadAdResult == "1")    {
        //AVAILABLE!
    }
else {
//UNAVAILABLE!
     if(result == taplighInternalError)
        {
            //Internal Error
        }
        else if(result == taplighBadTokenUsed)
        {
            // Bad token
        }
        else if(result == taplighNoAdReady)
        {
            //No Ad Ready
        }
        else if(result == taplighAdunitDisabled)
        {
            //Ad unit disabled
        }
        else if(result == taplighAdunitNotFound)
        {
            //Ad unit not found
        }
}

نتیجه درخواست دریافت تبلیغ در قسمت شرطی بازگردانده می شود و به شرح زیر است:

    • taplighNoInternetAccess : در صورتیکه اینترنت دستگاه کاربر خاموش باشد این پیغام به وی برگردانده می شود. در مواردی هم که اتصال اینترنت برقرار بوده اما دسترسی به شبکه اینترنت نداشته باشد نیز این پیغام برگردانده می شود.
    • taplighBadTokenUsed : در صورتیکه توکن ارسالی به سرور اشتباه باشد این پیغام برگردانده می شود.
    • taplighNoAdReady : در صورتیکه در این زمان و با شرایط برنامه شما تبلیغ برای نمایش وجود نداشته باشد این پیغام برگردانده می شود.
    • taplighAdUnitDisabled : در صورتیکه واحد تپلیغ در سمت پنل غیر فعال شده باشد، نمایش تبلیغ متوقف شده و این پیغام در موبایل دریافت می شود.
    • taplighAdunitNotFound : در صورتیکه رشته کدی که به عنوان واحد تپلیغ به ورودی این متد داده می شود دچار مشکل باشد و در سمت سرور تعریف نشده باشد این پیغام دریافت می شود. در این حالت رشته کد ورودی واحد تپلیغ رو چک کرده و در صورت وجود تفاوت آن را اصلاح نمایید.
    • taplighInternalError : این خطا در صورتی برگردانده می شود که اشکالی در ارتباط با کتابخانه و سرور تپلیغ به غیر از موارد توضیح داده شده رخ دهد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۳۶۰، ۳۶۱ و یا ۴۸۱ تماس حاصل نمایید.

در صورتیکه در این event در جواب loadAdResult مقدار «۱» را دریافت کردید به معنای دریافت صحیح تبلیغ است. حال می توانید با استفاده از قطعه کد زیر تبلیغ را نمایش دهید :

ShowAd("UNIT-CODE");

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

دریافت نتیجه نمایش تپلیغ

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

پاسخ به درخواست‌ها در رویداد Asynchronous Social Event قابل مشاهده است. در این پاسخ رویداد یک ds_map به async_load اختصاص داده می‌شود. در ds_map برگردانده شده، کلید type نشان دهنده‌ی پاسخ برگردانده شده است. برای دریافت جواب ابتدا بر روی یکی از object های خود، در قسمت Eventها از طریق Asynchrounus ، یک Social به event های خود اضافه کنید.

سپس یک کد به این Event اضافه کنید و قطعه کد زیر را در آن بنویسید.

type = string(async_load[? "type"]);
if(type==TAPLIGH_AD_REWARD_RESULT) {
    var reward = string(async_load[? "reward"]);
    global.matn = reward;
}
else if(type==TAPLIGH_AD_SHOW_RESULT){
    var result = string(async_load[? "result"]);
    var token = string(async_load[? "token"])
    if(result == taplighNoInternetAccess)    {
    }
    else if(result == taplighBadTokenUsed)    {
    }
    else if(result == taplighInternalError)    {
    }
    else if(result == taplighNoAdReady)    {
    }
    else if(result == taplighAdVideoClosedOnView)    {
    }
    else if(result == taplighAdViewCompletely)    {
    }
    else if(result == taplighAdClicked)    {
    }
    else if(result == taplighAdVideoClosedAfterFulView){
    }
    else if(result == taplighAdImageClosed)    {
    }

اگر تبلیغ به صورت کامل دیده شده و از نوع جایزه ای باشد، در قسمت اول مقدار جایزه در متغیر reward ذخیره می شود. نتیجه تبلیغ به صورت زیر در قسمت شرطی بعد بازگردانده می شود :

    • taplighNoInternetAccess : در صورتیکه اینترنت دستگاه کاربر خاموش باشد این پیغام به وی برگردانده می شود. در مواردی هم که اتصال اینترنت برقرار بوده اما دسترسی به شبکه اینترنت نداشته باشد نیز این پیغام برگردانده می شود.
    • taplighBadTokenUsed : در صورتیکه توکن ارسالی به سرور اشتباه باشد این پیغام برگردانده می شود.
    • taplighNoAdReady : در صورتیکه در این زمان و با شرایط برنامه شما تبلیغ برای نمایش وجود نداشته باشد این پیغام برگردانده می شود.
    • taplighAdViewCompletely : در صورتیکه کاربر تبلیغ ویدیویی را به صورت کامل مشاهده کند این پیام را دریافت خواهد کرد. توجه کنید از این اکشن تنها برای تصمیم گیری برای دادن جایزه و یا عملکردهای دیگر استفاده کنید و اجرا کردن اکشن موردنظرتان را از طریق مقادیر پایینی انجام دهید. چرا که در این حالت هنوز تبلیغ بسته نشده و اکتیویتی تبلیغ بر روی اکتیویتی شما قرار دارد.
    • taplighAdClicked : در صورتیکه کاربر بر روی تبلیغ کلیک کند این مقدار برگردانده می شود. در این حالت به واسطه بسته شدن صفحه نمایش تبلیغ و بازگشت از آن به صفحه فراخوانی تبلیغ برنامه تان، شما می توانید واکنش های مناسب خود را اجرا کنید.
    • taplighAdImageClosed : اگر کاربر بر روی علامت بستن تبلیغ تصویری نمایش داده شده کلیک کند این مقدار برگردانده می شود. توجه کنید که این حالت شامل کلیک بر روی آیکون بستن تصویر انتهایی تبلیغ ویدیویی نمی باشد و آن عملیات از طریق دو مقدار بعدی برگردانده می شود. همچنین در این حالت به واسطه بسته شدن صفحه نمایش تبلیغ و بازگشت از آن به صفحه فراخوانی تبلیغ برنامه تان، شما می توانید واکنش های مناسب خود را اجرا کنید.
    • taplighAdVideoClosedAfterFulView : در صورتیکه کاربر پس از نمایش کامل ویدیو بر روی علامت بستن تصویر انتهایی تبلیغ کلیک کند این مقدار برگردانده می شود. در صورتیکه شما به کاربر به واسطه نمایش کامل ویدیو قصد دادن امتیاز، سکه و… را دارید از طریق این مقدار می توانید این کار را انجام دهید.
    • taplighAdVideoClosedOnView : اگر کاربر حین نمایش تبلیغ ویدیویی آن را ببندد، این مقدار برگردانده می شود. توجه کنید که در این حالت به واسطه بسته شدن صفحه نمایش تبلیغ و بازگشت از آن به صفحه فراخوانی تبلیغ برنامه تان، شما می توانید واکنش های مناسب خود را اجرا کنید.
    • taplighInternalError : این خطا در صورتی برگردانده می شود که اشکالی در ارتباط با کتابخانه و سرور تپلیغ به غیر از موارد توضیح داده شده رخ دهد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۳۶۰، ۳۶۱ و یا ۴۸۱ تماس حاصل نمایید.

نکته مهم : در صورتیکه پیش از اجرای متد loadAd متد showAd را فراخوانی کنید حتما در متدonAdResult با پاسخ noAdReady مواجه خواهید شد.

بررسی صحت اطلاعات نمایش تبلیغ

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

برای فرایند نمایش هر تبلیغ یک توکن منحصر به فرد ثبت می شود و توسعه دهنده می تواند این توکن را پس از پایان نمایش ودر هنگام دریافت نتیجه تبلیغ دریافت کند. سپس می تواند با استفاده از متد زیر وضعیت این توکن را در سرور تپلیغ بررسی نماید.

InitializeTapligh("YOUR-TOKEN");

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

type = string(async_load[? "type"]); if(type==TAPLIGH_VERIFY_TOKEN_RESULT)
{
    var result = string(async_load[? "result"]);
    if(result == taplighSuccess)    {
//OK!
    }
    else if (result == taplighNotUsed) {
    }
    else if (result == taplighNotFound) {
    }
    else if (result == taplighTokenExpired) {
    }
    else if (result == taplighInternalError) {
    }
}

۵ حالت برای توکن می تواند رخ داده باشد. شما می توانید تمامی این مقادیر در کلاس TokenResult مشاهده نمایید :

    • taplighSuccess : این مقدار به معنای موفقیت آمیز بودن نمایش تبلیغ بوده است. در این حالت کاربر ویدیو را به صورت کامل دیده است.
    • taplighNotUsed : اطلاعات مربوط به نمایش تبلیغ هنوز توسط سرور دریافت نشده است.
    • taplighNotFound : توکن مربوطه منقضی شده است.
    • taplighTokenExpired : توکن مربوطه در سرور وجود ندارد.
    • taplighInternalError : در صورت قطع بودن اتصال به اینترنت و یا بروز هرگونه خطا در ارتباط کتابخانه با سرور این مقدار برگردانده خواهد شد.

نمایش تبلیغ جهت تست

SetTestEnable(1);

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

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

لطفا نظرات خود را در زمینه تجربه استفاده از SDK از طریق developers@tapligh.com ، شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی 481 و یا تلگرام با ما در میان بگذارید.