Android Studio

راه‌اندازی

اضافه کردن کتابخانه

• در build.gradle مربوط به اپلیکیشن وارد شوید. مراقب باشید اشتباها به فایل gradle مربوط به پروژه وارد نشوید.
• کد زیر را در dependencies اضافه کنید.

implementation 'co.ronash.android:pushe-base:1.4.1'
implementation 'com.google.android.gms:play-services-gcm:16.0.0'
implementation 'com.google.android.gms:play-services-location:16.0.0'
implementation 'com.google.android.gms:play-services-ads:16.0.0'

برای استفاده از قابلیت های اندروید 8 مانند notification channel بایستی TargetSDK برابر 26 یا بالاتر باشد.

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

در فایل build.gradle مربوط به پروژه مطمئن شوید که لینک های لازم برای دریافت پوشه و کتابخانه های ساپورت موجود هستند

allprojects {
    repositories {
        google()
        jcenter()
        //...
    }
}

تغییرات AndroidManifest.xml

• وارد پنل کاربری پوشه شوید و در قسمت اپلیکیشن‌ها، روی آیکون دریافت منیفست بزنید (این آیکون را با کلیک بر روی علامت سه نقطه‌ی گوشه‌ی کارت اپلیکیشن می توانید ببینید).
• منیفست اندروید استودیو را انتخاب کنید و محتویات آن را با توجه به راهنمای موجود، در قسمت‌های مربوطه کپی کرده و به AndroidManifest.xml پروژه خود اضافه کنید.
• اگر پس از اضافه کردن به AndroidManifest.xml تگ tools به رنگ قرمز نشان داده می شود، روی آن کلیک کرده و دکمه‌های Alt + Enter را بزنید. برخی از دسترسی ها (permissions) برای پوشه اختیاری است. این دسترسی ها برای ارسال هدفمند اعلان به کاربران است. شما قادر خواهید بود با استفاده از این دسترسی‌ها کاربران خود را دسته بندی کنید و اعلان‌های خود را هدفمند ارسال کنید.

تغییرات MainActivity.java

• در قسمت import ، کد روبرو را وارد کنید.

import co.ronash.pushe.Pushe;

• در onCreate کد روبرو را وارد کنید.

Pushe.initialize(context,true);

• اگر در تابع بالا مقدار true گذاشته شود و دستگاه کاربر شما گوگل پلی سرویس نداشته باشد و یا آن را غیرفعال کرده باشد دیالوگی باز می شود و به کاربر پیشنهاد نصب گوگل پلی سرویس داده می شود تا قابلیت دریافت و ارسال پوش نوتیفیکیشن فعال شود. اگر در تابع بالا false را قرار دهید، این دیالوگ برای کاربر باز نمی شود.

تست

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

• به صفحه نصب ها بروید.
• بعد از گذشت زمان کوتاهی یک ردیف مشخصات نصب به لیست نصب ها اضافه می شود که متعلق به گوشی شما است.
• یک اعلان تست ارسال کنید.دقت کنید تلفن همراه شما به اینترنت متصل باشد.

  اگر می خواهید اپلیکیشن را بر روی Emulator تست کنید، بر روی ایمولاتور شما باید Google API نصب باشد.

امکانات

دریافت اطلاعات دلخواه با فرمت JSON

شما میتوانید از طریق پنل برای اپلیکیشن خود اطلاعات دلخواه در قالب یک JSON ارسال کنید. برای اینکه بتوانید از این اطلاعات در اپلیکیشن خود استفاده کنید مراحل زیر را انجام دهید.

• کد زیر را در AndroidManifest.xml داخل بدنه تگ <application> اضافه کنید.

<service
    android:name=".MyPushListener"
    android:exported="false">
    <intent-filter>
        <action android:name="co.ronash.pushe.RECEIVE" />
    </intent-filter>
</service>
<!--PushListener can be somewhere else according to your packaging-->

• در پروژه خود یک class جدید ایجاد کنید و برای آن یک نام انتخاب کنید. پیشنهاد ما نام MyPushListener می باشد.
• کد زیر را در آن قرار دهید. بر روی PusheListenerService و JSONObject که به رنگ قرمز در آمده اند رفته و کلید Alt+Enter را بزنید تا کتابخانه‌های مربوطه به پروژه شما اضافه شوند.

