پروژه نمونه پیاده‌سازی پوش‌متریکس را می‌توانید در اینجا ملاحظه نمایید.

راه‌اندازی کتابخانه در اپلیکیشن اندروید

۱. مخزن متریکس را در فایل build.gradle مربوط به پروژه خود در قسمت allprojects اضافه کنید:

allprojects {
    repositories {
        // ...

        mavenCentral()
    }
}

۲. وابستگی مربوط به کتابخانه پوش‌متریکس را در قسمت dependencies فایل build.gradle اپلیکیشن خود وارد کنید:

implementation 'ir.metrix.push:metrix:1.1.3'

۳. شناسه اپلیکیشن و شناسه ارسال پوش خود را در فایل 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'

امکانات و قابلیت‌ها

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

شناسه‌ها و توکن‌ها

اختصاص شناسه سفارشی به کاربران

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

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

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

متد MetrixNotification.setUserEmail

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

var userEmail = '';
MetrixNotification.setUserEmail(userEmail);

نکته: برای حذف ایمیل از قبل ذخیره شده کاربر مقدار null را به عنوان پارامتر به این متد بدهید.

متد MetrixNotification.setUserPhoneNumber

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

var phoneNumber = '';
MetrixNotification.setUserPhoneNumber(phoneNumber);

متد MetrixNotification.setCustomId

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

const customId = 'aCustomIdYousetForUser';

MetrixNotification.setCustomId(customId);

نکته: برای حذف شناسه از پیش ذخیره شده مقدار null را به عنوان پارامتر به این متد بدهید.

دریافت شناسه یکتا کاربر

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

توضیحات این شناسه‌ها در جدول زیر آمده است:

// Android ID
var androidId = MetrixNotification.getDeviceId();

// Advertising ID
var adId = MetrixNotification.getAdvertisingId();

دریافت مقدار شناسه‌های سفارشی

برای دریافت مقادیر شناسه های سفارشی شده که متدهای آن در بالا توضیح داده شد می توانید از متد‌های زیر استفاده کنید. توضیحات این شناسه‌ها در جدول زیر آمده است:

متد MetrixNotification.getUserEmail

این متد مقداری که برای email از قبل توسط MetrixNotification.setUserEmail ذخیره شده را برمی‌گرداند. در صورتی که هیچ مقدار ایمیلی از قبل برای آن ذخیره نشده باشد یک string خالی برمی‌گرداند.

var email = MetrixNotification.getUserEmail();

متد MetrixNotification.getUserPhoneNumber

این متد مقداری که برای phoneNumber از قبل توسط MetrixNotification.setUserPhoneNumber ذخیره شده را برمی‌گرداند. در صورتی که هیچ مقداری از قبل ذخیره نشده باشد یک string خالی بر‌می‌گرداند.

var phone = MetrixNotification.getUserPhoneNumber();

متد MetrixNotification.getCustomId

این متد مقداری که از قبل برای customId توسط MetrixNotification.setCustomId ذخیره شده را بر‌می‌گرداند. در صورتی که هیچ مقداری از قبل ذخیره نشده باشد یک string خالی برمی‌گرداند.

var customId = MetrixNotification.getCustomId();

توکن‌ اختصاصی سرویس‌ فایربیس

در صورتی که بخواهید از توکن مستقیم Firebase cloud messaging استفاده کنید می‌توانید با استفاده از تابع زیر آن را بدست آورید:

MetrixNotification.setTokenListener(new MetrixNotification.Listener() {
    @Override
    public void onReceived(String value) {
        // TODO
    }
});

گروه‌بندی کاربران

تاپیک (topic)

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

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

عضویت کاربر در تاپیک

کاربر را به تاپیک‌ مشخص اضافه می‌کند.

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
    }
});

تگ (tag)

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

مثال:

• کاربرانی که در تاریخ خاصی متولد شده‌اند برای ارسال اعلان تبریک تولد.
• کاربرانی که نام آنها محمد است و ۲۵ سال دارند.
• و ...

