مستند استفاده از Basic4Android

پیکربندی چشمک

  • ابتدا کتابخانه چشمک برای Basic4Android را دانلود کنید.
  • سپس فایل دانلود شده را extract کرده و محتویات آن را در پوشه Libraries کتابخانه Basic4Android که در محل نصب آن قرار دارد کپی کنید.
  • در نرم افزار B4A، قسمت Libraries کلیک راست کرده و گزینه Refresh‍‍‍‍‍ را بزنید بعد Cheshmak در لیست ظاهر میشود سپس آن را انتخاب کنید.
  • برنامه B4A را باز کرده و در فایل Main قسمت Project Attributes مقدار #AdditionalJar : Cheshmak.aar را اضافه نمایید.
  • از منوی Project گزینه Manifest Editor را انتخاب کرده و در پنجره باز شده مقادیر زیر را کپی کنید.
AddManifestText( <permission android:name="${applicationId}.permission.C2D_MESSAGE" android:protectionLevel="signature" />)
AddPermission(${applicationId}.permission.C2D_MESSAGE)
AddPermission(android.permission.ACCESS_NETWORK_STATE)
AddApplicationText(<meta-data
           android:name="com.google.android.gms.version"
           android:value="@integer/google_play_services_version" />
    <service android:name="me.cheshmak.android.sdk.core.push.CheshmakPushRegistration"
           android:exported="false" />
       <service
           android:name="me.cheshmak.android.sdk.core.push.CheshIDListenerService"
           android:exported="false" >
           <intent-filter>
               <action android:name="com.google.android.gms.iid.InstanceID" />
           </intent-filter>
       </service>
       <service android:name="me.cheshmak.android.sdk.core.push.CheshGcmListenerService" />

       <receiver
           android:name="com.google.android.gms.gcm.GcmReceiver"
           android:exported="true"
           android:permission="com.google.android.c2dm.permission.SEND" >
           <intent-filter>
               <action android:name="com.google.android.c2dm.intent.RECEIVE" />
               <category android:name="me.cheshmak.android.sdk.core" />
           </intent-filter>
       </receiver>
       <receiver android:name="me.cheshmak.android.sdk.core.recievers.AlarmReceiver" >
           <intent-filter>
               <action android:name="android.intent.action.TIME_SET" />
               <action android:name="android.intent.action.ACTION_POWER_CONNECTED" />
               <action android:name="android.intent.action.ACTION_POWER_DISCONNECTED" />
               <action android:name="android.intent.action.DELETE" />
           </intent-filter>
           <intent-filter>
               <action android:name="android.intent.action.BOOT_COMPLETED" />
               <action android:name="android.intent.action.QUICKBOOT_POWERON" />
           </intent-filter>
       </receiver>
       <receiver android:name="me.cheshmak.android.sdk.core.recievers.RemoteReceiver" >
           <intent-filter>
               <action android:name="CHESH_REMOTE_DATA_ACTION" />
           </intent-filter>
       </receiver>
       <receiver android:name="me.cheshmak.android.sdk.core.recievers.LocationReceiver" />
       <receiver
           android:name="me.cheshmak.android.sdk.core.push.GcmBroadcastReceiver"
           android:permission="com.google.android.c2dm.permission.SEND" >
           <intent-filter>
               <action android:name="com.google.android.c2dm.intent.RECEIVE" />
               <category android:name="${applicationId}" />
           </intent-filter>
       </receiver>
       <service
           android:name="me.cheshmak.android.sdk.core.network.EventSendService"
           android:enabled="true" >
       </service>
       <receiver android:name="me.cheshmak.android.sdk.core.push.MessageHandler" />)

بعد از انجام مراحل بالا ، چشمک با انجام دو مرحله زیر قابل استفاده میباشد :

  • در فایل Starter متد Process_Globals شی چشمک را به صورت زیر ایجاد نمایید.
Dim chesh As Cheshmak
  • جهت استفاده از چشمک، کد زیر را در متد Service_Create وارد نمایید.
chesh.initTracker("APP_KEY")

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

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

حالا میتوانید از امکانات چشمک که در مستند زیر وجود دارد استفاده کنید.

کد نمونه

کد نمونه Basic4Android برای چشمک را می‌توانید از آدرس برنامه دمو چشمک دریافت کنید و نحوه کانفیگ کردن چشمک در آن را بررسی کنید.

ارسال رویداد ها

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

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

chesh.trackEvent("event_name")
Dim map As Map
map.Initialize
map.Put("key1","value1")
map.Put("key2","value2")
map.Put("key3","value3")
map.Put("key4","value4")
map.Put("key5","value5")
chesh.trackEvents("event_name",map)

