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 خود برنامه اضافه نکنید و در پروژه کلی تان اضافه کنید.

allprojects {
    repositories {
        google()
        jcenter()
        maven {
            url 'https://repository.cheshmak.me'
        }
    }
}

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

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

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

کد زیر را در متد 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>

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

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

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

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

رفع تداخل با فایربیس و سایر سرویس دهندگان

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

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

الف) حذف تمامی سرویس‌های دریافت کننده

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

<service 
    android:name="me.cheshmak.android.sdk.core.push.CheshmakFirebaseMessagingService" 
    tools:node="remove" />

ممکن است اندروید استودیو به tools:node خطا نمایش دهد. در این صورت نیاز بوده تا تگ manifest در ابتدای فایل آن را تعریف کنید:

<manifest ...
    xmlns:tools="http://schemas.android.com/tools">

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

یک کلاس جدید ایجاد کرده و از کلاس CheshmakFirebaseMessagingService اکستند کنید. در صورتی که خودتان قبلا کلاس دریافت کننده پوش داشتید کافی است تا تنها از این کلاس extend کنید.

حال نیاز بوده تا تابع onMessageReceived در این کلاس را override کنید. در این کلاس، چشمک متدی را در اختیار شما قرار داده است تا به راحتی پیام‌هایی که مختص چشمک است را از سایر پیام‌ها جدا کنید. این تابع isCheshmakMessage نام دارد. در صورتی که message مختص چشمک باشد نیاز بوده تا onMessageReceived در کلاس parent را فراخوانی کنید(تا پوش به دست کتابخانه چشمک برسد و آن را پردازش کند) در غیر این صورت پوش برای چشمک نبوده و نیاز بوده تا خودتان پوش را پردازش کنید. به مثال زیر توجه کنید:

public class MyFcmService extends CheshmakFirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        if(isCheshmakMessage(remoteMessage)){
            super.onMessageReceived(remoteMessage);
        } else {
            // process your message. It's not for Cheshmak
        }

    }
}

مهم: در صورتی که هر یک از متد های دیگر این کلاس را Override کردید حتما تابع super مربوطه از آن را نیز فراخوانی کنید. برای مثال به کد زیر توجه کنید:

    @Override
    public void onNewToken(String s) {
        super.onNewToken(s); //make sure you call super.onNewToken here
        //do your work here
    }

ج) افزودن سرویس به مانیفست

در این مرحله سرویس ایجاد شده را به مانیفست در تگ اپلیکیشن اضافه می‌کنیم تا بتواند پوش نوتیفیکیشن ها را با موفقیت دریافت کنید. برای مثال:

<service android:name=".MyFcmService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

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

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

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

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

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

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

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

ریموت کانفیگ

با استفاده از امکان ریموت کانفیگ چشمک شما می‌توانید یک JSON را به صورت key-value از طریق پنل چشمک تنظیم نموده و هر یک از کلیدها و مقادیر آن را در کد کلاینت اندروید خود دریافت نمایید.

این امکان به اپلیکیشن شما این قابلیت را می‌دهد تا بتوانید قسمت‌های قابل تنظیم اپلیکیشن خود را از طریق چشمک تنظیم نمایید. به عنوان مثال می‌توانید یک آپشن با نام bgColor در برنامه خود قرار داده و آن را در پنل چشمک خود در منوی کانفیگ تنظیم نمایید و هر بار که مایل بودید رنگ پس‌زمینه اپلیکیشن خود را تغییر دهید.

به منظور دریافت مقادیر کانفیگ‌ها می‌توانید از کلاس CheshmakConfig استفاده کنید. تمامی متدهای این کلاس از نوع static بوده و نیازی به new کردن این کلاس ندارید. متد‌های این کلاس به صورت زیر می‌باشند:

Double myNumber = CheshmakConfig.getDouble("myNumber", 0.0);
Integer myInt = CheshmakConfig.getInt("myInt", 105);
Long myLong = CheshmakConfig.getLong("mylong", 222222222L);
String bgColor = CheshmakConfig.getString("bgColor", "#FFFFFF");
Boolean myBool = CheshmakConfig.getBoolean("myBool", false);

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

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

سوال: آیا نیاز است کدی را پیاده سازی کنم تا کانفیگ از سرورهای چشمک دریافت شود؟
پاسخ: خیر. sdk چشمک این کار را انجام داده و در صورت تغییر کانفیگ آن را دریافت می‌کند.