استفاده از چشمک در Android Studio

نصب چشمک

ویدئوی راهنمای نصب سریع چشمک در بالا آمده است. در صورت تمایل می توانید مطابق ویدئو پیش بروید و یا از طریق مراحل زیر چشمک را نصب کنید:

۱. پیش نیاز استفاده از چشمک

SDK چشمک در اندروید استودیو قابل استفاده می باشد. جهت دانلود اندروید استودیو به آدرس زیر بروید :

آخرین نسخه اندروید استودیو

جهت استفاده از چشمک از نصب بودن بسته ی Google Play Service در SDK Manager اطمینان حاصل کنید . جهت این کار ابتدا SDK Manager را از منوی Tools -> Android -> SDK Manager باز کرده و سپس مانند تصویر زیر اگر در ستون status وضعیت بسته ی Google Play Service به غیر از Installed بود آن را تیک زده و دکمه Install را جهت نصب کلیک کنید

_images/goolge_sdk.png

نکته اول: همیشه سعی بر استفاده از آخرین نسخه Google Play Service داشته باشید .

نکته دوم: چشمک از نسخه 7.5 به بالای Google Play Service استفاده میکند.

چشمک از اندروید ۲.۲ به بالا قابل استفاده میباشد .

نسخه ی ۲.۲ اندروید دارای API LEVEL 8 میباشد

۲.دسترسی‌ها

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

اینترنت

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

​<uses-permission android:name="android.permission.INTERNET" />​

ویبره دستگاه اندروید

این دسترسی باعث می شود در هنگام دریافت پوش نوتیفیکیشن توجه کاربر بیشتر جلب شود.

​<uses-permission android:name="android.permission.VIBRATE" />​

موقعیت مکانی

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

​<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />​
​<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

*نکته: تنها در صورتی این دسترسی را دریافت کنید که کاربری اپلیکیشنتان به این دسترسی نیاز داشته باشد چرا که برخی از مارکت‌های داخلی نسبت به دریافت این دسترسی‌ها و عدم کاربرد آن در اپلیکیشن شما حساس می‌باشند.

۳. تنظیم Gradle

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

۱. ابتدا در فایل build.gradle پروژه تان آدرس ریپازیتوری چشمک را وارد کنید:

repositories {
jcenter()
  //Add Maven block to your repositories section
   maven {
      url 'https://repository.cheshmak.me'
   }
}

۲. کتابخانه را به صورت dependencies به پروژه به صورت زیر اضافه نمایید:

//other dependencies
compile 'me.cheshmak:analytics:1.+'

۳.جهت استفاده از قابلیت پوش چشمک باید dependency مربوط بهgcm را به کتابخانه‌های خود اضافه نمایید نحوه اضافه کردن gcm را از این لینک ببینید.

//gcm dependency
compile 'com.google.android.gms:play-services-gcm:(Replace with LAST_VERSION number )'

۴.فراخوانی چشمک در کلاس Application

برای استفاده از چشمک باید کدهای راه اندازی زیر را در کلاس Application برنامه درون تابع onCreate اضافه کنید .اگر برنامه شما داری کلاس Application نیست از راهنمای زیر برای ایجاد آن استفاده نمایید:

چگونه کلاس Application ایجاد کنیم

CheshmakConfig config= new CheshmakConfig();
config.setIsEnableAutoActivityReports(true);
config.setIsEnableExceptionReporting(true);
Cheshmak.with(context, config);
​// OR​
​// Cheshmak.with(context);​
​// Cheshmak.configure(config);​
Cheshmak.initTracker(APP_KEY);

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

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

ارسال رویداد ها به صورت یک عنوان

با استفاده از این روش شما میتواننید رویداد ها را به صورت یک عنوان به سرور ارسال فرمایید .مثال زیر نمونه ای از این روش میباشد

//before start reading​
Cheshmak.trackEvent("start-reading");
​//I am reading now​
Cheshmak.trackEvent("end-reading");

و یا

Cheshmak.trackEvent("click-actionbar");

ارسال رویدادهای پیشرفته

گاهی اوقات ارسال تنها یک عنوان برای یک رویداد کافی نمی باشد و شما نیاز دارید داده های بیشتری را به همراه این رویداد ارسال فرمایید ، ساختار ارسال داده های اضافی در اس دی چشمک به صورت یک Map‎String, String‎ می باشد که هر رکورد در آن شامل یک key و یک value به صورت رشته ای میباشد که به همراه یک عنوان فرستاده میشود ،مثال زیر نمونه ای از این نوع ارسال رویداد میباشد :

Map<String, String> map = new HashMap<String, String>();
map.put("eventName", "clickbutton");
map.put("userRate", "4");
map.put("country", "iran");
map.put("islogin","false")
Cheshmak.trackEvent("tags", map);

استفاده از پوش نوتیفیکیشن

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

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

باز شدن Activity خاصی پس از کلیک روی پوش

برای دریافت پیغام پوش نیاز به تعیین یک Activity برای دریافت آن دارید . برای تعیین Activity مورد نظر ابتدا به AndroidManifest.xml رفته و درون تگ Activity مورد نظر ،کد meta-data زیر را وارد نمایید:

​
​<activity
android:name=".YourActivity"​
android:label="your_activity_name" >​
​<meta-data android:name="cheshmakPush" android:value="openActivityOnPush"/>​
​</activity>​

دریافت داده از پوش نوتیفیکیشن

در پنل سایت شما دیتای ساخته شده توسط شما دارای ساختار JSON میباشد و به صورت رشته با کلید me.cheshmak.data قابل دسترسی میباشد

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

پیغامی که در زیر عنوان پوش در بالای نوتیفیکیشن به عنوان توضیحات می آید با کلید message قابل دسترسی می باشد

