پیاده سازی ورژن ۳ SDK در Unity

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

 

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

 

Tapligh.Reward.Initialize("Your-token", test-mode);

 

Test-mode is Boolean (true | false)

برای نمایش تپلیغ دو مرحله را باید طی نمایید. در مرحله اول تبلیغ را load کرده و پس از دریافت آن را در محل و یا زمان مورد نظر نمایش دهید. (لازم به ذکر است که قبل از استفاده از متد Load به وسیله متد isInitializeDone از صحت Initialize شدن اطمینان حاصل کنید و در صورت  Initialize شدن اقدام به Load نمایید)

برای دریافت و آماده شدن تبلیغ کد زیر را کپی نمایید.

Tapligh.Reward.LoadAd("Unit-Code");

 

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

public System.Action<string, string> OnLoadReadyListener
public System.Action<string, LoadErrorStatus> OnLoadErrorListener

 

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

public enum LoadErrorStatus
{
    NO_INTERNET_ACCSSES,
    APP_NOT_FOUND,
    AD_UNIT_DISABLED,
    AD_UNIT_NOT_FOUND,
    AD_UNIT_NOT_READY,
    INTERNAL_ERROR,
    NO_AD_READY
}

 

NO_INTERNET_ACSSES

در صورتیکه اینترنت دستگاه کاربر خاموش باشد این پیغام به وی برگردانده می شود. در مواردی هم که اتصال اینترنت برقرار بوده اما دسترسی به شبکه اینترنت نداشته باشد نیز این پیغام برگردانده می شود.

 

APP_NOT_FOUND

درصورت اشتباه بودن توکن یا پکیجنیم اپ این خطا اتفاق می افتد.


AD_UNIT_DISABLED

در صورتیکه واحد تپلیغ در سمت پنل غیر فعال شده باشد، نمایش تپلیغ متوقف شده و این پیغام در موبایل دریافت می شود.


AD_UNIT_NOT_FOUND

در صورتیکه رشته کدی که به عنوان واحد تپلیغ به ورودی این متد داده می-شود دچار مشکل باشد و در سمت سرور تعریف نشده باشد این پیغام دریافت می شود. در این حالت رشته کد ورودی واحد تپلیغ رو چک کرده و در صورت وجود تفاوت آن را اصلاح نمایید.


AD_UNIT_NOT_READY

این مقدار در واحدهای بینابینی و در لحظه ای که ازنظر زمانی یا تعداد (بر اساس نوع تعریف واحد تپلیغ) موعد نمایش تبلیغ فرا نرسیده باشد برگردانده می شود.


INTERNAL_ERROR

این خطا در صورتی برگردانده می شود که اشکالی در ارتباط با کتابخانه و سرور تپلیغ به غیر از موارد توضیح داده شده رخ دهد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۴۸۱ تماس حاصل نمایید.


NO_AD_READY

در صورتیکه در این زمان و با شرایط برنامه شما تپلیغ برای نمایش وجود نداشته باشد این پیغام برگردانده می شود.

 

نکته: درصورتی که کتابخانه به درستی initialize نشده باشد نیز این خطا بازگردانده میشود.

 

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

در صورتیکه درخواست آماده سازی تبلیغ موفقیت آمیز بود، دلیگیت OnLoadReadyListener اجرا خواهد شد. برای نمایش تبلیغ از متد زیر استفاده نمایید.

 

Tapligh.Reward.ShowAd("Unit-Code");

 

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

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

public System.Action OnAdListener
public System.Action OnRewardReadyListener

 

این توابع بلافاصله پس از گرفتن جواب سرور برای درخواست شما فراخوانی می شوند.

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

public enum AdResult
{
    NO_INTERNET_ACSSES,
    BAD_TOKEN_USED,
    NO_AD_READY,
    INTERNAL_ERROR,
    TOKEN_EXPIRED,
    AD_CLICKED,
    AD_IMAGE_CLOSED,
    AD_VIDEO_CLOSED_AFTER_FULL_VIEW,
    AD_VIDEO_CLOSED_ON_VIEW,
    SKIP_AND_CLICKED,
    SKIP_AND_CLOSED
}

 

NO_INTERNET_ACSSES

در صورتیکه اینترنت دستگاه کاربر خاموش باشد این پیغام به وی برگردانده می شود. در مواردی هم که اتصال اینترنت برقرار بوده اما دسترسی به شبکه اینترنت نداشته باشد نیز این پیغام برگردانده می شود.


BAD_TOKEN_USED

در صورتیکه توکن ارسالی به سرور اشتباه باشد و یا نام بسته تعریف شده در سرور با نام بسته برنامه متفاوت باشد، این پیغام برگردانده می شود.


NO_AD_READY

در صورتیکه در این زمان و با شرایط برنامه شما تپلیغ برای نمایش وجود نداشته باشد این پیغام برگردانده می شود.


INTERNAL_ERROR

