چابک

مفاهیم اولیه

پوش (Push)

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


کانال (Channel)

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


عضویت در کانال‌ها (Subscribe)

عمل ثبت نام کردن یک کلاینت روی یک کانال خاص برای دریافت پیام‌های ارسالی به آن کانال subscribe نامیده می‌شود و عمل برعکس آن unsubscribe نامیده می‌شود.


ارسال پیام (Publish)

اپلیکیشن می تواند با استفاده از کلاینت چابک، به سمت سرور اطلاعات ارسال نماید. عمل ارسال پیام از کلاینت به سرور publish نامیده می‌شود.


افزودن کتابخانه چابک به پروژه

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

۱. افزودن کتابخانه چابک از طریق jcenter

برای این منظور ابتدا در فایل gradle اصلی پروژه بایستی jcenter را بعنوان repository اضافه نمایید، مطابق نمونه زیر:

                
buildscript {
  repositories {
    jcenter()
  }
}
                
            

حالا فایل build.gradle در مسیر app را بازکرده و در بخش dependencies خط زیر را وارد نمایید:

                
dependencies {
    compile 'com.adpdigital.push:chabok-lib:LATEST_CHABOK_VERSION'
}
                
            



۲. افزودن دستی فایل کتابخانه

چنانچه قصد استفاده از jcenter را ندارید، می توانید آخرین نسخه فایل کتابخانه چابک را از اینجا دانلود کرده، سپس در پوشه‌ای با نام aars در داخل پوشه اصلی پروژه خود قرار دهید:
project/app/aars
سپس خط زیر را در بخش dependencies فایل گریدل پروژه بیافزایید:

                
dependencies {
    compile(name: 'chabok-lib-2.6.3', ext: 'aar')
}
                
            

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


تغییرات لازم در فایل manifest

۱. کدهای زیر را به فایل AndroidManifest.xml پروژه اضافه کنید:
دربخش مجوز‌ها موارد زیر را اضافه کرده و نام کلاس Application خود را نیز بجای YOUR_APPLICATION_CLASS_NAME وارد کنید. عبارت YOUR_APPLICATION_PACKAGE_ID را با نام پکیج برنامه خود جایگزین کنید.

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="YOUR_APPLICATION_PACKAGE_ID"> <permission android:name="YOUR_APPLICATION_PACKAGE_ID.permission.C2D_MESSAGE" android:protectionLevel="signature"/> <uses-permission android:name="YOUR_APPLICATION_PACKAGE_ID.permission.C2D_MESSAGE" /> <application android:name=".YOUR_APPLICATION_CLASS_NAME" android:allowBackup="true" android:icon="@drawable/ic_launcher" android:label="@string/app_name" android:theme="@style/AppTheme"> ... </application>


۲. کلاس رسیور PushMessageReceiver را نیز به پروژه خود اضافه نمایید.

<receiver android:name="PushMessageReceiver"> <intent-filter> <category android:name="YOUR_APPLICATION_PACKAGE_ID"/> <action android:name="com.adpdigital.push.client.MSGRECEIVE"/> </intent-filter> </receiver>


۳. رسیور GcmReceiver را به ترتیب زیر تعریف کنید تا بتوانید نوتیفیکیشن‌هایی که از طریق سرور‌های گوگل ارسال می شوند را نیز دریافت کنید.

<receiver android:name="com.google.android.gms.gcm.GcmReceiver" android:enabled="true" android:exported="true" android:permission="com.google.android.c2dm.permission.SEND"> <intent-filter> <action android:name="com.google.android.c2dm.intent.RECEIVE" /> <action android:name="com.google.android.c2dm.intent.REGISTRATION" /> <category android:name=" YOUR_APPLICATION_PACKAGE_ID" /> </intent-filter> </receiver>




نمونه‌سازی و مقداردهی اولیه

