پیاده سازی SDK در اندروید استدیو

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

در فایل gradle اصلی پروژه ریپازیتوری تپلیغ را به صورت زیر به لیست ریپازیتوریهای خود اضافه کنید:

 

maven { url  "https://dl.bintray.com/tapligh/Tapligh-SDK" }

خروجی نهایی فایل باید به صورت شکل زیر باشد.

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

// for gradle 3.0 and above
implementation 'com.tapligh.sdk:rewarded-sdk:3.+'
// for gradle before version 3.0
compile 'com.tapligh.sdk:rewarded-sdk:3.+'

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

 در صورتیکه از proguard در پروژه خود استفاده می­کنید، خطوط زیر را به تنظیمات proguard خود اضافه کنید.

-keepattributes Signature
-keepattributes *Annotation*

-keep public class com.tapligh.sdk.**{ * ; }
-keep public interface com.tapligh.sdk.**{ * ; }

-keepclassmembers class * extends java.lang.Enum {
    <fields>;
    public static **[] values();
    public static ** valueOf(java.lang.String);
}

نیازمندی های اولیه

  • حداقل نسخه اندروید مورد نیاز : 16
  • حداقل نسخه جاوای قابل پشتیبانی : 7

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

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

Tapligh tapligh = Tapligh.newInstance(Your-Activity);

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

tapligh.setToken("YOUR-TOKEN", boolean);

در این کد عبارت YOUR-TOKEN توکنی است که شما پس از ثبت برنامه خود در پنل تپلیغ آن را دریافت میکنید.

در صورتیکه مقدار ورودی دوم این متد را true قرار دهید تبلیغات تست سیستم به شما نمایش داده میشود. این حالت برای زمانی مفید است که شما در حال آزمایش
هستید تا بهترین جای نمایش تپلیغ را برای برنامه خود پیدا کنید.
حال برای نمایش تبلیغ ابتدا بایستی تپلیغ را دریافت نمایید. به این منظور کد زیر را در جای مورد نظر کد خود قرار دهید:
tapligh.loadAd("UNIT-CODE" , newAdLoadListener() {
    @Override
    public void onAdReady(String unitCode, String token) {
        
    }
    @Override
    public void onLoadError(String unitCode, LoadErrorStatus loadErrorStatus) {
        
    }
});
برای استفاده از این متد دو ورودی لزم است. ورودی اول کد رشته مربوط به واحد تپلیغ است که در پنل برنامه خود ایجاد نموده اید.

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

  • noInternetAccess: در صورتیکه اینترنت دستگاه کاربر خاموش باشد این پیغام به وی برگردانده میشود. در مواردی هم که اتصال اینترنت برقرار بوده اما دسترسی به شبکه اینترنت نداشته باشد نیز این پیغام برگردانده میشود.
  • appNotFound: در صورتیکه توکن ارسالی به سرور اشتباه باشد و یا نام بسته تعریف شده در سرور با نام بسته برنامه متفاوت باشد، این پیغام برگردانده میشود.
  • noAdReady : در صورتیکه در این زمان و با شرایط برنامه شما تپلیغ برای نمایش وجود نداشته باشد این پیغام برگردانده میشود.
  • adunitDisabled: در صورتیکه واحد تپلیغ در سمت پنل غیر فعال شده باشد، نمایش تپلیغ متوقف شده و این پیغام در موبایل دریافت میشود.
  • adUnitNotFound: در صورتیکه رشته کدی که به عنوان واحد تپلیغ به ورودی این متد داده میشود دچار مشکل باشد و در سمت سرور تعریف نشده باشد این پیغام دریافت میشود. در این حالت رشته کد ورودی واحد تپلیغ رو چک کرده و در صورت وجود تفاوت آن را اصلاح نمایید.
  • adUnitNotReady: این مقدار در واحدهای بینابینی و در لحظه ای که ازنظر زمانی یا تعداد (بر اساس نوع تعریف واحد تپلیغ) موعد نمایش تبلیغ فرا نرسیده باشد برگردانده می شود.
  • internalError: این خطا در صورتی برگردانده میشود که اشکالی در ارتباط با کتابخانه و سرور تپلیغ به غیر از موارد توضیح داده شده رخ دهد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره 42570000-021 داخلی 444 تماس حاصل نمایید.

    پس از آنکه متد onAdReady اجرا شد، به این معنی است که تبلیغ آماده نمایش است. بنابراین برای نمایش تبلیغ از متد زیر استفاده نمایید: 

tapligh.showAd("UNIT-CODE" , new ADResultListener () {

   @Override
   public void onAdResult(ADResult adResult, String token) {

   }

   @Override
   public void onRewardReady(String reward) {

   }

});
برای استفاده از این متد دو ورودی لزم است. ورودی اول رشته کد مربوط به واحد تپلیغی
است که در ورودی متد loadAd استفاده کردید.با استفاده از ورودی دوم میتوانید نتیجه نمایش تبلیغ را مشاهده کنید. در ادامه درباره این ورودی توضیحات بیشتری ارائه خواهیم داد.

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

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

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

@Override
public void onAdResult(ADResult adResult, String token) {
   Log.i("Tapligh" , "token->" + token);
   switch (adResult){
     case tokenExpired: Log.i("Tapligh", "tokenExpired"); break;
     case adVideoClosedOnView: Log.i("Tapligh", "adVideoClosedOnView"); break;
     case adViewCompletely: Log.i("Tapligh", "adViewCompletely"); break;
     case adClicked: Log.i("Tapligh", "adClicked"); break;
     case adVideoClosedAfterFulView: Log.i("Tapligh"  , "adVideoClosedAfterFulView"); break;
     case skipAndClicked: Log.i("Tapligh", "skipAndClicked"); break;
     case skipAndClosed: Log.i("Tapligh", "skipAndClosed"); break;
     // used for image ad
     case adImageClosed: Log.i("Tapligh", "adImageClosed");break;
   }
}
@Override
public void onRewardReady(String reward) {
   Log.i("Tapligh" , "reward->" + reward);
}

