راه‌اندازی

پس از طی کردن مراحل صفحه پیش‌نیازها، می‌توانید راه‌اندازی SDK چابک را شروع کنید. در ابتدا شما باید کتابخانه چابک را نصب کنید و سپس برای فعالسازی پوش‌نوتیفیکیشن چابک بخش‌ افزودن GcmReceiver به فایل Manifest را مطالعه کرده و همانند مستندات بیان شده پیش بروید. در انتها، مقداردهی و راه‌اندازی کتابخانه چابک را در اپلیکیشنتان انجام دهید و برای شناخت کاربر توسط چابک، مرحله ثبت کاربر را حتما پشت سر بگذارید.

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

۱- نصب کتابخانه

۲- افزودن GcmReceiver به فایل Manifest

۳- مقداردهی اولیه (Initialize)

۴- ثبت کاربر (Register)


۱- نصب کتابخانه

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

buildscript {
  repositories {
    jcenter()
  }
}  

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

نصب کتابخانه استاندارد چابک

برای استفاده از کتابخانه استاندارد چابک (بدون قابلیت مکان‌یابی) از کتابخانه chabok-lib که در زیر به آن اشاره‌ شده است، استفاده کنید. فایل build.gradle در مسیر app را باز کرده و در بخش dependencies خط زیر را اضافه نمایید:

dependencies {
    compile 'me.leolin:ShortcutBadger:1.1.22@aar'
    compile 'com.adpdigital.push:chabok-lib:VERSION'

    //If you want to get the push notification, add to dependencies
    compile 'com.google.android.gms:play-services-gcm:10.2.6' 
}

نصب کتابخانه با قابلیت مکان‌یابی چابک

درصورتی که در برنامه خود نیاز به استفاده از موقعیت مکانی کاربر دارید، لازم است در ابتدا کتابخانه chabok-lib را حذف و کتابخانه chabok-lib-geo را جایگزین کنید. با توجه به این که در این کتابخانه از سرویس فیوز گوگل استفاده شده است باید تغییرات زیر نیز در قسمت ‌‌‌dependencies اعمال شود:

dependencies {
   compile 'me.leolin:ShortcutBadger:1.1.22@aar'
   compile 'com.adpdigital.push:chabok-lib-geo:VERSION'
   compile 'com.google.android.gms:play-services-location:10.2.6'

  //If you want to get the push notification, add to dependencies
   compile 'com.google.android.gms:play-services-gcm:10.2.6'
}  

نکات ضروری نصب کتابخانه

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

نکته: برای گوشی‌هایی مانند شیاومی و هواوی که گزینه تنظیمات مربوط به برنامه‌های حفاظت شده دارند (ProtectedApps) کاربر باید برنامه شما را در لیست برنامه‌های حفاظت شده، فعال کند تا دریافت پوش‌نوتیفیکیشن در همه حالت‌ها امکان‌پذیر شود. برای اطلاعات بیشتر می‌توانید بخش عیب‌یابی را مطالعه نمایید.

  • برای استفاده از سرویس GCM گوگل (پوش‌نوتیفیکیشن) لازم است play-services-gcm را همانند بالا (خط آخر هر دو کتابخانه) در بخش dependencies اضافه کنید.

  • دقت داشته باشید که همیشه از جدیدترین نسخه ShortcutBadger استفاده کنید. برای اطلاع از آخرین نسخه می‌توانید به این لینک مراجعه نمایید. همچنین با توجه به حجم زیاد مجوزهای نمایش نشان (Badge) روی آیکون اپ،‌ می‌توانید از این قسمت هر کدام از آن‌ها را با اختیار خودتان بردارید.

  • به علت محدودیت‌‌های اندروید ۸ به بالا دقت کنید حتما مطابق جدول زیر تنظیمات نسخه‌ها را به درستی انجام دهید. در صورت رعایت نکردن نسخه‌های ذکر شده در جدول زیر هنگامی که اپلیکیشنتان kill شده باشد به هنگام دریافت نوتیفیکیشن با خطا مواجه خواهد شد.

buildTools compileSdk targetSdk googlePlayServices
25.x.x 25 >= 23 >= 9.6.0
26.x.x 26 >= 23 >= 9.6.0
27.x.x 27 >= 23 >= 10.2.1
  • توجه داشته باشید که برای VERSION آخرین نسخه کتابخانه را از این صفحه مشاهده کنید و سپس آن را وارد نمایید، همچنین توصیه می‌شود بخش مدل نسخه‌گذاری در چابک را مطالعه نمایید.

نصب دستی کتابخانه

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

مدل نسخه‌گذاری در چابک (Semantic Versioning)

چابک از مدل نسخه‌گذاری MAJOR.MINOR.PATCH استفاده می‌کند. همه تغییرات نسخه‌ها بلافاصله پس از انتشارشان به صورت موردی در صفحه لیست تغییرات برای اطلاع شما اضافه می‌شوند. برای همین توصیه می‌کنیم این صفحه را حتما مطالعه نمایید. این موارد برای هر نسخه در دو بخش ارتقا (در صورت وجود ارتقا) و تغییرات برای شما نمایش داده شده‌ است.

  • Patch: تغییرات در این سطح شامل Bug Fix و قابلیت‌های بسیار کوچک می‌باشد. به روز رسانی به این نسخه‌ها نیاز به تغییری در کد ندارد. برای آگاهی از آن‌ها، باید بخش تغییرات را مطالعه کنید. به عنوان مثال به‌ روز رسانی کتابخانه چابک از نسخه 2.13.0 به نسخه 2.13.2 مربوط به این سطح می‌شود.
  • Minor: تغییرات در این سطح شامل قابلیت‌های بزرگتر و تغییر در کارکرد (Functionality) کتابخانه می‌شود. در به روز رسانی به این نسخه‌ها حتما باید بخش ارتقا و تغییرات صفحه لیست تغییرات را با دقت مطالعه کنید. در صورت بروز هر گونه مشکل در نتیجه رعایت نکردن نکات بخش ارتقا و تغییرات در به روز رسانی به نسخه‌های Minor، تیم چابک مسئولیتی را نمی‌پذیرد. توصیه می‌کنیم که هر سه تا شش ماه اقدام به بررسی نسخه‌های Minor نمایید. به عنوان مثال به‌ روز رسانی کتابخانه چابک از نسخه 2.12.1 به نسخه 2.13.2 مربوط به این سطح می‌شود.
  • Major: این سطح از تغییرات مخصوص بازنویسی و یا تغییرات اساسی در کتابخانه چابک است. در به روز رسانی به این نسخه‌ها حتما باید بخش ارتقا و تغییرات تغییرات صفحه لیست تغییرات را با دقت مطالعه کنید. در صورت بروز هر گونه مشکل در نتیجه رعایت نکردن نکات بخش ارتقا و تغییرات در به روز رسانی به نسخه‌های Major، تیم چابک مسئولیتی را نمی‌پذیرد. بنابراین توصیه می‌کنیم که هر یک سال اقدام به بررسی نسخه‌های Major نمایید. به عنوان مثال به‌روزرسانی کتابخانه چابک از نسخه 1.0.1 به نسخه 2.13.2 مربوط به این سطح می‌شود.

نکته: توصیه می‌کنیم برای دریافت آخرین نسخه Bug Fixها از کاراکتر + (wildcard) استفاده نمایید تا gradle به صورت خودکار نسخه‌های patch را بیاورد.


۲- افزودن کلاس GcmReceiver به فایل Manifest

برای دریافت پوش‌نوتیفیکیشن باید GcmReceiver را در کلاس Application به فایل AndroidManifest.xml اضافه نمایید تا بتوانید پوش‌نوتیفیکیشن‌هایی که از طریق سرور‌های گوگل ارسال می شوند را نیز دریافت کنید.