​protected void onCreate(Bundle savedInstanceState) {
  //some code​
  Intent intent = getIntent();
  if (intent != null) {
   if (intent.getExtras() != null) {
    Toast.makeText(this,"Cheshmak push notification data"+​
    intent.getExtras().getString("me.cheshmak.data")+"\n"+​
    intent.getExtras().getString("title")+"\n"+​
    intent.getExtras().getString("message")+"\n",Toast.LENGTH_SHORT).show();
   }
  }
  //some code​
}

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

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

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

برای کانفیگ کردن اپلیکیشن خود ابتدا در فایل AndroidManifest.xml درون تگ سرویسی که می‌خواهید باز شود تگ زیر را قرار دهید:

​<meta-data  android:name="cheshmakPush" android:value="startServiceOnPush" />​

برای مثال:

​<service android:name=".MyService">​
<meta-data  android:name="cheshmakPush"​
android:value="startServiceOnPush" />​
​
​</service>​

حال درون متد onStart شما خواهید توانست مقدار JSON ای که در پنل ارسال پوش ارسال کرده‌اید دریافت کنید. مقدار JSON در فیلد me.cheshmak.data درون intent ذخیره شده است. دقت کنید که مقدار این فیلد به صورت String می باشد و نیاز است تا با استفاده از کلاسی مانند JSONObject آن را بخوانید.

برای مثال فرض کنید JSON زیر را با پنل ارسال پوش ارسال کرده اید:

{
"MyKey":"this is my test string"​
}

کد زیر نمونه کد نوشته شده برای دریافت مقدار MyKey می باشد:

@Override
​public void onStart(Intent intent, int startId) {
  super.onStart(intent, startId);
  Log.d("CHESHMAK_POPP", "SERVICE STARTED" + intent.getStringExtra("me.cheshmak.data"));
  JSONObject object=new JSONObject(intent.getStringExtra("me.cheshmak.data"));
  String myOption=object.getString("MyKey");
  ​
}

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

تگ کردن کاربران

تگ چیست؟

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

کاربرد تگ گذاری

شما می‌توانید هر تگی را به کاربران خود تخصیص دهید. برای مثال زمانی که یکی از کاربرانتان با پرداخت هزینه به کاربر ویژه ارتقا یافت شما می توانید تگ premiumUser را به این کاربر تخصیص دهید. در پنل ارسال پوش چشمک گزینه ارسال بر اساس تگ کاربران وجود دارد. به این معنی که به راحتی می‌توانید به کاربرانی پوش نوتیفیکیشن ارسال نمایید که دارای تگ‌ خاصی باشند. در این مثالا یعنی شما می توانید به کاربرانی که اپلیکیشن شما را با پرداخت درون برنامه‌ای خریداری کرده اند پوش نوتیفیکیشن ارسال نمایید.

چگونه کاربران را تگ کنیم؟

جهت تگ کردن کاربران شما می‌توانید با استفاده از تابع sendTag به صورت تکی و تابع sendTags به صورت لیستی از تگ ها برای نشان دادن در پنل استفاده کنید روش استفاده از هرکدام مانند مثال زیر است.

Cheshmak.sendTag("premiumUser");

در صورتی که بخواهید همزمان چند تگ را به یک کاربر اختصاص دهید می توانید یک List رشته به آن ارسال نمایید:

List tags = new ArrayList<String>();
 tags.add("premiumUser");
 tags.add("tagA");
 tags.add("tagB");
 Cheshmak.sendTags(tags);

چگونه تگ ها را حذف کنیم ؟

تگ های تخصیص یافته به کاربران را میتوان به دو روش تکی و چند تایی حذف کرد: روش تکی.

Cheshmak.deleteTag("premiumUser");

روش چند تایی:

List tags = new ArrayList<String>();
tags.add("premiumUser");
tags.add("tagA");
tags.add("tagB");
Cheshmak.deleteTags(tags);

پاک کردن همه تگ ها:

Cheshmak.deleteAllTags();

ارسال خطاها

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

ارسال خطا به همراه عنوان

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

try{
    //Do some buggy things​
  }
​catch (Exception ex) {
    Cheshmak.trackException("Image-resize-error",ex);
}

و یا اگر این خطا از اولویت بالایی برخوردار بود به صورت زیر ارسال شود :

try{
    //Do some buggy things​
}
​catch (Exception ex){
    Cheshmak.trackException("memory-exception-error",ex,true);
}

ارسال خطاها بدون عنوان

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

try{
    //Do some buggy things​
  }
​catch (Exception ex) {
    Cheshmak.trackException(ex);
}

و یا اگر این خطا از اولویت بالایی برخوردار بود به صورت زیر ارسال شود :

try{
    //Do some buggy things​
}
​catch (Exception ex) {
    Cheshmak.trackException(ex,true);
}

ارسال گزارش بازدید از صفحات برنامه

شما با فعال کردن قابلیت ارسال خودکار مشاهده صفحات برنامه میتوانید گزارش های مربوط به Activity هایی که کابر از آنها دیدن کرده را مشاهده فرمایید . در این قسمت در صورتی که شما از Fragment ها و یا view های خودتان استفاده میکنید میتوانید با استفاده از توابع زیر گزارش صفحات برنامه خود را برای سرور ارسال فرمایید و در داشبورد کاربری قسمت گزارش صفحات دیدن نمایید :

@Override
​public View onCreateView (LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
  //Start View​
  Cheshmak.startView("game_select_fragment");
}

و ​

@Override
​protected void onPause() {
    super.onPause();
    //EndView​
    Cheshmak.stopView("game_select_fragment");
}