مقادیر مربوط به نتیجه تپلیغ به صورت زیر هستند:

  • tokenExpired:در صورتی که این مقدار را دریافت کنید به این معنی است که تبلیغ لود شده، منقضی شده است. در این حالت از طریق متد loadAd دوباره باید درخواست تبلیغ بدهید.
  • adClicked : در صورتیکه کاربر بر روی تپلیغ کلیک کند این مقدار برگردانده می­شود. در این حالت به واسطه بسته شدن صفحه نمایش تپلیغ و بازگشت از آن به صفحه فراخوانی تپلیغ برنامه تان، شما می­توانید واکنش­های مناسب خود را اجرا کنید.
  • adImageClosed : اگر کاربر بر روی علامت بستن تپلیغ تصویری نمایش داده شده کلیک کند این مقدار برگردانده می­شود. توجه کنید که این حالت شامل کلیک بر روی آیکون بستن تصویر انتهایی تپلیغ ویدیویی نمی­باشد و آن عملیات از طریق دو مقدار بعدی برگردانده می­شود. همچنین در این حالت به واسطه بسته شدن صفحه نمایش تپلیغ و بازگشت از آن به صفحه فراخوانی تپلیغ برنامه تان، شما می­توانید واکنش­های مناسب خود را اجرا کنید.
  • adVideoClosedAfterFulView : در صورتیکه کاربر پس از نمایش کامل ویدیو بر روی علامت بستن تصویر انتهایی تپلیغ کلیک کند این مقدار برگردانده می­شود. در صورتیکه شما به کاربر به واسطه نمایش کامل ویدیو قصد دادن امتیاز، سکه و… را دارید از طریق این مقدار می­توانید این کار را انجام دهید.
  • adVideoClosedOnView : اگر کاربر حین نمایش تپلیغ ویدیویی آن را ببندد، این مقدار برگردانده می­شود. توجه کنید که در این حالت به واسطه بسته شدن صفحه نمایش تپلیغ و بازگشت از آن به صفحه فراخوانی تپلیغ برنامه تان، شما می­توانید واکنش­های مناسب خود را اجرا کنید.
  • skipAndClicked: در صورتی که کاربر ویدیو را اسکیپ کرده و بر روی بنر نهایی ویدیو کلیک نماید این مقدار برگردانده می شود. فعالسازی قابلیت اسکیپ بر روی ویدیو از طریق تنظیمات واحد تپلیغ قابل ا اعمال است.
  • SkipAndClosed: در صورتی که کاربر ویدیو را اسکیپ کرده و در بنر انتهایی بر روی دکمه بستن آن کلیک نماید این مقدار برگردانده می شود. فعالسازی قابلیت اسکیپ بر روی ویدیو از طریق تنظیمات واحد تپلیغ قابل ا اعمال است.

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

تمامی این مقادیر در کلاس AdResult قرار داده شده­اند و شما می­توانید آنها را مشاهده کنید.

 

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

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

برای توسعه دهندگانی که در ازای نمایش تبلیغات به کاربران جایزه می دهند، مطمئن شدن از درستی ااعتبار اطلاعاتی که در خصوص نمایش کامل تبلیغ دریافت میکنند از اهمیت بالایی برخوردار است. چراکه برخی کاربران با شبیهسازی این اطلاعات در صدد دریافت جایزه‌های بینهایت بر می آیند. سرویس تپلیغ با شناخت این دغدغه راه حل زیر را در اختیار توسعه دهندگان گذاشته است.
برای فرایند نمایش هر تبلیغ یک توکن منحصر به فرد ثبت می شود و توسعه دهنده می تواند این توکن را پس از پایان نمایش ودر هنگام دریافت نتیجه تبلیغ در تابع onRewardReady دریافت کند. سپس می تواند با استفاده از متد زیر وضعیت این توکن را در سرور تپلیغ بررسی نماید.
tapligh.verifyToken(“TOKEN”, new VerifyTokenListener(){

   @Override
   public void onTokenVerified(TokenResult result) {

     if(TokenResult.SUCCESS.equals(result)) {
     //TODO write your code

     } else if (TokenResult.TOKEN_EXPIRED.equals(result)) {
     //TODO write your code

     } else if(TokenResult.NOT_USED.equals(result)) {
     //TODO write your code

     } else if(TokenResult.TOKEN_NOT_FOUND.equals(result)) {
     //TODO write your code

     } else if(TokenResult.INTERNAL_ERROR.equals(result)) {
     //TODO write your code

     }
   }
});

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

  • Success: این مقدار به معنای موفقیت آمیز بودن نمایش تپلیغ بوده است. در این حالت کاربر ویدیو را به صورت کامل دیده است.
  • NOT_USED : اطلاعات مربوط به نمایش تپلیغ هنوز توسط سرور دریافت نشده است.
  • TOKEN_EXPIRED: توکن مربوطه منقضی شده است.
  • TOKEN_NOT_FOUND: توکن مربوطه در سرور وجود ندارد.
  • INTERNAL_ERROR: در صورت قطع بودن اتصال به اینترنت و یا بروز هرگونه خطا در ارتباط کتابخانه با سرور این مقدار برگردانده خواهد شد.

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

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