اضافه‌کردن تگ

در مثال زیر تگ‌های نام، سن و تاریخ تولد در نظر گرفته شده‌اند.

Map<String,String> tags = new HashMap<String, String>();
tags.put("name","Mohammad");
tags.put("age","25");
tags.put("birthday","1435187386");
MetrixNotification.addTags(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 شناسه‌ای را که با استفاده از آن میخواهید نوتیفیکیشن را ارسال کنید تعیین می‌کنید. برای مثال در نمونه زیر از 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()

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

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 بقیه‌ی فیلدها می‌توانند null باشند.

NotificationButtonData.java

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

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

‌ با غیر فعال شدن نمایش اعلان، توابع رویداد کماکان اجرا می‌شوند که برای جلوگیری از اجرای آنها می‌توانید فعال‌بودن را بررسی کنید.

MetrixNotification.disableNotifications();

MetrixNotification.enableNotifications();

بررسی وضعیت فعال یا غیرفعال بودن نمایش اعلان

boolean showingNotificationEnabled = MetrixNotification.isNotificationEnable();

if (showingNotificationEnabled) {
    // می‌توانید کدهایی را که می‌خواهید وقتی نمایش نوتیفیکیشن فعال است اجرا شوند در اینجا بنویسید
} else {
    // می‌توانید کدهایی را که می‌خواهید وقتی نمایش نوتیفیکیشن غیرفعال است اجرا شوند در اینجا بنویسید
}

کانال نوتیفیکیشن

کانال نوتیفیکیشن که در اندروید نسخه ۸ اضافه شده در واقع یک دسته‌بندی برای اعلان‌های ارسالی به کاربران می‌باشد که می‌توان در این دسته بندی رنگ LED ، صدای اعلان و ... را مشخص کرد

استفاده از کانال نوتیفیکیشن در اندروید ۸ به بالا اجباری می‌باشد و به هر نوتیفیکیشن باید یک کانال اختصاص داده شود. هنگامی که از کتابخانه پوش‌متریکس استفاده می‌کنید به صورت پیش‌فرض یک کانال به نوتیفیکیشن‌ها اختصاص داده می‌شود که در صورت تمایل می‌توانید توسط ادامه راهنما کانال سفارشی خودتان را ایجاد کنید تا تنظیمات دلخواه شما را داشته باشد.

البته لازم به ذکر است که بیشتر تنظیماتی که می‌توان برای کانال نوتیفیکیشن تعیین کرد از طریق کنسول در هنگام ارسال نوتیفیکیشن در دسترس هستند و شما می‌توانید از طریق کنسول، رنگ ‌LED، صدای نوتیفیکیشن و ... را تعیین کنید.

نکته: در نظر داشته باشید که در صورت ساخت کانال تنظیمات رنگ LED ، صدای اعلان و ... که در کنسول تنظیم می‌کنید دیگر کار نخواهد کرد و فقط تنظیمات کانال شما برای اعلان ارسالی‌تان اعمال می‌شود. در کنسول شناسه کانالتان را هنگام فرستادن اعلان وارد می‌کنید و هر تنظیمی که برای آن کانال ست کرده باشید هنگام نمایش اعلان اعمال خواهد شد.

وقتی نوتیفیکیشنی را به کانال سفارشی می‌فرستید در نظر داشته‌باشید که کانفیگ نوتیفیکیشن که هنگام ارسال در کنسول تنظیم می‌کنید از بین‌می‌رود و تنظیمات کانال نوتیفیکیشن سفارشی جایگزین آن می‌شود (مثلا صدای اعلان، رنگ LED و ...)

اضافه‌کردن کانال نوتیفیکیشن

createNotificationChannel(parameters...)

در صورتی که نیاز به شخصی‌سازی بیشتر دارید، ساخت کانال به صورت مستقیم نیز امکان‌پذیر است. اطلاعات بیشتر را می‌توانید در مستندات اندروید مشاهده کنید.

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

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);