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

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

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

 

برای اضافه کردن فایل کتابخانه به پروژه مراحل زیر را طی نمایید.

۱ – ابتدا در پروژه اندروید خود نحوه نمایش پروژه را به حالت project تغییر دهید و در پوشه libs فایل کتابخانه واقع در فولدر Library کتابخانه را اضافه نمایید. در صورتیکه فولدر libs در پروژه شما وجود ندارد آن را ایجاد کنید.

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

۲ – در فایل manifest پروژه خود دسترسی های زیر را اضافه نمایید. در صورتیکه هر یک از این درخواست ها را قبلا اضافه کرده اید نیازی به اضافه کردن دوباره آن نیست.
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

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

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

۳ – در زیر تگ application خود کدهای زیر را اضافه نمایید.
<activity android:name="com.tapligh.sdk.ADView.ADView" android:configChanges="orientation|screenSize|screenLayout|keyboardHidden|uiMode" android:theme="@android:style/Theme.Translucent.NoTitleBar"/>
<receiver android:name="com.tapligh.sdk.ADView.ADsReceiver">
    <intent-filter android:priority="999">
        <action android:name="android.intent.action.PACKAGE_INSTALL" />
        <action android:name="android.intent.action.PACKAGE_ADDED" />
        <action android:name="android.intent.action.PACKAGE_REMOVED" />
        <data android:scheme="package" />
    </intent-filter>
</receiver>
۴ – در صورتیکه از proguard در پروژه خود استفاده می کنید، خطوط زیر را به تنظیمات proguard خود اضافه کنید.
-keepattributes Signature
-keepattributes *Annotation*
-keep public class com.tapligh.sdk.ADView.**{
 	public protected private * ;
}

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

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

۱ – حداقل نسخه اندروید مورد نیاز : ۱۶
۲ – حداقل نسخه جاوای قابل پشتیبانی : ۷

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

 

  • ابتدا در صفحه ای که می خواهید تپلیغ نمایش دهید، نمونه ای از کلاس Tapligh بسازید. برای این کار از کد زیر استفاده کنید:
Tapligh tapligh = Tapligh.newInstance(Your_Activity);

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

tapligh.setToken("YOUR_TOKEN");

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

دریافت تبلیغ

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

<span class="prp-code">tapligh</span>.loadAd(<span class="grn-code">"UNIT-CODE"</span> , <span class="ylw-code">new</span> AdLoadListener() {

    <span class="ylw-code">@Override</span>
    <span class="org-code">public void onAdReady</span>( String unitCode, String token ) {

    }

    <span class="ylw-code">@Override</span>
    <span class="org-code">public void onLoadError</span>( String unitCode, LoadErrorStatus loadErrorStatus ) {

    }
});

برای استفاده از متد بالا دو ورودی لازم است. ورودی اول (UNIT-CODE) کد رشته مربوط به واحد تپلیغ است که در پنل برنامه خود ایجاد نموده اید. جهت اطلاعات بیشتر درباره واحد تپلیغ به این قسمت مراجعه کنید.

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

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

  • noInternetAccess : در صورتیکه اینترنت دستگاه کاربر خاموش باشد این پیغام به وی برگردانده می شود. در مواردی هم که اتصال اینترنت برقرار بوده اما دسترسی به شبکه اینترنت نداشته باشد نیز این پیغام برگردانده می شود.
  • badTokenUsed : در صورتیکه توکن ارسالی به سرور اشتباه باشد و یا نام بسته تعریف شده در سرور با نام بسته برنامه متفاوت باشد، این پیغام برگردانده می شود.
  • noAdReady : در صورتیکه در این زمان و با شرایط برنامه شما تپلیغ برای نمایش وجود نداشته باشد این پیغام برگردانده می شود.
  • adunitDisabled : در صورتیکه واحد تپلیغ در سمت پنل غیر فعال شده باشد، نمایش تپلیغ متوقف شده و این پیغام در موبایل دریافت می شود.
  • adunitDisabled : در صورتیکه واحد تپلیغ در سمت پنل غیر فعال شده باشد، نمایش تپلیغ متوقف شده و این پیغام در موبایل دریافت می شود.
  • adUnitNotFound : در صورتیکه رشته کدی که به عنوان واحد تپلیغ به ورودی این متد داده می شود دچار مشکل باشد و در سمت سرور تعریف نشده باشد این پیغام دریافت می شود. در این حالت رشته کد ورودی واحد تپلیغ رو چک کرده و در صورت وجود تفاوت آن را اصلاح نمایید.
  • adUnitNotReady : این مقدار در واحدهای بینابینی و در لحظه ای که ازنظر زمانی یا تعداد (بر اساس نوع تعریف واحد تپلیغ) موعد نمایش تبلیغ فرا نرسیده باشد برگردانده می شود.
  • internalError : این خطا در صورتی برگردانده می شود که اشکالی در ارتباط با کتابخانه و سرور تپلیغ به غیر از موارد توضیح داده شده رخ دهد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۳۶۰، ۳۶۱ و یا ۴۸۱ تماس حاصل نمایید.

نمایش تبلیغ

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

<span class="prp-code">tapligh</span>.showAd(<span class="grn-code">"UNIT-CODE"</span> , <span class="org-code">new</span> ADResultListener() {

    <span class="ylw-code">@Override</span>
    <span class="org-code">public void onAdResult</span>(ADResult adResult, String token) {

    }

    <span class="ylw-code">@Override</span>
    <span class="org-code">public void onRewardReady</span>(String reward) {

    }

});

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

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

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

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

<span class="ylw-code">@Override</span>
<span class="org-code">public</span> void onAdResult(ADResult adResult, String token) {
	Log.i(<span class="grn-code">"Tapligh"</span> , <span class="grn-code">"token->"</span> + token);
	<span class="org-code">switch</span> (adResult){
		<span class="org-code">case</span> <span class="prp-code">adVideoClosedOnView</span>: Log.i(<span class="grn-code">"Tapligh"</span> , <span class="grn-code">"adVideoClosedOnView"</span>); <span class="org-code">break</span>;
		<span class="org-code">case</span> <span class="prp-code">adViewCompletely</span>: Log.i(<span class="grn-code">"Tapligh"</span> , <span class="grn-code">"adViewCompletely"</span>); <span class="org-code">break</span>;
		<span class="org-code">case</span> <span class="prp-code">adClicked</span>: Log.i(<span class="grn-code">"Tapligh"</span> , <span class="grn-code">"adClicked"</span>); <span class="org-code">break</span>;
		<span class="org-code">case</span> <span class="prp-code">adVideoClosedAfterFulView</span>: Log.i(<span class="grn-code">"Tapligh"</span> , <span class="grn-code">"adVideoClosedAfterFulView"</span>); <span class="org-code">break</span>;
		// used for image ad
		<span class="org-code">case</span> <span class="prp-code">adImageClosed</span>: Log.i(<span class="grn-code">"Tapligh"</span> , <span class="grn-code">"adImageClosed"</span>); <span class="org-code">break</span>;
	}
}

<span class="ylw-code">@Override</span>
<span class="org-code">public void onRewardReady</span>(String reward) {
        Log.i(<span class="grn-code">"Tapligh"</span> , <span class="grn-code">"reward->"</span> + reward);
}

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

  • noInternetAccess : در صورتیکه اینترنت دستگاه کاربر خاموش باشد این پیغام به وی برگردانده می شود. در مواردی هم که اتصال اینترنت برقرار بوده اما دسترسی به شبکه اینترنت نداشته باشد نیز این پیغام برگردانده می شود.
  • adViewCompletely : در صورتیکه کاربر تپلیغ ویدیویی را به صورت کامل مشاهده کند این پیام را دریافت خواهد کرد. توجه کنید از این اکشن تنها برای تصمیم گیری برای دادن جایزه و یا عملکردهای دیگر استفاده کنید و اجرا کردن اکشن موردنظرتان را از طریق مقادیر پایینی انجام دهید. چرا که در این حالت هنوز تپلیغ بسته نشده و اکتیویتی تپلیغ بر روی اکتیویتی شما قرار دارد.
  • adClicked : در صورتیکه کاربر بر روی تپلیغ کلیک کند این مقدار برگردانده می شود. در این حالت به واسطه بسته شدن صفحه نمایش تپلیغ و بازگشت از آن به صفحه فراخوانی تپلیغ برنامه تان، شما می توانید واکنش های مناسب خود را اجرا کنید.
  • adImageClosed : اگر کاربر بر روی علامت بستن تپلیغ تصویری نمایش داده شده کلیک کند این مقدار برگردانده می شود. توجه کنید که این حالت شامل کلیک بر روی آیکون بستن تصویر انتهایی تپلیغ ویدیویی نمی باشد و آن عملیات از طریق دو مقدار بعدی برگردانده می شود. همچنین در این حالت به واسطه بسته شدن صفحه نمایش تپلیغ و بازگشت از آن به صفحه فراخوانی تپلیغ برنامه تان، شما می توانید واکنش های مناسب خود را اجرا کنید.
  • adVideoClosedAfterFulView : در صورتیکه کاربر پس از نمایش کامل ویدیو بر روی علامت بستن تصویر انتهایی تپلیغ کلیک کند این مقدار برگردانده می شود. در صورتیکه شما به کاربر به واسطه نمایش کامل ویدیو قصد دادن امتیاز، سکه و… را دارید از طریق این مقدار می توانید این کار را انجام دهید.
  • adVideoClosedOnView : اگر کاربر حین نمایش تپلیغ ویدیویی آن را ببندد، این مقدار برگردانده می شود. توجه کنید که در این حالت به واسطه بسته شدن صفحه نمایش تپلیغ و بازگشت از آن به صفحه فراخوانی تپلیغ برنامه تان، شما می توانید واکنش های مناسب خود را اجرا کنید.
  • internalError :این خطا در صورتی برگردانده می شود که اشکالی در ارتباط با کتابخانه و سرور تپلیغ به غیر از موارد توضیح داده شده رخ دهد. در این حالت پس از حصول اطمینان از درستی کد و انجام تمامی موارد توضیح داده شده با واحد پشتیبانی تپلیغ به شماره ۴۲۵۷۰۰۰۰-۰۲۱ داخلی ۳۶۰، ۳۶۱ و یا ۴۸۱ تماس حاصل نمایید.

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

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

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

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

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

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

<span class="prp-code">tapligh</span>.verifyToken(Context_OR_Activity, String TOKEN, new VerifyTokenListener(){

        <span class="ylw-code">@Override</span>
        <span class="org-code">public void onTokenVerified</span>(TokenResult result) {
              if(TokenResult.<span class="prp-code">SUCCESS</span>.equals(result)){
                 //TODO write your code
              } else if (TokenResult.<span class="prp-code">TOKEN_EXPIRED</span>.equals(result)) {
                 //TODO write your code
              } else if(TokenResult.<span class="prp-code">NOT_USED</span>.equals(result)){
                 //TODO write your code
              } else if(TokenResult.<span class="prp-code">TOKEN_NOT_FOUND</span>.equals(result)){
                 //TODO write your code
              } else if(TokenResult.<span class="prp-code">INTERNAL_ERROR</span>.equals(result)){
                 //TODO write your code
              }
          }
  });

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

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

 

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

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

<span class="prp-code">tapligh</span>.setTestEnable(MainActivity, <span class="org-code">boolean</span>);

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

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

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

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