Befrest Android SDK Documentation


افزودن SDK به پروژه

ابتدا فایل jar بفرست را از اینجا دانلود کرده و در پوشه libraries پروژه خود قرار دهید. سپس سرویس و broadcastReceiver های داخلی بفرست را به فایل AndroidManifest درست قبل از تگ پایانی </application> اضافه کنید.

<service android:name="rest.bef.PushService" />

<receiver
   android:name="rest.bef.BefrestConnectivityChangeReceiver"
   android:enabled="false">
   <intent-filter>
       <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
   </intent-filter>
</receiver>

همچنین permission های زیر را قبل از تگ آغازی <application> اضافه کنید.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
تعریف permission مخصوص هر اپلیکیشن

جهت تامین امنیت ارسال پوش ها بین قسمت های مختلف اپلیکیشن لازم است هر اپلیکیشن یک permission مخصوص خود ساخته و از آن استفاده کند. برای این منظور کد زیر را در کنار سایر permission های برنامه در فایل AndriodManifest قرار داده و عبارت YOUR_APPLICATION_PACKAGE_NAME را که دراین تکه کد دو بار تکرار شده است، با نام پکیج برنامه خود جایگزین کنید.

<!--important! change 'YOUR_APPLICATION_PACKAGE_NAME' to your application package name in the following two lines -->
<permission android:protectionLevel="signature" android:name="YOUR_APPLICATION_PACKAGE_NAME.permission.PUSH_SERVICE" />
<uses-permission android:name="YOUR_APPLICATION_PACKAGE_NAME.permission.PUSH_SERVICE" />
دسترسی به یک instance از بفرست

برای دسترسی به توابع بفرست می توانید با استفاده از متد زیر یک instance از بفرست ایجاد کنید.

Befrest befrestInstance = BefrestFactory.getInstance(context);
تنظیم اطلاعات اتصال

برای ست کردن سه پارامتر uid ،chid و auth از متد های زیر استفاده کنید.

befrestInstance
    .setAuth(String auth)
    .setChId(String chId)
    .setUId(long uId);

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

befrestInstance.init(long uid, String auth, String chid);
توابع کنترل روند اتصال به بفرست

تابع start حتما باید بعد از تنظیم کردن پارامتر‌های UID و CHID فراخوانی شود. (ممکن است پیش از فراخوانی تابع start، رشته auth را از سرور خود دریافت نکرده باشید. در این صورت befrest به دلیل در اختیار نداشتن رشته auth، متد onAuthorizeProblem گیرنده‌ها را فراخوانی خواهد کرد.)

befrestInstance.start();

با صدا زدن تابع stop، تا زمانی که دوباره تابع start را صدا بزنید، پیام‌ها را دریافت نخواهید کرد. (با فعال کردن دوباره بفرست، همه پوش هایی که در مدت زمان توقف به کانال مورد نظر ارسال شده باشند را دریافت خواهید کرد)

befrestInstance.stop();
لطفا نکات زیر را در نظر داشته باشید:
  • صدا زدن تابع start یکبار در هر مرتبه اجرای برنامه لازم و کافی است. بنابراین بهترین مکان برای صدا زدن این تابع، متود onCreate کلاس Application است. همچنین این تابع را بعد از تغییر دادن هر یک از پارامتر‌های اتصال فراخوانی کنید تا بفرست از پارامترهای جدید برای اتصال استفاده کند.
  • بفرست اطلاعات اتصال را ذخیره می کند. در نتیجه بعد از یک مرتبه ست کردن پارامترها تنها صدا زدن start برای شروع کار بفرست در دفعات بعد کافی خواهد بود.

شیوه‌ی معمول راه اندازی بفرست بصورت زیر است:

public class BefrestApplication extends Application {

    long uId;
    String chId;
    String auth;

   @Override
   public void onCreate() {
       super.onCreate();
       BefrestFactory.getInstance(this)
                       .setChId(chId)
                       .setUId(uId)
                       .setAuth(auth)
                       .start();
   }
}
دریافت پوش‌ها

برای دریافت پوش های بفرست دو روش وجود دارد و شما میتوانید مطابق با نیاز خود از هریک از این دو روش (و یا هردو به صورت همزمان) استفاده کنید. دریافت پوش ها از طریق broadcast receiver ها و دریافت پوشها از طریق یک سرویس. استفاده از broadcast receiver ممکن است کمی کند تر باشد اما این امکان را فراهم میکند که بتوانید در هر کلاسی که به یک context دسترسی داشته باشید پوش ها را دریافت کنید.

دریافت پوش‌ها با استفاده از static BroadcastReceiver

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

public class StaticPushReceiver extends BefrestPushReceiver {
    @Override
    public void onPushReceived(Context context, BefrestMessage[] messages) {
        // Befrest push messages received
        // Your logic goes here
    }
}

سپس این گیرنده را مطابق کد زیر در فایل AndroidManifest در کنار سایر receiver ها ثبت کنید.

<receiver
   android:name=".StaticPushReceiver"
   android:exported="false">
   <intent-filter>
       <action android:name="rest.bef.broadcasts.ACTION_BEFREST_PUSH"/>
   </intent-filter>
</receiver>
دریافت پوش‌ها با استفاده از dynamic BroadcastReceiver

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

public class MainActivity extends AppCompatActivity {