۱. برای دریافت یا ارسال پیام از/به سرور چابک، بایستی یک نمونه از کلاس AdpPushClient بسازید و آن را مقداردهی نمایید. یکی از بهترین روش‌ها برای ساختن کلاینت چابک استفاده از کلاس اپلیکیشن پروژه شماست. برای این منظور در متد onCreate کدهای زیر را اضافه کنید. در صورتی که برنامه شما کلاس Application ندارد آن را ایجاد کنید.

                
private AdpPushClient chabok = AdpPushClient.init(
        getApplicationContext(),
        YOUR_MAIN_ACTIVITY_CLASS.class,
        YOUR_APP_ID,
        YOUR_API_KEY,
        SDK_USERNAME,
        SDK_PASSWORD
);
                
            

با استفاده از متد init یک نمونه از AdpPushClient مقدار دهی اولیه می شود. در این متد بجای پارامتر‌های YOUR_APP_ID, YOUR_API_KEY, SDK_USERNAME, SDK_PASSWORD مقادیر مربوط به حساب چابک خود را وارد نمایید.
به عنوان مثال به کد زیر توجه کنید که همیشه یک سینگلتن از کلاس AdpPushClient را مدیریت می‌کند.
در کد زیر متد getPushClient برای نمونه گیری و تنظیمات مربوط به AdpPushClient تعریف شده است، شما کافیست بجای YOUR_MAIN_ACTIVITY_CLASS نام اکتیویتی اصلی (چابک به طور پیش‌فرض بعد از کلیک شدن روی نوتیفیکیشن، این اکتیویتی را باز می‌کند) خود را قرار دهید.

                
public class YourAppClass extends Application {

  private AdpPushClient chabok = null;

  @Override
  public void onCreate() {
    super.onCreate();
    getPushClient();
  }

  public synchronized AdpPushClient getPushClient() {
    if (chabok == null) {
        chabok = AdpPushClient.init(
            getApplicationContext(),
            YOUR_MAIN_ACTIVITY_CLASS.class,
            YOUR_APP_ID,
            YOUR_API_KEY,
            SDK_USERNAME,
            SDK_PASSWORD
        );
        chabok.setDevelopment(DEV_MODE);
        chabok.register(USER_ID, new String[]{CHANNEL_NAME});
    }
    return chabok;
  }
}
                
            

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

متد setDevelopment

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

متد register

با دو امضای متفاوت وجود دارد:
امضای اول که تنها شناسه کاربر را گرفته و کاربر را با آن شناسه روی سرور چابک ثبت نام میکند.
chabok.register(USER_ID);
امضای دوم که علاوه بر شناسه کاربر، لیستی از نام‌ کانال‌هایی که کاربر باید روی آن‌ها عضو شود را نیز دریافت می کند. با ثبت نام در این کانال‌ها کاربر پیام‌های ارسالی روی آن‌ها را دریافت خواهد نمود.
chabok.register(USER_ID, new String[]{CHANNEL_NAME1, CHANNEL_NAME2, ...});
متغیر USER_ID شناسه کاربر برای ثبت نام در چابک می‌باشد و ارسال پیام‌ به کاربران توسط همین شناسه‌ها و بدون استفاده از توکن یا شناسه گوشی، به سادگی امکان پذیر خواهد بود شناسه کاربری می تواند هر فیلد باارزش و معنا‌دار برای کسب و کار شما باشد که کاربر خود را با آن شناسایی می‌کنید. شماره موبایل، کدملی، شماره حساب و یا ایمیل مثال‌هایی از شناسه‌های کاربری مناسب در موارد واقعی هستند.

متد dismiss

در متد onTerminate کلاس اپلیکیشن (یا اگر بجای کلاس اپلیکیشن از یک اکتیویتی برای مدیریت کلاینت استفاده می کنید در متد onDestroy) که در واقع آخرین فراخوانی در چرخه حیات این کلاس است، متد dismiss از کلاینت چابک را فراخوانی نمایید تا منابع در اختیار آزاد شوند. واضح است بعد از فراخوانی این متد دیگر نمی توان از نمونه جاری کلاینت استفاده کرد و باید دوباره نمونه‌سازی کنید.

                
@Override
public void onTerminate() {
    chabok.dismiss();
    super.onTerminate();
}
                
            



وضعیت اتصال به چابک

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

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

                
public void onEvent(ConnectionStatus status) {
    // status can be one of
    // NOT_INITIALIZED
    // CONNECTING
    // CONNECTED
    // DISCONNECTED
}
                
            