این خطا در صورتی برگردانده می شود که اشکالی در ارتباط با کتابخانه و سرور تپلیغ به غیر از موارد توضیح داده شده رخ دهد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۴۸۱ تماس حاصل نمایید.

TOKEN_EXPIRED

درصورتی که انقضای توکن تبلیغ شما به پایان رسیده باشد این پیغام ارسال می شود.


AD_CLICKED

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


AD_IMAGE_CLOSED

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


AD_VIDEO_CLOSED_AFTER_FULL_VIEW

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


AD_VIDEO_CLOSED_ON_VIEW

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

SKIP_AND_CLICKED

در صورتی که کاربر ویدیو رو اسکیپ کند و روی بنر اخر کلیک کند این پیام ارسال می شود.

SKIP_AND_CLOSED

در صورتی که کاربر ویدیو رو اسکیپ کند و بنر اخر را ببندد. این پیام فرستاده می شود.

 

نکته مهم: در صورتیکه متد showAd را پیش از اجرای متد loadAd فراخوانی نمایید در دلیگیت OnAdListener حتما مقدار NO_AD_READY را دریافت خواهید کرد.

 

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

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

فرض می کنیم که شما کلاسی به نام test دارید و می خواهید در صورت تمام شدن نمایش تبلیغ تابع checkTapligh را برای بررسی نتیجه تپلیغ و تابع OnRewardReadyListener را برای دریافت جایزه تپلیغ صدا کنید.

جهت تست پروژه خود ترجیحا از Emulator ها استفاده ننمایید.

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

using UnityEngine;
using UnityEngine.UI;
using System.Collections;
using System.Collections.Generic;

public class Test : MonoBehaviour {

    private string TOKEN = "YOUR GAME TOKEN!";
    private string UNIT_CODE = "YOUR GAME UNIT CODE!";
    private bool TEST_MODE = false;

    private string verifyToken = "";

    public Text message = null;

    void Start()
    {
        Tapligh.Reward.Initialize(TOKEN, TEST_MODE);
        Tapligh.Reward.OnAdListener = OnAdResult;
        Tapligh.Reward.OnRewardReadyListener = OnRewardReady;
        IsInitialized();
    }

    /***************** Main methods **************************/

    public void LoadAd()
    {
        Tapligh.Reward.OnLoadReadyListener = OnAdReady;
        Tapligh.Reward.OnLoadErrorListener = OnLoadError;
        Tapligh.Reward.LoadAd(UNIT_CODE);
    }

    public void ShowAd()
    {
        Tapligh.Reward.ShowAd(UNIT_CODE);
    }

    public void VerifyToken()
    {
        Tapligh.Reward.OnTokenVerifyFinishedListener = OnVerifyListener;
        Tapligh.Reward.VerifyToken(verifyToken);
    }

    public void GetTaplighVersion()
    {
        message.text = "Reward SDK Version : " + Tapligh.Reward.GetTaplighVersion();
    }

    /***************** Private methods ************************/

    private void OnRewardReady(string reward)
    {
        message.text = "Reward : " + reward;
    }

    private void OnAdReady(string unit, string token)
    {
        Debug.Log("Unity3D Controller: On Ad Ready: VERIFY TOKEN [" + token + "] & UNIT [" + unit + "]");
        if (message != null)
        {
            verifyToken = token;
            message.text = "VERIFY TOKEN [" + token + "]";
        }
    }

    private void OnAdResult(AdResult result, string token)
    {
        string msg = null;

        switch (result) {
            case AdResult.NO_INTERNET_ACSSES: msg = "NO INTERNET ACSSES"; break;
            case AdResult.BAD_TOKEN_USED: msg = "BAD TOKEN USED"; break;
            case AdResult.NO_AD_READY: msg = "NO AD READY"; break;
            case AdResult.INTERNAL_ERROR: msg = "INTERNAL ERROR"; break;
            case AdResult.TOKEN_EXPIRED: msg = "TOKEN EXPIRED"; break;
            case AdResult.AD_CLICKED: msg = "AD CLICKED"; break;
            case AdResult.AD_IMAGE_CLOSED: msg = "AD IMAGE CLOSED"; break;
            case AdResult.AD_VIDEO_CLOSED_AFTER_FULL_VIEW: msg = "AD VIDEO CLOSED AFTER FULL VIEW"; break;
            case AdResult.AD_VIDEO_CLOSED_ON_VIEW: msg = "AD VIDEO CLOSED ON VIEW"; break;
            case AdResult.SKIP_AND_CLICKED: msg = "SKIP AND CLICKED"; break;
            case AdResult.SKIP_AND_CLOSED: msg = "SKIP AND CLOSED"; break;
        }

        message.text = "Ad Result : " + msg;
    } 
    private void OnLoadError(string unit, LoadErrorStatus error)
    {
        string msg = null;

        switch (error) {
            case LoadErrorStatus.NO_INTERNET_ACCSSES: msg = "NO INTERNET ACCSSES"; break;
            case LoadErrorStatus.APP_NOT_FOUND: msg = "APP NOT FOUND"; break;
            case LoadErrorStatus.AD_UNIT_DISABLED: msg = "AD UNIT DISABLED"; break;
            case LoadErrorStatus.AD_UNIT_NOT_FOUND: msg = "AD UNIT NOT FOUND"; break;
            case LoadErrorStatus.AD_UNIT_NOT_READY: msg = "AD UNIT NOT READY"; break;
            case LoadErrorStatus.INTERNAL_ERROR: msg = "INTERNAL ERROR"; break;
            case LoadErrorStatus.NO_AD_READY: msg = "NO AD READY"; break;
        }

        Debug.Log("Unity3D Controller: On Load Error: UNIT [" + unit + "]");
        message.text = "On Load Error : " + msg;
    }

    private void OnVerifyListener(TokenResult tokenResult)
    {
        string msg = null;

        switch (tokenResult) {
            case TokenResult.INTERNAL_ERROR: msg = "ENTERNAL ERRROR"; break;
            case TokenResult.NOT_USED: msg = "NOT USED"; break;
            case TokenResult.SUCCESS: msg = "SUCCESS"; break;
            case TokenResult.TOKEN_EXPIRED: msg = "TOKEN EXPIRED"; break;
            case TokenResult.TOKEN_NOT_FOUND: msg = "TOKEN NOT FOUND"; break;
        }
        message.text = "Token Verify : " + msg;
    }

    private void IsInitialized()
    {
        message.text = "Tapligh SDK Initialized : " + Tapligh.Reward.IsInitializeDone();
    }

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

 

public void VerifyToken (string token)

 

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

public System.Action<TokenResult> OnTokenVerifyFinishedListener

 

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

۱- SUCCESS

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

۲- NOT_USED

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

۳- TOKEN_EXPIRED

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

۴- TOKEN_NOT_FOUND

توکن مربوطه در سرور وجود ندارد. در این حالت رشته توکن ارسالی را دوباره بررسی کرده تا از صحت ان مطمئن شوید وخطاهای احتمالی را برطرف نمایید.

۵- INTERNAL_ERROR

در صورت قطع بودن اتصال به اینترنت و یا بروز هرگونه خطا در ارتباط کتابخانه با سرور این مقدار برگردانده خواهد شد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۴۴۴ تماس حاصل نمایید.

 لطفا نظرات خود را در زمینه تجربه استفاده از SDK از طریق developers@tapligh.com با ما در میان بگذارید.

<span class="blu-code">public void</span> <span class="cyn-code">VerifyToken</span> <span class="blu-code">(string token)</span>

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

<span class="blu-code">public System.Action<TokenResult></span> <span class="cyn-code">OnTokenVerifyFinishedListener</span>

این دلیگیت یک ورودی از جنس یک enum به نام TokenResult می باشد. ۵ حالت برای توکن می تواند رخ داده باشد که مقادیر آن به شرح زیر است:
۱- Success: این مقدار به معنای موفقیت آمیز بودن نمایش تبلیغ بوده است. در این حالت کاربر ویدیو را به صورت کامل دیده است و شما میتوانید جایزه تعیین شده را به کاربر اختصاص دهید.
۲- NOT_USED : اطلاعات مربوط به تبلیغ نمایش داده شده به دلیل شلوغی سرورهای تپلیغ هنوز توسط سرور دریافت نشده است. در این حالت میتوانید پس از اندکی دوباره این درخواست را ارسال نمایید.
۳- TOKEN_EXPIRED: توکن مربوطه منقضی شده است. در این مورد توکن ارسالی پیش از این استفاده شده و اعتبار خود را از دست داده است.
۴- TOKEN_NOT_FOUND: توکن مربوطه در سرور وجود ندارد. در این حالت رشته توکن ارسالی را دوباره بررسی کرده تا از صحت ان مطمئن شوید وخطاهای احتمالی را برطرف نمایید.
۵- INTERNAL_ERROR: در صورت قطع بودن اتصال به اینترنت و یا بروز هرگونه خطا در ارتباط کتابخانه با سرور این مقدار برگردانده خواهد شد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۳۶۰، ۳۶۱ و یا ۴۸۱ تماس حاصل نمایید.
نمایش تپلیغات پیش فرض
در صورتیکه مقدار ورودی این متد را true قرار دهید تبلیغات پیش فرض سیستم به شما نمایش داده میشود. این حالت برای زمانی مفید است که شما در حال آزمایش هستید تا بهترین جای نمایش تبلیغ را برای برنامه خود پیدا کنید.
فراموش نکنید که در صورت استفاده از تبلیغات تست حتما قبل از انتشار نهایی برنامه خود این مقدار را false کنید. به خاطر بسپارید که کامنت کردن این خط معادل false کردن آن نیست و اگر این خط را کامنت کنید نمایش تبلیغ پیش فرض ادامه پیدا خواهد کرد.

<span class="blu-code">TaplighInterface</span>.Instance.<span class="red-code">SetTestEnable</span>(true);

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