    DynamicPushReceiver receiver;
    Befrest befrestInstance;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // ...
        befrestInstance = Befrest.getInstance(this);
        receiver = new DynamicPushReceiver();
        befrestInstance.registerPushReceiver(receiver);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        befrestInstance.unRegisterPushReceiver(receiver);
    }

    class DynamicPushReceiver extends BefrestPushReceiver {

        @Override
        public void onPushReceived(Context context, BefrestMessage[] messages) {
            // Befrest push message(s) received
            // your logic goes here
        }
    }
}
دریافت پوش های بفرست با استفاده از یک سرویس

بفرست اتصال خود را در یک سرویس برقرار نگه می دارد و در زمان دریافت پوش جدید با ارسال broadcast مناسب،receiver های ثبت شده را از دریافت پوش جدید آگاه میکند. از این پس منظور از سرویس پوش این سرویس خواهد بود. شما می توانید با تعریف کلاسی که از سرویس پوش پیش فرض بفرست ارث می برد و معرفی کلاس جدید به عنوان سرویس پوش وابستگی دریافت پوش به سیستم broadcasting را از میان بردارید. این کار باعث حذف شدن تاخیر ارسال و دریافت broadcast بین قسمت های مختلف برنامه می شود و کارایی را افزایش می دهد.
بدین منظور ابتدا کلاس MPushReceiver را که از rest.bef.PushReceiver ارث می برد بصورت زیر ایجاد کنید.

public class MPushService extends rest.bef.PushService {
    @Override
    protected void onPushReceived(ArrayList messages) {
        super.onPushReceived(messages);
        // Befrest push messages received
        // Your logic goes here
    }
}

از آنجا که این کلاس یک سرویس است لازم است آن را در Manifest به عنوان سرویس ثبت کنید.

<service android:name=".MPushService" />

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

befrestInstance.setCustomPushService(MPushService.class);
لطفا نکات زیر را در نظر داشته باشید:
  • بفرست با دریافت پوش جدید ابتدا onPushReceivd سرویس پوش را صدا می زند. رفتار پیش فرض این تابع ارسال broadcast برای مطلع کردن گیرنده ها از پوش های جدید است. در کلاس MPushService تنها چنانچه مایلید پوش دریافت شده به گیرنده های ثبت شده نیز broadcast شود super.onPushReceived را صدا بزنید. (با این روش شما میتوانید همزمان از سرویس و broadcastReceiverها برای مدیریت پوش ها استفاده کنید. همچنین توجه داشته باشید که این منطق برای سایر eventها از قبیل onConnectionRefreshed و onBefrestConnected که کارکرد آنها در ادامه توضیح داده خواهد شد یکسان است.)
Refresh کردن بفرست

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

تاپیک‌ها

اضافه و کم کردن تاپیک‌هایی که کاربر مورد نظر، پیام‌های منتشر شده در آن تاپیک‌ها را دریافت می‌کند از طریق دو تابع addTopic و removeTopic انجام می‌شود. ورودی این متود‌ها نام تاپیک مورد نظر است. باید تاپیک‌های مورد نظر را قبل از start کردن بفرست اضافه کنید. چنانچه می‌خواهید پس از start کردن بفرست، تاپیک‌ها را کم یا اضافه کنید تابع Befrest.start را پس از تغییر در تاپیک‌ها فراخوانی کنید. همچنین می‌توانید لیست تاپیک‌هایی را که تاکنون اضافه کرده‌اید با استفاده از تابع getCurrentTopics بررسی کنید.

افزایش امنیت در بفرست

می‌توانید برای بالابردن امنیت اتصال به بفرست، api key را به صورت دوره‌ای از قسمت تنظیمات حساب کاربری خود در وب سایت بفرست تغییر داده و کلید جدید را در سرور خود نگهداری کنید. با هر بار تغییر api key، اطلاعاتی که پیش از این، اپلیکیشن شما از آن برای اتصال استفاده می‌کرده نامعتبر خواهد شد. با اشکال در اطلاعات اتصال، بفرست شما را با فراخوانی تابع onAuthorizeProblem در گیرنده‌ها مطلع خواهد کرد. می‌توانید با override کردن این تابع در یکی از گیرنده‌های استاتیک، متوجه نادرستی رشته auth شوید و از سرور اپلیکیشن خود رشته auth جدید و درست را دریافت کنید. پس از تصحیح رشته auth با استفاده از تابع setAuth، بفرست را دوباره start کنید.

نکته امنیتی مهم: لازم است به این نکته اشاره مستقیم داشته باشیم که نگه‌داری api key و تولید رشته auth در اپلیکیشن می‌تواند امنیت حساب کاربری شما را به مخاطره اندازد. برای جلوگیری از دسترسی دیگران به api key و در نتیجه آن، تولید رشته auth، جداً توصیه می‌شود api key در سمت سرور نگهداری شده و رشته auth نیز در سرور تولید و به اپلیکیشن تحویل داده شود.

تعیین سطح لاگ‌های بفرست

در مراحل توسعه، بفرست با لاگ کردن اتفاقات مهم شما را از وضعیت خود مطلع می‌کند. می‌توانید با استفاده از تابع setLogLevel سطح لاگ‌ها را تغییر داده و جزییات کمتر یا بیشتری را مشاهده کنید.