نصب و راهاندازی Pushfa Android SDK
نصب نسخه 2.0.4 از Maven Central، اتصال Firebase، مقداردهی SDK در Application و فعالسازی Push در Android 13+.
۱. نصب از Maven Central؛ روش پیشنهادی
در repositories باید google() و mavenCentral() فعال باشند. سپس فقط dependency رسمی پوشفا را اضافه کنید. SDK خودش firebase-messaging را دریافت میکند و معمولاً نیازی به dependency جداگانه Firebase Messaging نیست.
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
}
}
// app/build.gradle.kts
dependencies {
implementation("com.pushfa:pushfa-android-sdk:2.0.4")
}
نصب جایگزین با JitPack یا سورس
JitPack فقط زمانی پیشنهاد میشود که Maven Central در دسترس پروژه نباشد. برای نصب آفلاین نیز میتوانید ماژول pushfa را از ZIP رسمی کنار پروژه قرار دهید.
// JitPack repository
maven { url = uri("https://jitpack.io") }
// JitPack dependency
implementation("com.github.pushfa:pushfa-android-sdk:2.0.4")
// یا ماژول سورس
include(":pushfa")
implementation(project(":pushfa"))
۲. Firebase را متصل کنید
Android App را داخل همان Firebase project سرویس پوشفا بسازید. applicationId باید دقیقاً با Package Name ثبتشده برابر باشد. google-services.json را داخل 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")
}
۳. SDK را در Application مقداردهی کنید
initialize را فقط یک بار در Application.onCreate اجرا کنید. SDK همان ابتدا شناسه ثابت مخاطب (Subscriber ID) را میسازد؛ اگر اجازه دریافت اعلان فعال و autoRegister=true باشد، توکن FCM را نیز خودکار دریافت و ثبت میکند.
class App : Application() {
override fun onCreate() {
super.onCreate()
Pushfa.initialize(
application = this,
config = PushfaConfig(
apiPublicKey = "YOUR_PUBLIC_KEY",
smallIconResId = R.drawable.ic_stat_pushfa,
notificationChannelId = "pushfa_default",
notificationChannelName = "اعلانهای پوشفا",
),
) { result ->
if (result.isSuccess) {
Log.d("Pushfa", "subscriber=${result.value?.subscriberId}")
Log.d("Pushfa", "token=${result.value?.pushToken}")
} else {
Log.e("Pushfa", "init failed", result.error)
}
}
}
}
ثبت Application در Manifest
<application
android:name=".App"
...>
</application>
تنظیمات کامل PushfaConfig
| گزینه | پیشفرض | کاربرد |
|---|---|---|
| apiPublicKey | اجباری | کلید عمومی سرویس پوشفا؛ کلید خصوصی را داخل APK قرار ندهید. |
| baseUrl | https://pushfa.com | آدرس سرور پوشفا؛ فقط برای محیط اختصاصی یا تست تغییر دهید. |
| autoRegister | true | اگر اجازه دریافت اعلان فعال باشد توکن را هنگام initialize خودکار دریافت و ثبت میکند. |
| autoDisplayNotifications | true | نمایش استاندارد پیام پس از دریافت؛ در حالت مدیریت کاملاً سفارشی false کنید. |
| trackVisits | true | ثبت Visit روزانه Subscriber برای تحلیل و RetenX. |
| notificationChannelId | pushfa_default | شناسه پایدار Notification Channel اندروید. |
| notificationChannelName | Pushfa notifications | نام قابلمشاهده Channel در تنظیمات سیستم. |
| notificationChannelImportance | IMPORTANCE_HIGH | اهمیت اولیه Channel؛ پس از ساختهشدن، کنترل نهایی با کاربر است. |
| smallIconResId | 0 | آیکن کوچک تکرنگ اعلان؛ در صورت صفر بودن SDK از آیکن اپ استفاده میکند. |
| accentColor | null | رنگ Accent اعلان بهصورت Android Color Int. |
۴. اجازه دریافت اعلان در Android 13+
SDK اجازه دریافت اعلان را در Manifest تعریف میکند، اما زمان نمایش پنجره سیستم با اپ شماست. پس از موافقت کاربر با دریافت اعلان، registerForPush را اجرا کنید. در Android 12 و پایینتر، initialize با تنظیم پیشفرض autoRegister=true معمولاً ثبت را خودکار انجام میدهد.
private fun registerPush() {
Pushfa.registerForPush { result ->
Log.d("Pushfa", "registered=${result.isSuccess}")
}
}
if (Pushfa.areNotificationsEnabled(this)) {
registerPush()
} else {
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)
) {
registerPush()
}
}
۵. راهاندازی را بررسی کنید
پس از اجرای اپ روی دستگاه واقعی، شناسه ثابت مخاطب (Subscriber ID) و توکن را از SDK بخوانید و همان سرویس را در پنل بررسی کنید. ثبت توکن توسط خود SDK انجام شده است و فراخوانی دستی endpoint لازم نیست.
Log.d("Pushfa", "SDK=${Pushfa.VERSION}")
Log.d("Pushfa", "subscriber=${Pushfa.getSubscriberId()}")
Log.d("Pushfa", "token=${Pushfa.getPushToken()}")
Log.d("Pushfa", "enabled=${Pushfa.areNotificationsEnabled(this)}")