build.gradle
مربوط به اپلیکیشن وارد شوید. مراقب باشید اشتباها به فایل gradle
مربوط به پروژه وارد نشوید.dependencies
اضافه کنید.implementation 'co.ronash.android:pushe-base:1.4.3'
برای استفاده از قابلیت های اندروید 8 مانند notification channel بایستی TargetSDK برابر 26 یا بالاتر باشد.
gradle
سینک شود.در فایل build.gradle
مربوط به پروژه مطمئن شوید که لینک های لازم برای دریافت پوشه و کتابخانه های ساپورت موجود هستند
allprojects {
repositories {
google()
jcenter()
//...
}
}
AndroidManifest.xml
پروژه خود اضافه کنید.AndroidManifest.xml
تگ tools
به رنگ قرمز نشان داده می شود، روی آن کلیک کرده و دکمههای Alt + Enter
را بزنید.
برخی از دسترسی ها (permissions) برای پوشه اختیاری است. این دسترسی ها برای ارسال هدفمند اعلان به کاربران است. شما قادر خواهید بود با استفاده از این دسترسیها کاربران خود را دسته بندی کنید و اعلانهای خود را هدفمند ارسال کنید.import
، کد روبرو را وارد کنید.import co.ronash.pushe.Pushe;
onCreate
کد روبرو را وارد کنید.Pushe.initialize(context,true);
true
گذاشته شود و دستگاه کاربر شما گوگل پلی سرویس نداشته باشد و یا آن را غیرفعال کرده باشد دیالوگی باز می شود و به کاربر پیشنهاد نصب گوگل پلی سرویس داده می شود تا قابلیت دریافت و ارسال پوش نوتیفیکیشن فعال شود. اگر در تابع بالا false
را قرار دهید، این دیالوگ برای کاربر باز نمی شود.پس از اینکه فایل کتابخانه را مطابق با آموزش داده شده نصب کردید، میتوانید پروژه را اجرا و بر روی دستگاه خود نصب و تست کنید.
اگر می خواهید اپلیکیشن را بر روی Emulator تست کنید، بر روی ایمولاتور شما باید Google API نصب باشد.
شما میتوانید از طریق پنل برای اپلیکیشن خود اطلاعات دلخواه در قالب یک 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
}
}
}
در حالتی که یک دکمه اعلان کلیک شود، شناسه آن دکمه را که یکی از اعداد ۱ تا ۳ هست میتوانید داشته باشید و از روی آن اینکه چه دکمهای کلیک شده است را متوجه میشوید.
شما میتوانید کاربران خود را در تاپیک یا تاپیکهای متفاوت ثبت نام کنید و برحسب علاقمندی کاربران یا دستهبندی خودتان به تاپیک مرتبط پوش بفرستید. مثلا اگر شما اپلیکیشن خبری دارید و کاربرانی به اخبار ورزشی علاقمند هستند و عده ای به اخبار فرهنگی، می توانید دسته اول را در تاپیک ورزشی و دسته دوم را در تاپیک فرهنگی ثبت نام کنید و هنگام ارسال پوش، برحسب محتوای پوشتان به تاپیک مرتبط آن را ارسال کنید تا فقط کاربران علاقمند به آن موضوع آن را دریافت کنند.
برای استفاده از این امکان باید کاربران خود را در تاپیک مورد نظر عضو کنید. فرض کنید نام تاپیک مورد نظرتان 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");
}
در اندروید ۸ به بعد قابلیتی برای تعریف کانال نوتیفیکیشن در اپلیکیشن ایجاد شده است. به این شکل که در برنامه خود یک یا چند کانال نوتیفیکیشن تعریف می کنید و در زمان ارسال اعلان پیشرفته با وارد کردن 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
);
شما میتوانید خطاهای عمومی موجود در هنگام نصب در اندروید را در این لینک مشاهده نمایید. موارد عنوان شده در زیر تنها مربوط به اندروید استودیو هستند.
با توجه به اینکه سایت Jcenter خدمات به ایران را محدود کرده است در صورتی که با این خطا مواجه شدهاید، پراکسی شما مشکل دارد و باید از پراکسی مناسب استفاده کنید.
در پوشه از کتابخانه ی support-v4
استفاده شده است. لذا اندروید استودیو اقدام به دانلود ملزومات کتابخانه از ریپازیتوری مربوطه خواهد کرد. در صورتی که به هردلیل در انجام این امر ناموفق باشد خطای بالا را خواهید دید.
برای اطلاعات بیشتر میتوانید سوال مربوط به آن در سایت استک اور فلو را بررسی کنید.
این دسترسی برای ارسال اعلان برحسب موقعیت مکانی کاربر هست. می توانید آن را حذف کنید اما دراینصورت اعلان پیشرفته برحسب مکان کاربر برای شما درست کار نخواهد کرد.
با اضافه کردن تگ زیر به Manifest می توانید این دسترسی را حذف کنید:
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove"/>
در صورتی که از نسخه ی 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.
این خطا برای توسعهدهندگانی که از Android Studio 2 استفاده میکنند گزارش شده است. برای آشنایی بیشتر در مورد این خطا میتوانید به این سایت مراجعه کنید. راهحلهایی که برای این مشکل پیشنهاد می شود موارد زیر است: