نصب و راهاندازی 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 را میسازد؛ اگر permission فعال و autoRegister=true باشد، FCM token را نیز خودکار دریافت و ثبت میکند.
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 | اگر permission فعال باشد token را هنگام 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. |
۴. permission در Android 13+
SDK permission را در Manifest تعریف میکند، اما زمان نمایش پنجره سیستم با اپ شماست. پس از قبول permission، 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 و token را از SDK بخوانید و همان سرویس را در پنل بررسی کنید. ثبت token توسط خود 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)}")
