نصب سریع


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

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


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


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

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


sdk

نکته اول: همیشه سعی بر استفاده از آخرین نسخه 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.0.+'
            

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

نحوه اضافه کردن gcm

https://developers.google.com/android/guides/setup#add_google_play_services_to_your_project

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

۴. استفاده از api چشمک


در این قسمت راهنمای سریع پیکربندی و استفاده از چشمک را مشاهده میفرمایید

برای استفاده از چشمک باید کدهای راه اندازی زیر را در کلاس 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);
              
            

کد نمونه و برنامه دمو


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

سورس کد برنامه دمو

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

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

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

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

هنگام دریافت پیغام پوش یکی از 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>
              
            

ساختار bundle فرستاده شده در پیغام پوش:

در پنل سایت شما دیتای ساخته شده توسط شما دارای ساختار 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
}
              
            

ارسال پوش تست

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

                
Cheshmak.isTestDevice(true);
                
              

و جهت پاک کردن این دستگاه از لیست دستگاه های تست به شکل زیر عمل نمایید
                
Cheshmak.isTestDevice(false);
                
              

توجه خیلی مهم: این امکان تنها برای حالت توسعه باید استفاده گردد و این کد باید جهت نسخه نهایی حذف شود


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


در چشمک این قابلیت وجود دارد تا پس از این که پوش نوتیفیکیشن را ارسال کردید هیچ نوتیفیکیشنی به کاربر نمایش داده نشود، بلکه تنها یک سرویس که توسط خودتان در اپلیکیشن مربوطه کانفیگ شده است اجرا شود و یک داده 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");

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


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


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

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


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


              
//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);
              
            

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

تگ چیست؟

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

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

شما می‌توانید هر تگی را به کاربران خود تخصیص دهید. برای مثال زمانی که یکی از کاربرانتان با پرداخت هزینه به کاربر ویژه ارتقا یافت شما می توانید تگ 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();
                
              

نکته مهم

نکته مهم: شما مجاز به استفاده از تگ is_test در برنامه خود نمی باشید. از سایر رشته های دیگر می توانید استفاده کنید.


ارسال خطاها

بخش مهمی از اطلاعاتی که یک برنامه نویس برای برنامه خود بدان نیازمند است خطاهایی است که در برنامه ممکن است روی دهد . با توجه به اینکه تعداد گوشی های اندروید و همچنین نسخه های آن زیاد است اهمیت آن دو چندان میشود . برای ارسال خطاها در اس دی کی چشمک چند روش وجود دارد که به شرح زیر است : نکته :در چشمک دو نوع خطا مشخص شده : مدیریت شده و مدیریت نشده . این خطاها بر اساس اولویت ای که خود برنامه نویس از خطا دارد دسته بندی شده و قابل تفکیک میباشد . به صورت پیشفرض تمام خطا ها به صورت مدیریت شده هستند .این مقادیر میتواند بوسیله یک 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");
}