راهاندازی چابک
۱. تغییرات لازم در فایل 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>
در صورتی که برنامه شما کلاس Application
ندارد با استفاده از راهنمای ارائه شده در این پست، آن را ایجاد کنید.
نکته
: با توجه به حجم زیاد مجوزهای نمایش نشان (Badge) روی آیکون اپ، میتوانید از این قسمت هر کدام از آنها را با اختیار خودتان بردارید.
۲. تعریف رسیور GcmReceiver
رسیور 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_KEY)",
"SDK_USERNAME",
"SDK_PASSWORD"
);
پارامترها
با استفاده از متد init
یک نمونه از AdpPushClient
مقداردهی اولیه می شود. در این متد بجای پارامترهای YOUR_APP_ID
, YOUR_API_KEY(SDK_KEY)
, SDK_USERNAME
, SDK_PASSWORD
مقادیر مربوط به حساب چابک خود را وارد نمایید. نحوه ایجاد حساب در بخش پیشنیازها توضیح داده شده است. در صورت داشتن حساب چابک هم میتوانید این مقادیر را از پنل بخش تنظیمات قسمت دسترسی و توکنها بردارید.
نکته
: ترکیبAPP_ID/SENDERID
به عنوانYOUR_APP_ID
مورد استفاده قرار میگیرد.
در کد زیر متد initPushClient
برای نمونهگیری و تنظیمات مربوط به AdpPushClient
تعریف شده است، شما کافیست به جای YOUR_MAIN_ACTIVITY_CLASS
نام اکتیویتی اصلی (چابک به طور پیشفرض بعد از کلیک شدن روی نوتیفیکیشن، این اکتیویتی را باز میکند) خود را قرار دهید.
نکته
: توجه داشته باشید متدAdpPushClient.init
تحت هر شرایط حتما باید در کلاسApplication
و در متدonCreate
فراخوانی شود. متد فوق برای مقداردهی پارامترهای ضروری چابک میباشد و در صورت عدم فراخوانی آن در حالت Kill بودن اپلیکیشن با خطا مواجه خواهید شد.
public class YourAppClass extends Application {
private AdpPushClient chabok = null;
@Override
public void onCreate() {
super.onCreate();
initPushClient();
String userId = chabok.getUserId();
if (userId != null && !userId.isEmpty()) {
chabok.register(userId);
}
}
private synchronized void initPushClient() {
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");
}
}
@Override
public void onTerminate() {
if (chabok != null)
chabok.dismiss();
super.onTerminate();
}
}
توضیح متدها
۱- متد setDevelopment
مشخص میکند که برنامه به محیط تستی چابک متصل شود یا به محیط عملیاتی. این موضوع بستگی به این دارد که حساب کاربری شما روی کدام محیط تعریف شده باشد.
نکته
: به طور کلی چابک شامل ۲ محیط سندباکس و عملیاتی میباشد. حسابهای رایگان چابک بر روی محیط سندباکس و حسابهای پریمیوم روی عملیاتی قرار میگیرند. مقدارtrue
برای devMode
باعث اتصال به محیط سندباکس و مقدارfalse
باعث اتصال به محیط عملیاتی ما میشود.
chabok.setDevelopment("DEV_MODE");
نکته
: مقدار پیشفرض برابرtrue
در نظر گرفته شده است. برای تغییر به محیط عملیاتی (false
) باید از پنل بخش تنظیمات درخواست خود را ثبت نمایید تا پس از تایید، اطلاعات جدید حسابتان (AppId, APIKey, Username و Password) تعیین گردد.
۲- متد register
با استفاده از این متد شما میتوانید کاربر را با شناسه کاربری وی روی سرور چابک ثبتنام نمایید. شناسه کاربر می تواند هر فیلد با ارزش و معنادار برای کسب و کار شما باشد که کاربر خود را با آن شناسایی میکنید. شماره موبایل، کدملی، شمارهحساب، ایمیل و یا حتی یک کد UUID مثالهایی از شناسههای کاربری مناسب در موارد واقعی هستند. ارسال پیام به کاربران توسط همین شناسهها و بدون استفاده از توکن یا شناسه گوشی، به سادگی امکان پذیر خواهد بود.
این متد با دو امضای متفاوت وجود دارد: امضای اول که تنها شناسه کاربر را گرفته و کاربر را با آن شناسه روی سرور چابک ثبت نام میکند.
chabok.register("USER_ID");
کاراکترهای #,+,*,\,/
و فاصله در USER_ID
مجاز نیستند، همچنین طول این رشته نباید کمتر از ۳ و بیشتر از ۳۲ کاراکتر باشد.
نکته
: هر بار که برنامه اجرا میشود لازم است این متد فراخوانی شود تا اتصال چابک برقرار گردد.
برای اعتبارسنجی شناسه کاربری میتوانید از سرویس چابک که در بخش مربوط به اعتبارسنجی توضیح داده شده، استفاده نمایید، در غیر این صورت مسئولیت احراز هویت شناسه کاربری به عهده برنامه شما به عنوان استفاده کننده از کتابخانه چابک میباشد.
اگر عملیات ثبتنام به درستی انجام شده باشد، پس از فراخوانی این متد،
اطلاعات کاربر در پنل
چابک مربوط به حساب
برنامه، در قسمت مشترکین
، قابل مشاهده خواهد بود و شما میتوانید از پنل به
کاربر مسیج
و پوش
بفرستید.
امضای دوم که علاوه بر شناسه کاربر، لیستی از نام کانالهایی که کاربر باید روی آنها عضو شود را نیز دریافت می کند. با ثبت نام در این کانالها کاربر پیامهای ارسالی روی آنها را دریافت خواهد نمود.
chabok.register("USER_ID", new String[]{"CHANNEL_NAME1", "CHANNEL_NAME2", ...});
نکته امنیتی
: مقدارUSER_ID
را هرگز به صورت خام درSharedPreferences
ذخیره نکنید، چون این مقدار شناسه معنادار میباشد و میتوان با آن کاربر را روی چابک ثبتنام کرد. برای این منظور میتوانید از متدgetUserId
چابک استفاده کنید که شناسه کاربر را به صورت رمزنگاری شده نگهمیدارد.
رویداد تایید ثبت کاربر
برای اینکه از ثبت شدن کاربرتان اطمینان یابید، میتوانید از رویداد زیر استفاده کنید. علاوه بر آن، این رویداد دادههایی مانند نصب و بازدید را در اختیار شما قرار میدهد.
public void onEvent(AppState state){
switch (state) {
case REGISTERED:
Log.d(TAG, "Registered");
break;
case INSTALL:
Log.d(TAG, "Install");
break;
case LAUNCH:
Log.d(TAG, "Launch");
break;
default:
Log.d(TAG, "Protected grant needed");
}
}
۳- متد isRegistered
به کاربر این امکان را میدهد که بررسی کند آیا عملیات ثبتنام انجام شده است یا خیر.
chabok.isRegistered();
۴- متد unregister
تمامی اطلاعات مربوط به کاربر جاری را حذف مینماید.
chabok.unregister();
۵- متد dismiss
در متد onTerminate
کلاس اپلیکیشن (یا اگر بجای کلاس اپلیکیشن از یک اکتیویتی برای مدیریت کلاینت استفاده می کنید در متد onDestroy
) که در واقع آخرین فراخوانی در چرخه حیات این کلاس است، متد dismiss
از کلاینت چابک را فراخوانی نمایید تا منابع در اختیار آزاد شوند. واضح است بعد از فراخوانی این متد دیگر نمی توان از نمونه جاری کلاینت استفاده کرد و باید دوباره نمونهسازی کنید.
@Override
public void onTerminate() {
chabok.dismiss();
super.onTerminate();
}