Android Studio - مستندات چشمک

نصب سریع چشمک

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

۱.افزودن دسترسی‌های لازم

دسترسی‌ زیر را درون Manifest برنامه خود قرار دهید.

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

دو دسترسی آخر به صورت اختیاری می‌باشد و موجب هدفمندی بیشتر تبلیغات و افزایش درآمد زایی می‌شود.

۲.تنظیم Gradle

ریپازیتوری چشمک را به فایل build.gradle در دایرکتوری اصلی پروژه اندرویدتان اضافه کنید. دقت کنید که این کد را در فایل Gradle خود برنامه اضافه نکنید و در پروژه کلی تان اضافه کنید.

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

در نهایت وابستگی چشمک را به پروژه‌تان اضافه کنید:


implementation 'me.cheshmak:analytics:3.+'
implementation "com.google.firebase:firebase-messaging:17.3.4"
implementation "com.google.firebase:firebase-ads:17.1.3"

۳.افزودن کد چشمک

کد زیر را در متد onCreate کلاس Application قرار دهید و به جای App_KEY کلید برنامه را که در پنل چشمک در دسترس می‌باشد را قرار دهید.

دقت کنید که فقط در کلاس Application این تابع را فراخوانی کنید.

Cheshmak.with(context);
Cheshmak.initTracker("APP_KEY");

۴.باز شدن برنامه پس از کلیک روی پوش

برای باز شدن برنامه نیاز است به AndroidManifest.xml رفته و درون تگ Activity اصلی برنامه ،کد meta-data زیر را وارد نمایید:

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

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

نصب‌ها قرار گرفته و پس از گذشت ۱ دقیقه می‌توانید به اپلیکیشن خود پوش نوتیفیکیشن ارسال کنید.

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

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

توضیحات بیشتر مراحل نصب

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

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

۱.افزودن دسترسی‌های لازم

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

اینترنت

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

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

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

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

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

موقعیت مکانی

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

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

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

۲.تنظیم Gradle

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

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

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

دقت کنید که این کد را به فایل build.gradle در روت فولدر پروژه اندرویدتان اضافه کنید. برای مثال کد نمونه زیر را مشاهده کنید:


buildscript {
    repositories {

        jcenter()

    }
    dependencies {
        classpath 'com.android.tools.build:gradle:2.1.2'

    }
}

allprojects {
    repositories {

        jcenter()

        maven {
            url 'https://repository.cheshmak.me'
        }

    }

}

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

//other dependencies
implementation 'me.cheshmak:analytics:3.+'

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

//FCM dependency
implementation "com.google.firebase:firebase-messaging:17.3.4"
implementation "com.google.firebase:firebase-ads:17.1.3"

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

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

Cheshmak.with(context);
Cheshmak.initTracker("APP_KEY");

به جای App_KEY کلید برنامه را که درون پنل چشمک در دسترس می‌باشد را قرار دهید.

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

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

کسب درآمد

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

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

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

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

باز شدن 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>

توجه : MyService یک سرویس ساخته شده توسط شما می باشد و هر نام دیگری می تواند داشته باشد. برای اطلاعات بیشتر در مورد ایجاد بکگراند سرویس به لینک زیر مراجعه نمایید.

https://developer.android.com/training/run-background-service/create-service.html

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

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


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

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


@Override
public int onStartCommand(Intent intent ,int flags ,int startId) {
 super.onStartCommand(intent , flags ,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");
return START_NOT_STICKY;
}

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

دریافت cheshmak ID

برای هر کاربر در هر اپلیکیشنی که SDK چشمک در آن نصب شده باشد یک شناسه منحصر به فرد به نام Cheshmak ID ساخته می‌شود. این شناسه در برنامه اندروید شما قابل دسترسی می‌باشد. شما قادر خواهید بود چشمک آی دی را به سرور خودتان ارسال کنید.

در سرور های خودتان می‌توانید با استفاده از Rest API چشمک و داشتن Cheshmak ID به کاربر مشخصی از اپلیکیشن خود پوش نوتیفیکیشن ارسال کنید.
در قطعه کد زیر نحوه دریافت Cheshmak ID در برنامه اندروید نشان داده شده است.


Cheshmak.initTracker("r035KbHW8OcMwBQhPs+Jpg==", new CheshmakCallback() {
    @Override
    public void onCheshmakIdReceived(String cheshmakID) {
        Log.e("----------", "CheshmakID = "+cheshmakID);
    }
});

در واقع در زمانی که initTracker را فراخوانی می‌کنید در پارامتر دوم callback را تعریف کرده و ما هر وقت cheshmakID در دسترس بود این تابع را صدا می‌زنیم. شما نیاز بوده تا چشمک آی دی را در اینجا دریافت کرده و به سرور خود منتقل کنید.

آیا cheshmakID تغییر می‌کند؟ عموما خیر اما اگر تحت شرایطی تغییر پیدا کرد ما این تابع را صدا خواهیم زد و شما چشمک آی دی جدیدی را دریافت خواهید کرد.

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

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

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