SDK اندروید v2
راهنمای نصب Pushfa Android SDK v2 برای اپلیکیشنهای اندروید؛ شامل ثبت FCM، Subscriber ID، تاپیک، External ID، شناسههای سفارشی، رویدادها و مدیریت کامل اعلان.
قابلیتها و پیشنیازها
این SDK برای همه اپلیکیشنهای Native Android با حداقل Android 6.0 (API 23) قابل استفاده است و همان پروفایل پایدار Subscriber نسخه وب را به FCM token متصل میکند. دریافت FCM روی دستگاه به Google Play services نیاز دارد.
| قابلیت | رفتار |
|---|---|
| ثبت خودکار توکن | اتصال FCM token به Subscriber ID و حفظ هویت هنگام تعویض توکن |
| نمایش اعلان | عنوان، متن، تصویر، دکمهها، لینک عمیق، Silent و Collapse ID |
| گزارشها | ثبت تحویل بعد از نمایش واقعی و ثبت کلیک با retry آفلاین |
| پروفایل | External ID، Custom Alias، Topic، Visit و RetenX Event |
| زبان اپ | قابل استفاده در پروژههای Kotlin و Java |
دانلود و افزودن ماژول SDK
بسته سورس SDK را دانلود و کنار پروژه اندروید Extract کنید، سپس ماژول pushfa را در settings.gradle.kts معرفی کنید.
// settings.gradle.kts
include(":pushfa")
project(":pushfa").projectDir = file("android-sdk/pushfa")
// build.gradle.kts سطح پروژه (نسخههای سازگار با پروژه خود را نگه دارید)
plugins {
id("com.android.library") version "8.12.0" apply false
id("org.jetbrains.kotlin.android") version "2.2.20" apply false
}
// app/build.gradle.kts
dependencies {
implementation(project(":pushfa"))
}
اتصال Firebase به اپلیکیشن
اپ Android را در همان Firebase Project مورد استفاده سرویس پوشفا ثبت کنید، فایل google-services.json مخصوص package name اپ را در پوشه app قرار دهید و Google Services plugin را فعال کنید.
// 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")
}
راهاندازی در 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 برای شناسه اصلی کاربر و 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: اپ نمایش اعلان را خودش انجام داده است
}
اگر اپ 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_id Collapse ID Pro | جایگزینی اعلان قبلی با همان شناسه |
| silent پوش بیصدا | نمایش بدون صدا و لرزش |
| additional_data Additional Data (JSON) Pro | داده JSON سفارشی قابل خواندن از PushfaMessage |