<application
    android:name=".MY_APPLICATION_CLASS_NAME"
    ... >
	
	...
    <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="MY_APPLICATION_PACKAGE_ID" />
        </intent-filter>
    </receiver>
	
</application>

در صورتی که برنامه شما کلاس Application ندارد با استفاده از راهنمای ارائه شده در این پست، آن را ایجاد کنید.

نکته: با توجه به حجم زیاد مجوزهای نمایش نشان (Badge) روی آیکون اپ،‌ می‌توانید از این قسمت هر کدام از آن‌ها را با اختیار خودتان بردارید.


۳- مقداردهی اولیه (Initialize)

چابک برای راه‌اندازی نیاز به مقداردهی اولیه دارد. متد init چابک باید در کلاس Application در متد onCreate تحت هر شرایطی فراخوانی شود.

public class MyAppClass extends Application {

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

        //AdpPushClient.init() should always be called in onCreate of Application class
        AdpPushClient.init(
                getApplicationContext(),
                MY_ACTIVITY.class,
                "APP_ID/SENDER_ID", //based on your environment
                "API_KEY",          //based on your environment
                "SDK_USERNAME",     //based on your environment
                "SDK_PASSWORD"      //based on your environment
        );

        //true connects to Sandbox environment
        //false connects to Production environment
        AdpPushClient.get().setDevelopment(DEV_MODE);
    }
    
    @Override
    public void onTerminate() {
        if (AdpPushClient.get() != null) {
            AdpPushClient.get().dismiss();
        }

        super.onTerminate();
    }
}

در این متد به جای پارامتر‌های APP_ID/SENDER_ID, API_KEY(SDK_KEY), SDK_USERNAME, SDK_PASSWORD مقادیر مربوط به حساب چابک خود را وارد نمایید. نحوه ایجاد حساب در بخش پیش‌نیازها توضیح داده شده است. در صورت داشتن حساب چابک هم می‌توانید این مقادیر را از پنل بخش تنظیمات قسمت دسترسی‌ و توکن‌ها بردارید.

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

مقدار SENDER_ID در پارامتر APP_ID/SENDER_ID همان شناسه گوگل برای دریافت پوش‌نوتیفیکیشن می‌باشد که در پنل در بخش تنظیمات پلتفرم اندروید قرار داده‌اید و APP_ID همان APP_ID‌ای که در پنل در بخش دسترسی و توکن‌ها قرار داده شده است، می‌باشد.

نکته: توجه داشته باشید متد AdpPushClient.init تحت هر شرایط حتما باید در کلاس Application و در متد onCreate فراخوانی شود. متد فوق برای مقداردهی پارامتر‌های ضروری چابک می‌باشد و در صورت عدم فراخوانی آن در حالت بسته (Kill) بودن اپلیکیشن، با خطا مواجه خواهید شد.

متد setDevelopment تعیین می‌کند که اپلیکیشن شما به محیط آزمایشی (Sandbox) و یا عملیاتی (Production) چابک متصل شود. این موضوع بستگی به این دارد که حساب کاربری شما روی کدام محیط تعریف شده باشد. مقدار true به محیط آزمایشی و مقدارfalse به محیط عملیاتی متصل می‌شود. در نظر داشته باشید، هر محیط به کلیدهای دسترسی (AppId, APIKey, Username و Password) خودش در متد init نیاز دارد. بنابراین در صورت تغییر مقدار setDevelopment کلید‌های دسترسی آن هم باید تغییر داده شود.

AdpPushClient.get().setDevelopment(DEV_MODE);

نکته: برای درخواست حساب محیط عملیاتی، در بخش تنظیمات پنل، وارد بخش درخواست حساب عملیاتی شوید و درخواست خود را ثبت نمایید تا پس از تایید و ساخت حساب عملیاتی شما، اطلاعات جدید حسابتان (AppId, APIKey, Username و Password) تعیین گردد.

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