شما این متد را در هر کلاسی که نیاز داشته باشید می‌توانید پیاده‌سازی کنید، فقط کافیست شیء‌ای از آن کلاس را با استفاده از متد addListener به کلاینت اضافه کنید تا کتابخانه در زمان مورد نیاز متد شما را فراخوانی کند.
chabok.addListener(this)
شما به همین سبک و با پیاده‌سازی متد onEvent با پارامتر‌های متفاوت، رویداد‌های دیگری را نیز از کلاینت چابک می‌توانید دریافت کنید. انواع رویدادهایی که از طریق کلاینت چابک به آنها دسترسی دارید صورت زیر می باشد:

دریافت تعداد پیام‌های جدید

                
public void onEvent(BadgeUpdate badgeUpdate) {
}
                
            

دریافت پیام جدید چابک

                
public void onEvent(PushMessage pushMessage) {
}
                
            

دریافت تایید تحویل پیام چابک ارسال شده

                
public void onEvent(DeliveryMessage message) {
}
                
            




روش دیگر، استفاده از متد getStatus برای استعلام وضعیت اتصال است.

                
chabok.getStatus(new Callback() {
    @Override
    public void onSuccess(ConnectionStatus connectionStatus) {
        // check connectionStatus enum
    }

    @Override
    public void onFailure(Throwable throwable) {
        // Oh! No :(
    }
});
                
            

همچنین متد دیگری به نام isConnected وجود دارد که با استفاده از آن می‌توان در یافت که آیا اتصال به سرور چابک برقرار است یا خیر:

                
if(chabok.isConnected()) {
	// Hooooorah! :)
}
                
            


دریافت پیام چابک

شما می‌توانید از طریق یک رسیور پیام‌های جدید چابک را دریافت نمایید. برای این منظور کلاسی با همان نامی که در manifest استفاده کردید مثل PushMessageReceiver ایجاد نمایید که فرزند WakefulBroadcastReceiver باشد.

                
public class PushMessageReceiver extends WakefulBroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {
        Bundle messageData = intent.getExtras();
        String channel = messageData.getString(AdpPushClient.PUSH_MSG_RECEIVED_TOPIC);
        String body = messageData.getString(AdpPushClient.PUSH_MSG_RECEIVED_MSG);
        PushMessage push = PushMessage.fromJson(body, channel);
        handleNewMessage(push);
        completeWakefulIntent(intent);
    }


    private void handleNewMessage(PushMessage message) {
        // write your code to handle new message
    }


}
                
            




شخصی‌سازی نمایش اعلان

کلاینت چابک به طور پیش‌فرض برای پیام‌های دریافتی اعلان (نوتیفیکیشن) نمایش می‌دهد. درصورت تمایل به شخصی‌سازی نوتیفیکیشن‌ها، کد شخصی‌سازی مورد نظر خود را می‌توانید به کلاینت اضافه کنید.
برای شخصی سازی می بایستی یک شیء از نوع NotificationHandler نمونه سازی کنید، مانند نمونه زیر:

                
NotificationHandler myHandler = new NotificationHandler() {

    @Override
    public Class getActivityClass(ChabokNotification chabokNotification) {
        // return preferred activity class to be opened on this message's notification
        return YOUR_MAIN_ACTIVITY_CLASS.class;
    }

    @Override
    public boolean buildNotification(ChabokNotification chabokNotification, NotificationCompat.Builder builder) {
        // use builder to customize the notification object
        // return false to prevent this notification to be shown to the user, otherwise true
        return false;
    }
};

chabok.addNotificationHandler(myHandler);
                
            

در متد buildNotification با پارامترهای ورودی متد یعنی ChabokNotification و NotificationCompat.Builder می توانید نوتیفیکیشن دریافتی را به دلخواه تغییر داده و درباره نمایش آن تصمیم بگیرید. در صورتی که مقدار بازگشتی از این متد true باشد، کتابخانه با توجه به تنظیمات مربوطه نوتیفیکیشن را نمایش می دهد ولی اگر مقدار بازگشتی false باشد بدین معنی است که شما خود نمایش را به عهده می گیرید.





عضویت روی کانال‌ها

