SDK اندروید v2
راهنمای نصب Pushfa Android SDK v2 از Maven Central، JitPack یا سورس GitHub؛ شامل ثبت FCM، Subscriber ID، تاپیک، External ID (همان Alias اصلی)، شناسههای سفارشی، رویدادها و مدیریت کامل اعلان.
مخزن رسمی و راهنمای کامل GitHub
سورس رسمی Pushfa Android SDK، آخرین README فارسی، نمونهکد همه متدها و تاریخچه نسخهها در مخزن رسمی GitHub پوشفا نگهداری میشود. برای نصب نسخه فعلی از 2.0.4 استفاده کنید و برای مشاهده راهنمای کامل و تغییرات نسخههای بعدی همیشه README همین مخزن را مرجع قرار دهید.
قابلیتها و پیشنیازها
این SDK برای همه اپلیکیشنهای Native Android با حداقل Android 6.0 (API 23) قابل استفاده است، با Android SDK Platform 35 کامپایل میشود و همان پروفایل پایدار Subscriber نسخه وب را به FCM token متصل میکند. دریافت FCM روی دستگاه به Google Play services نیاز دارد.
| قابلیت | رفتار |
|---|---|
| ثبت خودکار توکن | اتصال FCM token به Subscriber ID و حفظ هویت هنگام تعویض توکن |
| نمایش اعلان | عنوان، متن، تصویر، دکمهها، لینک عمیق، Silent و Collapse ID |
| گزارشها | ثبت تحویل بعد از نمایش واقعی و ثبت کلیک با retry آفلاین |
| پروفایل | Alias عادی (External ID)، Custom Alias، Topic، Visit و RetenX Event |
| زبان اپ | قابل استفاده در پروژههای Kotlin و Java |
نصب از Maven Central، JitPack یا ماژول SDK
روش پیشنهادی، نصب مستقیم Dependency از Maven Central است. اگر Maven Central در دسترس پروژه نیست، میتوانید نسخه Tag شده همان مخزن رسمی GitHub را با JitPack نصب کنید. فایل ZIP سورس نیز برای نصب آفلاین یا افزودن ماژول pushfa کنار پروژه اندروید در دسترس است. فقط یکی از این سه روش را انتخاب کنید.
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
// فقط برای روش JitPack:
// maven { url = uri("https://jitpack.io") }
}
}
// app/build.gradle.kts
dependencies {
// روش پیشنهادی: Maven Central
implementation("com.pushfa:pushfa-android-sdk:2.0.4")
// روش جایگزین JitPack؛ با Dependency بالا همزمان اضافه نکنید:
// implementation("com.github.pushfa:pushfa-android-sdk:2.0.4")
}
// فقط برای نصب آفلاین از ZIP:
// include(":pushfa")
// project(":pushfa").projectDir = file("android-sdk/pushfa")
// implementation(project(":pushfa"))
ارتقا از 2.0.1، 2.0.2 یا 2.0.3 به 2.0.4
نسخه 2.0.4 اصلاح باز شدن لینک بدنه و دکمهها در Android 12+ و جایگزینی اعلانهای دارای collapse_id یکسان را همراه با انتشار امضاشده Maven Central ارائه میکند. از تگ 2.0.2 استفاده نکنید، چون آن تگ به سورس قدیمی بدون این اصلاحات اشاره میکند. اگر ماژول سورس را نصب کردهاید، کل پوشه android-sdk/pushfa قبلی را با پوشه نسخه جدید جایگزین کنید؛ فایلهای دو نسخه را Merge نکنید، چون PushfaClickReceiver حذف و PushfaNotificationClickActivity اضافه شده است.
| چه کسی | اقدام لازم |
|---|---|
| توسعهدهنده اپ | Dependency را ارتقا دهد یا ماژول سورس را کامل جایگزین کند، پروژه را Sync/Rebuild کند و یک بهروزرسانی عادی اپ منتشر کند. |
| کاربر نهایی اپ | فقط نسخه جدید اپ را از Google Play یا کانال قبلی نصب کند؛ حذف و نصب دوباره، عضویت مجدد یا اجازه جدید لازم نیست. |
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
}
}
// app/build.gradle.kts
dependencies {
implementation("com.pushfa:pushfa-android-sdk:2.0.4")
}
اتصال Firebase به اپلیکیشن
برای سرویس Android، فیلد Firebase config وب در پنل لازم نیست. اپ Android تنظیمات Client را از فایل google-services.json میخواند و سرور پوشفا برای ارسال پیام از Service Account همان Firebase Project استفاده میکند. در Firebase Console از Project overview روی Add app و سپس Android بزنید، Package Name دقیق applicationId اپ را ثبت کنید، فایل google-services.json را دانلود و در ریشه ماژول app قرار دهید.
// build.gradle.kts سطح پروژه
plugins {
id("com.google.gms.google-services") version "4.5.0" apply false
}
// app/build.gradle.kts
plugins {
id("com.android.application")
id("com.google.gms.google-services")
}
دریافت Service Account برای ارسال Android
در Firebase Console پروژه را باز کنید و از آیکن چرخدنده وارد Project settings شوید. تب Service accounts را باز کنید، در بخش Firebase Admin SDK روی Generate new private key بزنید و ساخت کلید را تایید کنید. فایل JSON دانلودشده را باز کنید و محتوای کامل آن را در فیلد Service Account پنل پوشفا قرار دهید. Firebase Project این فایل باید دقیقاً همان پروژه فایل google-services.json اپ باشد.
| اطلاعات | محل استفاده |
|---|---|
| Firebase config پنل | برای سرویس Android لازم نیست و در فرم نمایش داده نمیشود. |
| google-services.json | داخل پروژه Android در مسیر app/google-services.json قرار میگیرد و در پنل Paste نمیشود. |
| Service Account JSON | فقط در پنل پوشفا وارد میشود تا سرور بتواند از FCM HTTP v1 پیام ارسال کند. |
راهاندازی در Application
SDK را یک بار در Application.onCreate راهاندازی کنید. apiPublicKey همان کلید عمومی سرویس پوشفا است. آیکن کوچک باید یک drawable تکرنگ مناسب Status Bar باشد.
class App : Application() {
override fun onCreate() {
super.onCreate()
Pushfa.initialize(
this,
PushfaConfig(
apiPublicKey = "YOUR_PUBLIC_KEY",
smallIconResId = R.drawable.ic_stat_pushfa,
notificationChannelId = "marketing",
notificationChannelName = "Marketing notifications"
)
) { result ->
if (result.isSuccess) {
Log.d("Pushfa", "subscriber=" + result.value?.subscriberId)
} else {
Log.e("Pushfa", result.error?.message.orEmpty())
}
}
}
}
استفاده در پروژه Java
API عمومی SDK با Java نیز قابل استفاده است و PushfaCallback یک SAM interface است؛ بنابراین میتوان callback را با Lambda نوشت.
Pushfa.initialize(
this,
new PushfaConfig("YOUR_PUBLIC_KEY"),
result -> {
if (result.isSuccess()) {
Log.d("Pushfa", result.getValue().getSubscriberId());
} else {
Log.e("Pushfa", result.getError().getMessage());
}
}
);
اجازه اعلان در Android 13 و بالاتر
از Android 13 (API 33) نمایش اعلان نیاز به POST_NOTIFICATIONS دارد. SDK permission را در Manifest ادغام میکند؛ درخواست runtime را در زمان مناسب از Activity نشان دهید و بعد از تایید، ثبت Push را انجام دهید.
// برای نمایش پنجره Permission
Pushfa.requestNotificationPermission(this)
override fun onRequestPermissionsResult(
requestCode: Int,
permissions: Array<out String>,
grantResults: IntArray
) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults)
if (requestCode == Pushfa.DEFAULT_PERMISSION_REQUEST_CODE &&
Pushfa.areNotificationsEnabled(this)) {
Pushfa.registerForPush { result ->
Log.d("Pushfa", "registered=" + result.isSuccess)
}
}
}
متدهای عمومی SDK
همه متدهای شبکه asynchronous هستند و PushfaCallback روی Main Thread اجرا میشود. نتیجه دارای value، error و isSuccess است.
| متد | توضیح | خروجی |
|---|---|---|
| Pushfa.registerForPush(callback) | دریافت و ثبت FCM token پس از Permission | PushfaState |
| Pushfa.syncState(callback) | همگامسازی وضعیت معتبر از سرور | PushfaState |
| Pushfa.getSubscriberId() | شناسه پایدار مشترک روی این نصب | String? |
| Pushfa.getPushToken() | FCM token ذخیرهشده | String? |
| Pushfa.currentState() | نسخه Cache شده پروفایل، تاپیک و Aliasها | PushfaState? |
| Pushfa.areNotificationsEnabled(context) | بررسی Permission و تنظیمات اعلان سیستم | Boolean |
مدیریت تاپیکها
UUID تاپیک را از پنل سرویس دریافت کنید. دسترسی ثبت، خروج و خواندن بر اساس تنظیمات همان تاپیک در پوشفا کنترل میشود.
Pushfa.subscribeTopic("TOPIC_UUID") { result ->
Log.d("Pushfa", "topics=" + result.value)
}
Pushfa.unsubscribeTopic("TOPIC_UUID") { result -> }
Pushfa.getTopics { result ->
val topics = result.value.orEmpty()
}
External ID و شناسههای سفارشی
External ID همان Alias عادی و اصلی کاربر است و یک نوع شناسه جداگانه نیست. هر پروفایل فقط یک External ID دارد؛ در مقابل Custom Alias برای چند شناسه برچسبدار مانند mobile، crm_id یا tier استفاده میشود. مجوز خواندن/ثبت/حذف از تنظیمات Alias همان سرویس اعمال میشود.
// بعد از Login
Pushfa.setExternalId("USER-123") { result -> }
// حذف External ID هنگام Logout
Pushfa.setExternalId(null) { result -> }
Pushfa.addAlias("mobile", "09120000000") { result -> }
Pushfa.addAliases(
mapOf("crm_id" to "CRM-9", "tier" to "gold")
) { result -> }
Pushfa.removeAlias("tier") { result -> }
Pushfa.removeAliases(listOf("crm_id", "mobile")) { result -> }
Pushfa.getAliases { result -> }
ارسال رویداد RetenX
نام رویداد باید در یک Journey فعال یا متوقفشده سرویس استفاده شده باشد. params میتواند هر داده JSON معتبر و aliases میتواند شناسههای کاربر را همراه رویداد بهروز کند.
Pushfa.trackEvent(
eventName = "product_view",
params = mapOf(
"product_id" to 42,
"price" to 125000
),
aliases = mapOf("mobile" to "09120000000")
) { result ->
if (!result.isSuccess) {
Log.e("Pushfa", result.error?.message.orEmpty())
}
}
دریافت و شخصیسازی اعلان
به صورت پیشفرض SDK اعلان را در Foreground و Background نمایش میدهد و تصویر، حداکثر دو دکمه، Deep Link، Silent، Collapse ID، Additional Data و گزارش تحویل/کلیک را مدیریت میکند.
Pushfa.setNotificationListener { message ->
analytics.track("push_received", message.additionalData)
false // false: نمایش خودکار پوشفا ادامه پیدا کند
// true: اپ نمایش اعلان را خودش انجام داده است
}
لینک خارجی، Deep Link و مسیر داخلی اپ
کلیک بدنه اعلان و هر دو دکمه مستقیماً یک Activity PendingIntent را اجرا میکنند و در Android 12+ از BroadcastReceiver واسط استفاده نمیشود. لینک کامل مانند https://google.com، Android App Link تاییدشده و Custom Scheme با ACTION_VIEW باز میشود. مسیر نسبی مانند /promotion اپ را باز میکند و همان مسیر در intent.data و Pushfa.EXTRA_TARGET_URL قرار میگیرد.
private fun handlePushfaRoute(intent: Intent) {
val route = intent.getStringExtra(Pushfa.EXTRA_TARGET_URL)
?: intent.data?.path
when (route) {
"/promotion" -> openPromotionScreen()
}
}
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
handlePushfaRoute(intent)
}
رفتار Collapse ID در اندروید
اگر دو پیام collapse_id یکسان داشته باشند، SDK همان tag و همان notification ID را به NotificationManager میدهد؛ بنابراین اعلان دوم، اعلان نمایشدادهشده قبلی را بهروزرسانی و جایگزین میکند. بدون collapse_id هر پیام با id مستقل نمایش داده میشود.
{
"title": "وضعیت جدید سفارش",
"body": "سفارش شما ارسال شد",
"collapse_id": "order-42"
}
اگر اپ FirebaseMessagingService دارد
فقط یک سرویس باید رویداد MESSAGING_EVENT را دریافت کند. سرویس خودکار پوشفا را از Manifest ادغامشده حذف کنید و token/message را به SDK تحویل دهید. handleMessage برای پیام غیرپوشفا false برمیگرداند.
class AppMessagingService : FirebaseMessagingService() {
override fun onNewToken(token: String) {
Pushfa.handleNewToken(applicationContext, token)
}
override fun onMessageReceived(message: RemoteMessage) {
if (!Pushfa.handleMessage(applicationContext, message)) {
// پیام FCM غیر پوشفا
}
}
}
کلیدها و رفتار اعلان
SDK دادههای اعلان تولیدشده توسط Pushfa را بدون تغییر قرارداد نسخه وب مصرف میکند.
| کلید Payload | استفاده در Android SDK |
|---|---|
| id | شناسه اعلان و کلید گزارش |
| title / body | عنوان و متن اعلان |
| url | Deep Link یا لینک مقصد کلیک بدنه |
| image / icon | Big Picture یا Large Icon |
| actions | تعریف دکمهها همراه btnLeftUrl و btnRightUrl |
| ackUrl / clickAckUrl | گزارش تحویل و کلیک با WorkManager |
| collapse_idCollapse IDPro | جایگزینی اعلان قبلی با همان شناسه |
| silentپوش بیصدا | نمایش بدون صدا و لرزش |
| additional_dataAdditional DataPro | داده JSON سفارشی قابل خواندن از PushfaMessage |