ارسال خطاها

خطاهای برنامه ، بخش اجتناب ناپذیر اما قابل مدیریت جهت بهتر کردن محصول می باشد .با توجه به اینکه تعداد زیادی دستگاه و نسخه اندروید وجود دارد اطلاع از خطاهای موجود در برنامه کمک شایانی به بهبود عملکرد و درنتیجه رضایت کاربران دارد .چشمک با در اختیار گذاشتن توابعی برنامه نویس را قادر میسازد تا از خطاهای موجود در برنامه و حتی خطاهایی که منجر به بسته شدن آن میشود اطلاع حاصل کند .این گزارش در پنل چشمک قسمت خطاها قابل مشاهده میباشد .شما میتوانید برای خطاهایی که درون برنامه اتفاق می افتد یک مقدار عنوان تعریف کنید تا بعد از اینکه کد شما obfuscate شد به راحتی بتوانید خطای مورد نظر را در گزارش خطاهای پنل مشاهده نمایید. شما میتوانید با استفاده از سه تابع trackException , trackFATALException و trackLabeledException خطاها را مطابق نمونه های زیر ارسال نمایید .

نکات مهم :
  • تمام خطاهای که موجب Crash‍ برنامه میشوند به صورت خودکار ارسال میگردند .ارسال این نوع خطاها در حالت release امکان پذیر است .
Try
 Dim i As Int = "wrong value"
   Catch
 chesh.trackLabeledException("exception_name",LastException)
 End Try
chesh.trackFATALException("exception_name",Error)
chesh.trackException(Error)

گزارش صفحات برنامه

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

در صورت استفاده از Custom View میتوانید از دو تابع startView و stopView استفاده نمایید.

Sub Activity_Create(FirstTime As Boolean)
Activity.LoadLayout("layout")
chesh.startView("Main")

End Sub

Sub Activity_Resume

End Sub

Sub Activity_Pause (UserClosed As Boolean)
chesh.stopView("Main")
End Sub

نحوه استفاده از تگ ها

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

  • با استفاده از دو تابع addTag و addTags تگ های مورد نیاز خود را مانند مثال زیر اضافه کنید
chesh.addTag("tag1")
Dim list As List
  list.Initialize
  list.Add("tag1")
  list.Add("tag2")
  list.Add("tag3")
  list.Add("tag4")
  chesh.addTags(list)
  • تگ ها را میتوانید با استفاده از توابع deleteTag ،‍ deleteTags و deleteAllTags را حذف کنید.
chesh.deleteTag("tag1")
Dim list As List
list.Initialize
list.Add("tag1")
list.Add("tag2")
list.Add("tag3")
list.Add("tag4")
chesh.addTags(list)
chesh.deleteAllTags()

پوش نوتیفیکیشن

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

باز شدن اکتیویتی بعد از ارسال پوش

جهت باز شدن اکتیویتی بعد از ارسال پوش از منوی Project روی Manifest Editor را انتخاب کرده و خط زیر را به آن اضافه کنید.

AddActivityText(REPLACE_WITH_ACTIVITY_NAME,<meta-data android:name="cheshmakPush" android:value="openActivityOnPush"/>​)
  • نام اکتیویتی مورد نظر را با REPLACE_WITH_ACTIVITY_NAME عوض نمایید .

با استفاده از کد زیر میتوانید دیتای ارسالی از پنل را در اکتیویتی مورد نظر را دریافت کنید.

Sub Activity_Create(FirstTime As Boolean)

        Activity.LoadLayout("Layout1")

        Dim  intent As Intent
        intent =Activity.GetStartingIntent()
        Log(intent.GetExtra("me.cheshmak.data")) //Read Cheshmak Data


End Sub

باز شدن سرویس بعد از ارسال پوش

جهت باز شدن سرویس بعد از ارسال پوش از منوی Project روی Manifest Editor را انتخاب کرده و خط زیر را به آن اضافه کنید.
AddServiceText(REPLACE_WITH_SERVICE_NAME,<meta-data  android:name="cheshmakPush" android:value="startServiceOnPush"/>​)
  • نام سرویس مورد نظر را با REPLACE_WITH_SERVICE_NAME عوض نمایید .

با استفاده از کد زیر میتوانید دیتای ارسالی از پنل را در سرویس مورد نظر را دریافت کنید.

Sub Service_Start (StartingIntent As Intent)


     Log(StartingIntent.GetExtra("me.cheshmak.data"))

End Sub