public class MyPushListener extends PusheListenerService {
    @Override
    public void onMessageReceived(JSONObject customContent,JSONObject pushMessage){
        android.util.Log.i("Pushe","Custom json Message: "+ customContent.toString());
        // Your Code
    }
}

• از این طریق JSON دریافت می‌شود و با قرار دادن کد خود به جای // Your Code می‌توانید از آن استفاده کنید.
• وقتی از کلاس PusheListenerService ارث بری می‌کنید، داخل متد onMessageReceived دو شیء از نوع JSONObject دریافت می‌کنید که پارامتر اول JSON ارسالی و پارامتر دوم محتوای پوش نمایش داده شده است.
• برای مثال اگر در JSON ارسالی خود کلید‌های content و title را دارید و می‌خواهید آن را در LogCat نشان دهید، این کد را اضافه می‌کنید:

مثال: JSON ارسال شده

{
    "title": "تیتر",
    "content": "متن"
}

public class MyPushListener extends PusheListenerService{
    @Override
    public void onMessageReceived(JSONObject customContent,JSONObject pushMessage) {
        if (customContent == null || customContent.length() == 0)
            return; //json is empty
        android.util.Log.i("Pushe","Custom json Message: "+ customContent.toString()); //print json to logCat
        //Do something with json
      try{
            String s1 = customContent.getString("title");
            String s2 = customContent.getString("content");
            android.util.Log.i("Pushe","Json Message\n title: " + s1 + "\n content: " + s2);
      } catch (JSONException e) {
            android.util.Log.e("TAG","Exception in parsing json" ,e);
      }
 }

به همین ترتیب اگر شما مقادیر int یا boolean در JSON ارسالی گذاشته اید، با دستورهای

message.getInt(نام کلید)
message.getBoolean(نام کلید)

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

رسیورهای دریافت کلیک / رد اعلان

شما می‌توانید با ثبت یک رسیور در برنامه‌تان، از کلیک شدن یا رد کردن اعلان مطلع شوید. برای این کار یک BroadcastReceiver در فایل AndroidManifest.xml برنامه خودتان اضافه کنید و اینتنت فیلترهای زیر را در آن اضافه کنید. سه اینتنت فیلتر برای سه اتفاق زدن بر روی اعلان، رد کردن اعلان و کلیک شدن دکمه‌ای از اعلان معرفی شده است. می‌توانید هر سه را استفاده کنید یا فقط یکی یا دو تا را بسته به نیازمندی خودتان مشخص کنید.

این قابلیت برای نسخه های اندروید 8 و بالاتر کارایی ندارد.

<receiver android:name=".NotifBroadcastReceiver">
    <intent-filter>
        <action android:name="YOUR_PKG_NAME.pusheco.NOTIF_CLICKED"/>
        <action android:name="YOUR_PKG_NAME.pusheco.NOTIF_DISMISSED" />
        <action android:name="YOUR_PKG_NAME.pusheco.NOTIF_BTN_CLICKED" />
    </intent-filter>
</receiver>

در کلاس BroadcastReceiver هم کدی شبیه به زیر اضافه کنید:

• دقت کنید که YOUR_PKG_NAME همان نام پکیج شماست.

public class NotifBroadcastReceiver
extends BroadcastReceiver {

@Override

public void onReceive(Context context, Intent intent) {

    if(intent.getAction().equals("YOUR_PKG_NAME.pusheco.NOTIF_CLICKED")){
        Log.i("Pushe","Broadcast YOUR_PKG_NAME.pusheco.NOTIF_CLICKED received");
        //add your logic here
    }

    else if(intent.getAction().equals("YOUR_PKG_NAME.NOTIF_DISMISSED")){
        Log.i("Pushe", "Broadcast YOUR_PKG_NAME.NOTIF_DISMISSED received");
        //add your logic here
    }

    else if(intent.getAction().equals("YOUR_PKG_NAME.pusheco.NOTIF_BTN_CLICKED")){
        String btnId = intent.getStringExtra("pushe_notif_btn_id");
        Log.i("Pushe", "Broadcast YOUR_PKG_NAME.pusheco.NOTIF_BTN_CLICKED received. BtnId = "+btnId);
        //add your logic here
        }
    }
}

در حالتی که یک دکمه اعلان کلیک شود، شناسه آن دکمه را که یکی از اعداد ۱ تا ۳ هست می‌توانید داشته باشید و از روی آن اینکه چه دکمه‌ای کلیک شده است را متوجه می‌شوید.

تاپیک (topic)

شما می‌توانید کاربران خود را در تاپیک یا تاپیک‌های متفاوت ثبت نام کنید و برحسب علاقمندی کاربران یا دسته‌بندی خودتان به تاپیک مرتبط پوش بفرستید. مثلا اگر شما اپلیکیشن خبری دارید و کاربرانی به اخبار ورزشی علاقمند هستند و عده ای به اخبار فرهنگی، می توانید دسته اول را در تاپیک ورزشی و دسته دوم را در تاپیک فرهنگی ثبت نام کنید و هنگام ارسال پوش، برحسب محتوای پوش‌تان به تاپیک مرتبط آن را ارسال کنید تا فقط کاربران علاقمند به آن موضوع آن را دریافت کنند. برای استفاده از این امکان باید کاربران خود را در تاپیک مورد نظر عضو کنید. فرض کنید نام تاپیک مورد نظرتان ‍‍‍sport باشد. برای عضویت در این تاپیک از دستور زیر استفاده کنید:

Pushe.subscribe(context, "sport");

برای لغو عضویت از این تاپیک از دستور زیر استفاده کنید:

Pushe.unsubscribe(context, "sport");

توجه داشته باشید که توابع مربوط به عضو شدن و لغو عضویت در تاپیک باید بعد از پایان Pushe.initialize اجرا شوند. بنابراین آنها را بلافاصله بعد از Pushe.initialize قرار ندهید.

غیرفعال کردن نمایش پوش

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

Pushe.setNotificationOff(context);

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

Pushe.setNotificationOn(context);

ارسال پوش از یک دستگاه به دستگاه دیگر

می‌توانید مستقیم از یک دستگاه به دستگاه دیگر اعلان بفرستید. برای این کار باید شناسه‌ی پوشه‌ی آن دستگاه یعنی pusheId آن را داشته باشید. برای بدست آوردن شناسه هر دستگاه می توانید به روش زیر عمل کنید:

String pid = Pushe.getPusheId(context);

به این روش pid هر دستگاه را می توانید بدست بیاورید و آن‌ها را در سرور خود ذخیره کنید تا برای ارسال اعلان به دستگاه از آن استفاده کنید.

• برای ارسال اعلان ساده از دستور زیر استفاده کنید:

Pushe.sendSimpleNotifToUser(context, "pid_a0e3-82ac-a0", "title", "content");

• پارمتر اول context، پارامتر دوم pusheId است و پارامتر سوم و چهارم به ترتیب تیتر و متن اعلان هستند.
• برای ارسال اعلان پیشرفته از این دستور استفاده کنید:

Pushe.sendAdvancedNotifToUser(context, "pid_a0e3-82ac-a0", "{ \"title\":\"تست\", \"content\":\"پیام ارسالی از یک دستگاه \" }");

• پارمتر اول context، پارامتر دوم pusheId است و پارامتر سوم یک رشته با فرمت JSON هست که مشخصات اعلان پیشرفته را تعیین می کند. برای دیدن فرمت JSON به اینجا مراجعه کنید.
• برای ارسال JSON دلخواه از دستور زیر استفاده کنید:

Pushe.sendCustomJsonToUser(context, "pid_a0e3-82ac-a0", "{ \"key1\":\"value1\", \"key2\":\"value2\" }");

در این حالت پارامتر سوم یک رشته با فرمت JSON هست که اطلاعاتی که می خواهید ارسال کنید را به فرمت JSON داخلش دارد. نکته مهم: توابع ارسال اعلان به دستگاه دیگر و عضویت یا لغو عضویت در تاپیک را بعد از اطمینان از اینکه عملیات initialization پوشه انجام شده است، صدا بزنید. برای این کار به روش زیر عمل کنید:

if (Pushe.isPusheInitialized(context)) {
    Pushe.sendSimpleNotifToUser(context, "pid_a0e3-82ac-a0", "title", "content");
}

ایجاد و حذف کانال نوتیفیکیشن در اپلیکیشن (Android 8.0+ only)

در اندروید ۸ به بعد قابلیتی برای تعریف کانال نوتیفیکیشن در اپلیکیشن ایجاد شده است. به این شکل که در برنامه خود یک یا چند کانال نوتیفیکیشن تعریف می کنید و در زمان ارسال اعلان پیشرفته با وارد کردن Channel-Id آن کانال می‌توانید اعلان را برای آن کانال خاص ارسال کنید. مزیت این کار این هست که کاربر می تواند دریافت نوتیفیکیشن از بعضی کانال‌ها را غیرفعال کند و همچنان می‌تواند از یک یا چند کانال دیگر اعلان بگیرد. فراخوانی تابع ایجاد یا حذف کانال در حالتی که برنامه شما روی اندروید زیر ۸ اجرا شود، اثری ندارد. همچنین اگر بیشتر از یکبار تابع ایجاد کانال را صدا بزنید هم فقط یکبار کانال ایجاد می‌شود و مشکلی ایجاد نمی‌کند. با استفاده از دستور زیر در برنامه خود می توانید کانال نوتیفیکشن تعریف کنید:

    Pushe.createNotificationChannel(
                context,
                "MY_CHANNEL_ID", //channelId
                "all news channel", //Channel Name
                "", //description about channel
                4, //importance: Number between 0 to 5 (5 is the most important)
                true, //enableLight
                true, //enableViberation
                true, //showBadge
                Color.BLUE, //led color
                new long[]{100, 200, 300, 400, 500, 400, 300, 200, 400} // Vibrate mode (can be Nullable)
    );

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

    Pushe.removeNotificationChannel(
                context,
                "MY_CHANNEL_ID" //channelId
    );

عیب یابی

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

Error: Failed to resolve: co.ronash.android:pushe-base

با توجه به اینکه سایت Jcenter خدمات به ایران را محدود کرده است در صورتی که با این خطا مواجه شده‌اید، پراکسی شما مشکل دارد و باید از پراکسی مناسب استفاده کنید.

Error: Failed to resolve: com.android.support:support-v4:26.0.2

در پوشه از کتابخانه ی support-v4 استفاده شده است. لذا اندروید استودیو اقدام به دانلود ملزومات کتابخانه از ریپازیتوری مربوطه خواهد کرد. در صورتی که به هردلیل در انجام این امر ناموفق باشد خطای بالا را خواهید دید. برای اطلاعات بیشتر میتوانید سوال مربوط به آن در سایت استک اور فلو را بررسی کنید.

برخی مارکت ها به دسترسی ACCESS_COURSE_LOCATION حساسند.

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

با اضافه کردن تگ زیر به Manifest می توانید این دسترسی را حذف کنید: <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove"/>

The Google Mobile Ads SDK was initialized incorrectly.

در صورتی که از نسخه ی 17 سرویس های لوکیشن، gcm و ad استفاده کنید ممکن است به این خطا برخورد کنید. برای رفع آن بایستی متادیتای زیر را داخل تگ اپلیکیشن در مانیفست اضافه کنید.

<meta-data
android:name="com.google.android.gms.ads.AD_MANAGER_APP"
android:value="true"/>

• متن کامل خطا:

  The Google Mobile Ads SDK was initialized incorrectly. AdMob publishers
  should follow the instructions here: https://goo.gl/fQ2neu to add a valid
  App ID inside the AndroidManifest. Google Ad Manager publishers should   
  follow instructions here: https://goo.gl/h17b6x. 

fd.runtime.BootstrapApplication ClassNotFoundException

این خطا برای توسعه‌دهندگانی که از Android Studio 2 استفاده می‌کنند گزارش شده است. برای آشنایی بیشتر در مورد این خطا می‌توانید به این سایت مراجعه کنید. راه‌حل‌هایی که برای این مشکل پیشنهاد می شود موارد زیر است:

• در گریدل خود این کد را حذف کنید preDexLibraries = false
• غیر فعال کردن instant run به این روش