AdpPushClient.get().dismiss();


۴- ثبت کاربر (Register)

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

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

  • امضای اول فقط شناسه کاربر را گرفته و کاربر را با آن شناسه روی سرور چابک ثبت نام می‌کند.
AdpPushClient.get().register("USER_ID");

به عنوان مثال اگر اپلیکیشن شما دارای صفحه ورود و ثبت‌نام می‌باشد، متد register را در صفحه ورود یا ثبت‌نام پس از احراز هویت کاربر و همچنین، پس از هر بار اجرای (در کلاس Application متد onCreate) اپلیکیشن فراخوانی کنید تا کاربر به سرور چابک متصل شود.

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

    ...
    
    String userId = AdpPushClient.get().getUserId();
    
    if (userId != null && !userId.isEmpty()) {
        AdpPushClient.get().register(userId);
    } else {

        //If user is not registered verify the user and
        //call AdpPushClient.get().register("USER_ID") method at login page
        AdpPushClient.get().register("USER_ID");
    }
}

نکته: کاراکترهای ‍#,+,*,\,/ و فاصله در USER_ID مجاز نیستند، همچنین طول این رشته نباید کمتر از ۳ و بیشتر از ۳۲ کاراکتر باشد.

نکته امنیتی: مقدار USER_ID را هرگز به صورت خام در SharedPreferences ذخیره نکنید، چون این مقدار شناسه معنادار می‌باشد و می‌توان با آن کاربر را روی چابک ثبت‌نام کرد. برای این منظور می‌توانید از متد getUserId چابک استفاده کنید که شناسه کاربر را به صورت رمزنگاری شده نگه‌می‌دارد. همینطور می‌توانید قبل از عملیات ثبت با استفاده از شماره گوشی از معتبر بودن کاربر (verfication) اطمینان یابید، سپس شناسه او را ثبت نمایید.

  • امضای دوم علاوه بر شناسه کاربر، لیستی از نام‌ کانال‌هایی (برای آشنایی با مفهوم کانال و کاربرد آن این قسمت را مطالعه نمایید) که کاربر باید روی آن‌ها عضو شود را نیز دریافت می‌کند. با عضویت روی کانال‌های داده شده، کاربر قادر به دریافت پیام‌های ارسالی روی آن‌ کانال‌ها خواهد بود.
AdpPushClient.get().register("USER_ID", new String[]{"CHANNEL_NAME1", "CHANNEL_NAME2", ...});

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

دریافت وضعیت ثبت کاربر

برای اطمینان از ثبت شدن کاربر در چابک، می‌توانید از متد isRegistered یا رویداد AppState استفاده کنید.

AdpPushClient.get().isRegistered();

با رویداد AppState می‌توانید در این بخش جزئیات بیشتری از کاربرتان را مشاهده کنید.

public void onEvent(AppState state) {
    if (state == AppState.REGISTERED) {
        //User successfully registered.
        Log.d(TAG, "User successfully registered.");
    } else {
        Log.d(TAG, "onEvent: The app state is " + state);
    }
}

حذف کاربر (Unregister)

برای حذف دستگاه کاربر از سرور چابک می‌توانید از متد unregister استفاده کنید. پس از حذف کاربر، چابک دیگر به دستگاه‌های آن userId پوش ارسال نخواهد کرد. توصیه می‌شود این متد را زمانی که کاربر در اپلیکیشنتان از حساب خود خارج می‌شود (Logout) فراخوانی کنید. این امر باعث می‌شود تا کاربر از حفظ شدن حریم شخصی خود پس از خروج از حساب کاربری اطمینان یابد. پس از آن هم کاربر را به عنوان یک کاربر مهمان register کنید تا همچنان با او تعامل داشته باشید.

AdpPushClient.get().unregister();

نکته: تمامی مراحلی که در این راهنما بیان شده، در یک پروژه starter پیاده‌سازی شده است.