عضویت یک کاربر روی یک کانال برای دریافت پیام‌های ارسالی روی آن کانال subscribe نامیده می شود و لغو آن unsubscribe نامیده می شود. چابک به طور پیش فرض هر کاربر را روی یک کانال شخصی (بر اساس شناسه کاربر) و یک کانال گروهی (همه کاربران) ثبت نام می‌کند.





ارسال وضعیت پیام‌های دریافتی

شما می‌توانید عکس‌العمل کاربر به یک پیام چابک را (خوانده شدن، نادیده گرفته شدن، ...) با استفاده از کلاینت چابک مشخص کنید.
متد markAsRead برای ارسال رویداد خوانده شدن پیام توسط کاربر به سرور می تواند مورد استفاده قرار بگیرد.
متد dismiss نیز می‌تواند برای هر عملی که معنی باز نکردن یا نادیده گرفته شدن پیام را داشته باشد بکار رود. به دو طریق می توان این متدها را فراخوانی نمود:
۱. اگر شی پیام چابک در دسترس است به صورت مستقیم متد را فراخوانی کنید:

                
pushMessage.markAsRead();
pushMessage.dismiss();
                
            

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

                
PushMessage.markAsRead("PUSH_MESSAGE_ID");
PushMessage.messageDismissed("PUSH_MESSAGE_ID");
                
            




ارسال پیام

متد Publish برای ارسال پیام از سمت کلاینت به سرور‌های چابک استفاده می‌شود. شما از این مکانیزم علاوه بر پیام‌های شخصی می‌توانید برای ارسال اطلاعات و داده‌های کاربر به سمت سرور خود (بجای ارسال با درخواست‌های کلاسیک HTTP) استفاده کنید. مزایای این روش در مقایسه با درخواست‌های کلاسیک HTTP به صورت زیر می باشد:

  • روی اتصال موجود چابک می‌توانید تعداد زیادی رویداد سمت سرور بفرستید، در واقع برای هر درخواست یک اتصال جدید ساخته نمی‌شود.
  • تحویل اطلاعات را در سمت سرور، حتی در شرایطی که کاربر اینترنت ضعیف و یا قطع شده‌ای دارد، تضمین می‌کند. به این ترتیب که کلاینت چابک با استفاده از منطق سعی مجدد خود می‌تواند پیام‌ شما را حتی در شرایط بحرانی یک و فقط یک بار بفرستد.
  • بهینه تر در مصرف باطری
chabok.enableDeliveryTopic();

برای دریافت تایید تحویل پیام‌های ارسالی بایستی این ویژگی را توسط متد enableDeliveryTopic فعال نمایید. سپس با پیاده‌سازی متد onEvent می‌توانید از تحویل پیام خود مطلع شوید.





دریافت وضعیت برنامه

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

chabok.isBackground()
chabok.isForeground()

نمونه:

                
if(chabok.isForeground()) {
	// Do something on application foreground
}
                
            




مدیریت اطلاعات کاربری

شما می‌توانید اطلاعاتی دلخواه از کاربر را با در یک HashMap با استفاده از متد setUserInfo در سمت سرور چابک ذخیره کنید. با این کار در زمان رجیستر شدن کاربر روی سرور‌های چابک، این اطلاعات در سرور ذخیره می‌شوند.

                
HashMap userInfo = new HashMap<>();
userInfo.put("firstName", FIRST_NAME);
userInfo.put("lastName", LAST_NAME);
userInfo.put("email", USER_EMAIL);
userInfo.put("isMale", true);
...
chabok.setUserInfo(userInfo);
                
            

برای دریافت اطلاعات از قبل ذخیره شده کاربر نیز می توانید از متد getUserInfo استفاده نمایید،‌ بصورت زیر:

HashMap userInfo = chabok.getUserInfo();



کپی رایت © ۱۳۹۵-۱۳۹۴ ، چابک نام تجاری ثبت شده است، تمامی حقوق برای شرکت آتیه داده پرداز محفوظ می‌باشد.
با ثبت نام در خبرنامه چابک از آخرین خبر‌ها مطلع شوید.
ثبت نام
ورود به پنل کاربری
ورود به داشبورد