کتابخانه پوشمتریکس برای Android
- راهاندازی کتابخانه در اپلیکیشن اندروید
- امکانات و قابلیتها
- شناسهها و توکنها
- اختصاص شناسه سفارشی به کاربران
- متد MetrixNotification.setUserEmail
- متد MetrixNotification.setUserPhoneNumber
- متد MetrixNotification.setCustomId
- دریافت شناسه یکتا کاربر
- دریافت مقدار شناسههای سفارشی
- متد MetrixNotification.getUserEmail
- متد MetrixNotification.getUserPhoneNumber
- متد MetrixNotification.getCustomId
- توکن اختصاصی سرویس فایربیس
- گروهبندی کاربران
- تاپیک (topic)
- عضویت کاربر در تاپیک
- لغو عضویت کاربر از تاپیک
- تگ (tag)
- اضافهکردن تگ
- حذف تگ از لیست تگها
- گرفتن لیست تگها
- ارسال اعلان از طریق کد
- ارسال اعلان به دستگاه اجراکنندهی کد
- رویدادهای مرتبط با نوتیفیکیشن
- غیرفعالکردن نمایش اعلان
- بررسی وضعیت فعال یا غیرفعال بودن نمایش اعلان
- کانال نوتیفیکیشن
- اضافهکردن کانال نوتیفیکیشن
- حذف کانال نوتیفیکیشن
پروژه نمونه پیادهسازی پوشمتریکس را میتوانید در اینجا ملاحظه نمایید.
۱. مخزن متریکس را در فایل build.gradle
مربوط به پروژه خود در قسمت allprojects
اضافه کنید:
allprojects {
repositories {
// ...
mavenCentral()
}
}
۲. وابستگی مربوط به کتابخانه پوشمتریکس را در قسمت dependencies
فایل build.gradle
اپلیکیشن خود وارد کنید:
implementation 'ir.metrix.push:metrix:1.2.1'
۳. شناسه اپلیکیشن و شناسه ارسال پوش خود را در فایل AndroidManifest.xml
به صورت زیر وارد کنید:
<manifest>
...
<application>
...
<!-- خطوط زیر را اضافه کنید و شناسه اپلیکیشن خود را جایگزین نمایید -->
<meta-data
android:name="metrix_appId"
android:value="APP_ID" />
<!-- خطوط زیر را اضافه کنید و شناسه پوش اپلیکیشن خود را جایگزین نمایید -->
<!-- این شناسه با فعالسازی پوش در تنظیمات اپلیکیشن در اختیار شما قرار میگیرد -->
<meta-data
android:name="metrix_push_appId"
android:value="PUSH_APP_ID" />
</application>
</manifest>
۳. فایل google-services.json
مربوط به اپلیکیشن خود که از پنل فایربیس خود دریافت میکنید را در آدرس اصلی اپلیکیشن خود قرار دهید:
۴. جهت اضافهشدن پلاگین Google services
وابستگی زیر را در فایل build.gradle
سطح پروژه خود اضافه کنید:
buildscript {
...
dependencies {
...
// خط زیر را اضافه نمایید
classpath 'com.google.gms:google-services:4.3.4'
}
}
سپس پلاگین را در فایل build.gradle
اپلیکیشن خود اضافه کنید:
apply plugin: 'com.android.application'
// خط زیر را اضافه نمایید
apply plugin: 'com.google.gms.google-services'
جهت مشاهده امکانات و قابلیتهای مرتبط با کتابخانه متریکس، به مستندات متریکس در [اینجا]({{ site.baseurl }}/metrix-sdk-v1/android/#امکانات-و-قابلیتها) مراجعه کنید.
شما میتوانید به کاربران خود یک شناسه اختصاص دهید و از این شناسه برای ارسال اعلان تکی به کاربران استفاده کنید.
یکتا نگه داشتن شناسههایی که به کاربران خود اختصاص میدهید بر عهده شماست.
در صورتی که شناسهای را به بیشتر از یک کاربر اختصاص دهید، موقع ارسال اعلان به آن شناسه همه کاربرانی که آن شناسه به آنها اختصاص داده شده است اعلان را دریافت خواهند کرد. در مواقعی ممکن است این رفتار مطلوب باشد، مثلا در صورتی که یک کاربر در چند دستگاه لاگین کرده باشد ولی در غیر این صورت توجه داشته باشید که یک شناسه را به بیش از یک کاربر اختصاص ندهید.
سه نوع شناسه قابل اختصاص دادن به کاربران وجود دارد که شما برحسب نیاز از یک یا تعدادی از آنها میتوانید استفاده کنید.
شناسه | توضیحات | نحوه اختصاص دادن |
---|---|---|
ایمیل | آدرس ایمیل کاربر | MetrixNotification.setUserEmail() |
شماره تلفن | شماره تلفن کاربر | MetrixNotification.setUserPhoneNumber() |
شناسه دلخواه | هر عبارت دلخواهی که میخواهید به عنوان شناسه استفاده کنید | MetrixNotification.setCustomId() |
با استفاده از این متد می توانید ایمیل کاربر را به عنوان یک شناسه یکتا برای وی ذخیره کنید و با استفاده از آن اعلان یکتا برای این کاربر ارسال کنید.
var userEmail = "";
MetrixNotification.setUserEmail(userEmail);
نکته: برای حذف ایمیل از قبل ذخیره شده کاربر مقدار
null
را به عنوان پارامتر به این متد بدهید.
با استفاده از این متد می توانید شماره کاربر را به عنوان شناسه یکتا برای وی دخیره کنید و با استفاده از این شماره به این کاربر اعلان یکتا ارسال کنید.
var phoneNumber = "";
MetrixNotification.setUserPhoneNumber(phoneNumber);
با استفاده از این متد می توانید یک شناسه یکتا (می توانید از هر مقداری برای شناسه یکتا استفاده کنید فقط مقدار پارامتر باید از نوع string باشد) به کاربر اختصاص دهید تا با این شناسه به کاربر اعلان یکتا ارسال کنید.
const customId = "aCustomIdYousetForUser";
MetrixNotification.setCustomId(customId);
نکته: برای حذف شناسه از پیش ذخیره شده مقدار
null
را به عنوان پارامتر به این متد بدهید.
علاوه بر شناسههای معرفی شدهی بالا، دو شناسه دیگر به صورت خودکار به کاربران شما اختصاص داده میشود که با استفاده از آنها نیز میتوانید به کاربران خود اعلان ارسال کنید.
توضیحات این شناسهها در جدول زیر آمده است:
شناسه | توضیحات | نحوه دریافت |
---|---|---|
Android ID | این شناسه توسط اندروید به کاربران اختصاص داده میشود. در گوشیهای با سیستم عامل پایینتر از اندروید ۸، شناسهی Android ID کاربر بین تمامی اپلیکیشنهای نصب شده بر روی گوشی ثابت است و همچنین پس از حذف و نصب مجدد اپلیکیشن نیز ثابت میماند. در نسخهی اندروید ۸ به بالا، شناسهی Android ID یک کاربر تنها برای اپلیکیشنهایی که با کلیدهای یکسان امضا شده باشند یکتا است و برای بقیهی اپلیکیشنها متفاوت است. | MetrixNotification.getDeviceId |
Advertising ID | این شناسه برای یکتاسازی دیوایس حتی در حالتی که برنامهی شما حذف یا کلیردیتا شود استفاده میشود. این شناسه برای ماژول FCM برابر Google Ad id خواهد بود و برای ماژول HMS برابر Huawei OAID میباشد. کاربر میتواند این شناسه را حذف یا غیرفعال نماید | MetrixNotification.getAdvertisingId |
// Android ID
var androidId = MetrixNotification.getDeviceId();
// Advertising ID
var adId = MetrixNotification.getAdvertisingId();
برای دریافت مقادیر شناسه های سفارشی شده که متدهای آن در بالا توضیح داده شد می توانید از متدهای زیر استفاده کنید. توضیحات این شناسهها در جدول زیر آمده است:
شناسه | توضیحات | نحوه دریافت |
---|---|---|
شناسه سفارشی UserEmail | شناسه سفارشی ایمیل که توسط شما از قبل ذخیره شده توسط این متد قابل دریافت میباشد. | MetrixNotification.getUserEmail |
شناسه سفارشی UserPhoneNumber | شناسه سفارشی شماره کاربر که از قبل توسط شما ذخیره شده و توسط این متد قابل دریافت میباشد. | MetrixNotification.getUserPhoneNumber |
شناسه سفارشی CustomId | شناسه customId که از قبل توسط شما ذخیره شده و توسط این متد قابل دریافت میباشد. | MetrixNotification.getCustomId |
این متد مقداری که برای email از قبل توسط MetrixNotification.setUserEmail ذخیره شده را برمیگرداند. در صورتی که هیچ مقدار ایمیلی از قبل برای آن ذخیره نشده باشد یک string خالی برمیگرداند.
var email = MetrixNotification.getUserEmail();
این متد مقداری که برای phoneNumber از قبل توسط MetrixNotification.setUserPhoneNumber ذخیره شده را برمیگرداند. در صورتی که هیچ مقداری از قبل ذخیره نشده باشد یک string خالی برمیگرداند.
var phone = MetrixNotification.getUserPhoneNumber();
این متد مقداری که از قبل برای customId توسط MetrixNotification.setCustomId ذخیره شده را برمیگرداند. در صورتی که هیچ مقداری از قبل ذخیره نشده باشد یک string خالی برمیگرداند.
var customId = MetrixNotification.getCustomId();
در صورتی که بخواهید از توکن مستقیم
Firebase cloud messaging
استفاده کنید میتوانید با استفاده از تابع زیر آن را بدست آورید:
MetrixNotification.setTokenListener(new MetrixNotification.Listener() {
@Override
public void onReceived(String value) {
// TODO
}
});
تاپیک را میتوان یک گروه به حساب آورد که کاربران یک اپ را میتوان به آن اضافه و از آن حذف کرد. شما میتوانید کاربران خود را در تاپیک یا تاپیکهای متفاوت ثبتنام کنید و برحسب علاقهمندی کاربران یا دستهبندی خودتان به تاپیک مرتبط پوش بفرستید.
به عنوان مثال، اگر شما اپلیکیشن خبری دارید و کاربرانی به اخبار ورزشی علاقمند هستند و عدهای به اخبار فرهنگی، میتوانید دسته اول را در تاپیک ورزشی و دسته دوم را در تاپیک فرهنگی ثبتنام کنید و هنگام ارسال پوش، برحسب محتوای پوشتان به تاپیک مرتبط آن را ارسال کنید تا فقط کاربران علاقمند به آن موضوع آن را دریافت کنند. برای استفاده از این امکان باید کاربران خود را در تاپیک مورد نظر عضو کنید.
کاربر را به تاپیک مشخص اضافه میکند.
String sportTopic = "sport";
MetrixNotification.subscribeToTopic(sportTopic, new MetrixNotification.Callback() {
@Override
public void onComplete() {
// Successfully subscribed to topic
}
});
نام تاپیک باید انگلیسی باید و Regex آن مطابق داکیومنت فایربیس بصورت زیر است:
[a-zA-Z0-9-_.~%]+
کاربر را از تاپیک در صورت وجود حذف میکند (در صورتی که قبلا عضو نشده باشد اتفاقی نمیافتد)
String topicToRemoveUserFrom = "sport";
MetrixNotification.unsubscribeFromTopic(topicToRemoveUserFrom, new MetrixNotification.Callback() {
@Override
public void onComplete() {
// Successfully unsubscribed from topic
}
});
شما میتوانید کاربرانتان را برچسب گذاری کنید. هر تگ یا برچسب نمایانگر ویژگیهای مختلف مختص آن کاربر است. برای ارسال اعلان میتوان از این تگها استفاده کرد و دستهی خاصی از کاربران را مشخص کرد.
مثال:
- کاربرانی که در تاریخ خاصی متولد شدهاند برای ارسال اعلان تبریک تولد.
- کاربرانی که نام آنها محمد است و ۲۵ سال دارند.
- و ...
پارامتر ورودی | استفاده |
---|---|
tags | یک شئ از Map که کلید و مقدار آن string است. کلیدها عنوان تگ و مقدار هر کلید هم مقدار تگ را مشخص میکند |
در مثال زیر تگهای نام، سن و تاریخ تولد در نظر گرفته شدهاند.
Map<String,String> tags = new HashMap<String, String>();
tags.put("name","Mohammad");
tags.put("age","25");
tags.put("birthday","1435187386");
MetrixNotification.addTags(tags);
هر کاربر میتواند حداکثر ۱۰ تگ داشته باشد
میتوانید لیست کلیدهایی که میخواهید حذف کنید را به ورودی تابع بدهید.
پارامتر ورودی | استفاده |
---|---|
tags | لیست کلیدهایی که میخواهید از تگها حذف کنید |
List<String> tags = new ArrayList<String>();
tags.add("name");
tags.add("age");
tags.add("birthday");
MetrixNotification.removeTags(tags);
برای اضافه کردن تگ و حذف کردن تگ میتوانید callback ست کنید تا وقتی عملیات موفق بود از آن مطلع بشوید.
Map<Strring,String> tags = new HashMap<String, String>();
tags.put("name","Mohammad");
tags.put("age","25");
tags.put("birthday","1435187386");
MetrixNotification.addTags(tags, new MetrixNotification.Callback() {
@Override
public void onComplete() {
// Tags added
}
});
خروجی این تابع یک Map که تمام تگهای کاربر در آن وجود دارد خواهد بود.
Map<Strring,String> tags = new HashMap<String, String>();
tags.put("name","Ali");
MetrixNotification.addTags(tags);
Map<String,String> subscribedtags = MetrixNotification.getSubscribedTags(); // tags: {"name":"Ali"}
با استفاده از شناسههای کاربر میتوان از یک دیوایس دیگر به آن اعلان فرستاد.
در این حالت باید موارد زیر در نظر گرفته شود تا اعلان از یک دستگاه به دستگاه دیگر ارسال شود: ۱. اپلیکیشنی که برای ارسال و دریافت اعلان استفاده میشود باید در دستگاه مبدا و مقصد یکی باشد ۲. هر دو دستگاه باید در سرور پوشه رجیستر شده باشند
sendNotificationToUser(userNotification)
پارامتر ورودی | استفاده |
---|---|
userNotification | یک شی از نوع UserNotification |
میتوانید با استفاده از این تابع نوتیفیکیشنی به کاربر خاصی که این اپلیکیشن را نصب کرده و نصب آن در کنسول ثبتشده ارسال کنید. موقع ساختن آبجکت UserNotification شناسهای را که با استفاده از آن میخواهید نوتیفیکیشن را ارسال کنید تعیین میکنید. برای مثال در نمونه زیر از androidId برای ساختن آبجکت نوتیفیکیشن استفاده شده است.
if (MetrixNotification.isRegistered()) {
UserNotification userNotification = UserNotification.withAndroidId(androidId);
userNotification.setTitle("title1");
userNotification.setContent("content1");
MetrixNotification.sendNotificationToUser(userNotification);
}
در صورتی که بخواهید به همین دستگاهی که کد را اجرا میکند اعلان ارسال کنید کافیست شناسه را برابر شناسهی همین دستگاه قرار دهید:
UserNotification userNotification = UserNotification.withAndroidId(MetrixNotification.getAndroidId());
userNotification.setTitle("title1");
userNotification.setContent("content1");
MetrixNotification.sendNotificationToUser(userNotification);
در صورتی که پیامی از پوشمتریکس به کاربر ارسال شود (به صورت نوتیفیکیشن و یا جیسون)، میتوان از آنها باخبر شد. برای اینکار می توانید کالبکی تعریف کنید و هنگام رخدادن هریک از رویدادهای زیر کدهای خود را فراخوانی کنید.
- دریافت نوتیفیکیشن
- دریافت JSON (Custom content)
- کاربر بر روی اعلان کلیک کند
- کاربر اعلان را رد (Dismiss) کند
- کاربر بر روی دکمهای از اعلان کلیک کند
setNotificationListener()
پارامتر ورودی | استفاده |
---|---|
notificationListener | یک اینترفیس که متدهای رویدادها را نگهداری و در زمان رخداد فراخوانی میکند |
کدهای دریافت رویداد را میتوانید به صورت زیر استفاده کنید:
MetrixNotification.setNotificationListener(new MetrixNotificationListener() {
@Override
public void onNotification(@NonNull NotificationData notification) {
// Notification Received
}
@Override
public void onCustomContentNotification(@NonNull Map<String, Object> customContent) {
// Notification custom content (Json) received
}
@Override
public void onNotificationClick(@NonNull NotificationData notification) {
// Notification clicked
}
@Override
public void onNotificationDismiss(@NonNull NotificationData notification) {
// Notification dismissed
}
@Override
public void onNotificationButtonClick(@NonNull NotificationButtonData button, @NonNull NotificationData notification) {
// Notification button clicked
}
});
توجه: برای اینکه بتوانید رویدادها را در هر زمانی دریافت کنید بهتر است پیادهسازی کدهای رویداد را در کلاس اپلیکیشن انجام دهید.
کلاسهای NotificationData
و NotificationButtonData
دارای فیلدهای زیر هستند:
NotificationData.java
فیلد | توضیحات |
---|---|
title | تیتر نوتیفیکیشن |
content | محتوای نوتیفیکیشن |
bigTitle | تیتر بزرگ نوتیفیکیشن |
bigContent | محتوای بزرگ نوتیفیکیشن |
summary | متن خلاصهی نوتیفکیشن |
imageUrl | لینک عکس نوتیفیکیشن |
iconUrl | لینک آیکون نوتیفیکیش ن |
customContent | مپ دلخواه نوتیفیکیشن |
buttons | لیست دکمههایی که نوتیفیکیشن دارد |
جز title
و content
بقیهی فیلدها میتوانند null
باشند.
NotificationButtonData.java
فیلد | توضیحات |
---|---|
id | شناسهای برای تشخیص دکمه |
text | متن دکمه |
icon | آیکن دکمه |
به طور پیشفرض نمایش اعلان برای کاربر فعال است. اما میتوان نمایش اعلان را برای کاربر با استفاده از کد، غیرفعال و یا مجددا فعال نمود.
با غیر فعال شدن نمایش اعلان، توابع رویداد کماکان اجرا میشوند که برای جلوگیری از اجرای آنها میتوانید فعالبودن را بررسی کنید.
MetrixNotification.disableNotifications();
MetrixNotification.enableNotifications();
boolean showingNotificationEnabled = MetrixNotification.isNotificationEnable();
if (showingNotificationEnabled) {
// میتوانید کدهایی را که میخواهید وقتی نمایش نوتیفیکیشن فعال است اجرا شوند در اینجا بنویسید
} else {
// میتوانید کدهایی را که میخواهید وقتی نمایش نوتیفیکیشن غیرفعال است اجرا شوند در اینجا بنویسید
}
کانال نوتیفیکیشن که در اندروید نسخه ۸ اضافه شده در واقع یک دستهبندی برای اعلانهای ارسالی به کاربران میباشد که میتوان در این دسته بندی رنگ LED ، صدای اعلان و ... را مشخص کرد
استفاده از کانال نوتیفیکیشن در اندروید ۸ به بالا اجباری میباشد و به هر نوتیفیکیشن باید یک کانال اختصاص داده شود. هنگامی که از کتابخانه پوشمتریکس استفاده میکنید به صورت پیشفرض یک کانال به نوتیفیکیشنها اختصاص داده میشود که در صورت تمایل میتوانید توسط ادامه راهنما کانال سفارشی خودتان را ایجاد کنید تا تنظیمات دلخواه شما را داشته باشد.
البته لازم به ذکر است که بیشتر تنظیماتی که میتوان برای کانال نوتیفیکیشن تعیین کرد از طریق کنسول در هنگام ارسال نوتیفیکیشن در دسترس هستند و شما میتوانید از طریق کنسول، رنگ LED، صدای نوتیفیکیشن و ... را تعیین کنید.
نکته: در نظر داشته باشید که در صورت ساخت کانال تنظیمات رنگ LED ، صدای اعلان و ... که در کنسول تنظیم میکنید دیگر کار نخواهد کرد و فقط تنظیمات کانال شما برای اعلان ارسالیتان اعمال میشود. در کنسول شناسه کانالتان را هنگام فرستادن اعلان وارد میکنید و هر تنظیمی که برای آن کانال ست کرده باشید هنگام نمایش اعلان اعمال خواهد شد.
وقتی نوتیفیکیشنی را به کانال سفارشی میفرستید در نظر داشتهباشید که کانفیگ نوتیفیکیشن که هنگام ارسال در کنسول تنظیم میکنید از بینمیرود و تنظیمات کانال نوتیفیکیشن سفارشی جایگزین آن میشود (مثلا صدای اعلان، رنگ LED و ...)
createNotificationChannel(parameters...)
پارامتر ورودی | استفاده |
---|---|
channelId | شناسهای که بتوان کانال را شناسایی کرد. مثلا sportChannel |
channelName | نامی که برای کانال خود انتخاب میکنید |
description | توضیحات دلخواه در مورد کانال |
importance | عددی برای مشخصکردن میزان اهمیت (اطلاعات بیشتر) |
enableLight | فعالکردن LED |
enableVibration | فعالکردن ویبرهی نوتیفیکیشن |
showBadge | فعالکردن نمایش بچ در لانچر دستگاه |
ledColor | رنگ LED (اطلاعات بیشتر) |
vibrationPattern | پترن ویبره (اطلاعات بیشتر) |
در صورتی که نیاز به شخصیسازی بیشتر دارید، ساخت کانال به صورت مستقیم نیز امکانپذیر است. اطلاعات بیشتر را میتوانید در مستندات اندروید مشاهده کنید.
چیزی که مهم است این است که شما با استفاده از پوشمتریکس و یا مستقیما کانالتان را ایجاد کنید و شناسه آن کانال را هنگام فرستادن اعلان در کنسول وارد کنید (در مرحله سوم در قسمت فیلتر) در این صورت پوشی که از طریق کنسول ارسال میکنید فقط به آن دسته از کاربرانی ارسال میشود که از طریق برنامهتان کانال نوتیفیکیشن برایشان ایجاد شده باشد. شما ممکن است بخواهید کانال سفارشی را فقط برای دسته خاصی از کاربرانتان ایجاد کنید که به منطق برنامه شما بستگی دارد.
String channel = "sportChannel";
String channelName = "My Sport group";
String channelDesc = "This channel holds athletes users";
int importance = NotificationManager.IMPORTANCE_DEFAULT, ledColor = -65536;
boolean light = true, vibration = false, badge = true;
long[] vibrationPatterns = null;
// if(Build.VERSION.SDK_INT >= 26)
MetrixNotification.createNotificationChannel(channelId, channelName, channelDesc, importance, light, vibration, badge, ledColor, vibrationPattern);
در صورتی که قصد دارید کانال نوتیفیکیشن را حذف کنید، کد زیر را فراخوانی کنید. اگر هنگام ارسال نوتیفیکیشن از طریق کنسول در قسمت فیلتر شناسه کانالی را وارد کنید که وجود نداشته باشد کانال پیشفرض در نظر گرفته میشود.
String channelThatWasCreated = "sportChannelId";
MetrixNotification.removeNotificationChannel(channelThatWasCreated);