پیاده سازی SDK در پلتفرم B4A

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

فقط کافیست کتابخانه Tapligh را از تب Libraries Manager بیسیک 4 اندروید تیک بزنید.

 

مرحله دوم : اضافه کردن کد منیفست

کد زیر را به منیفست اضافه کنید:

Tapligh SDK
AddApplicationText(
<activity android:name="com.tapligh.sdk.adview.ADView" android:theme="@android:style/Theme.Light.NoTitleBar" android:configChanges="orientation|screenSize|keyboardHidden"/>
<receiver android:name="com.tapligh.sdk.adview.ADsReceiver">
  <intent-filter android:priority="999">
    <action android:name="android.intent.action.PACKAGE_ADDED"/>
    <action android:name="android.intent.action.PACKAGE_REMOVED"/>
    <data android:scheme="package"/>
  </intent-filter>
</receiver>)

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

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

Dim Tapligh As Tapligh

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

 If Tapligh.IsInitializeDone=False Then
    Tapligh.Initialize("Tapligh")
    Tapligh.SetToken("YOUR-TOKEN",False)
  End If

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

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

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

Tapligh.LoadAd("UNIT-CODE")

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

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

Private Sub Tapligh_onAdReady (unitCode As String,token As String)
  Log("Tapligh : onAdReady -> "&unitCode)
  Tapligh.ShowAd(unitCode) ' نمایش تبلیغ
End Sub
Private Sub Tapligh_onLoadError (unitCode As String,LoadErrorStatus As Object)
  Log("Tapligh : onLoadError -> "&unitCode)
  Select LoadErrorStatus
    Case Tapligh.LoadErrorStatus.NoInternetAccess : Log("Tapligh : noInternetAccess")
    Case Tapligh.LoadErrorStatus.adUnitDisabled : Log("Tapligh : adUnitDisabled")
    Case Tapligh.LoadErrorStatus.adUnitNotReady : Log("Tapligh : adUnitNotReady")
    Case Tapligh.LoadErrorStatus.appNotFound : Log("Tapligh : appNotFound")
    Case Tapligh.LoadErrorStatus.InternalError : Log("Tapligh : internalError")
    Case Tapligh.LoadErrorStatus.NoAdReady : Log("Tapligh : noAdReady")
  End Select
End Sub

درصورتی که ایونت ارور اجرا شد : ورودی اول این متد کد واحد تپلیغی است که درخواست آماده سازی بر روی آن اجرا شده و ورودی دوم از نوع کلاس 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) {

   }

});

 

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

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

   }

   @Override
   public void onRewardReady(String reward) {

   }

});

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

تبلیغ را در ایونت onAdReady با استفاده از کد زیر نمایش دادیم:

Tapligh.ShowAd(unitCode)

حالا برای دریافت نتیجه از دو ایونت  onAdResult و onRewardReady باید استفاده کنیم

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

geClosed")
    Case Tapligh.ADResult.skipAndClicked : Log("Tapligh : skipAndClicked")
    Case Tapligh.ADResult.skipAndClosed : Log("Tapligh : skipAndClosed")
    Case Tapligh.ADResult.tokenExpired : Log("Tapligh : tokenExpired")
  End Select
End Sub
Private Sub Tapligh_onRewardReady (reward As String)
  Log("Tapligh : reward -> "&reward)
End Sub

@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 قرار داده شده­اند و شما می­توانید آنها را مشاهده کنید.
  • Event name در اینیشتیالایز Tapligh قرار گرفته است. اگر آن را تغییر دهید باید در اول ایونت ها هم تغییر کند.

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

برای توسعه دهندگانی که در ازای نمایش تبلیغات به کاربران جایزه می دهند، مطمئن شدن از درستی ااعتبار اطلاعاتی که در خصوص نمایش کامل تبلیغ دریافت میکنند از اهمیت بالایی برخوردار است. چراکه برخی کاربران با شبیهسازی این اطلاعات در صدد دریافت جایزه‌های بینهایت بر می آیند. سرویس تپلیغ با شناخت این دغدغه راه حل زیر را در اختیار توسعه دهندگان گذاشته است.
برای فرایند نمایش هر تبلیغ یک توکن منحصر به فرد ثبت می شود و توسعه دهنده می تواند این توکن را پس از پایان نمایش ودر هنگام دریافت نتیجه تبلیغ در تابع onRewardReady دریافت کند. سپس می تواند با استفاده از متد زیر وضعیت این توکن را در سرور تپلیغ بررسی نماید.
Tapligh.VerifyToken("TOKEN")


Private Sub Tapligh_onTokenVerified (TokenResult As Object)
  Select TokenResult
    Case Tapligh.TokenResult.INTERNAL_ERROR
    Case Tapligh.TokenResult.NOT_USED
    Case Tapligh.TokenResult.SUCCESS
    Case Tapligh.TokenResult.TOKEN_EXPIRED
    Case Tapligh.TokenResult.TOKEN_NOT_FOUND
  End Select
End Sub

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

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

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

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

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