پوشفا
Android SDK 2.0.4 Android

نصب و راه‌اندازی 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 نیست.

اگر از Maven Central استفاده می‌کنید، dependency مربوط به JitPack را هم‌زمان اضافه نکنید.
// 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 را فعال کنید.

Firebase project فایل google-services.json و Service Account ثبت‌شده در سرویس پوشفا باید یکی باشد.
// 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

مجوزهای INTERNET و POST_NOTIFICATIONS و سرویس Firebase پوشفا از Manifest خود SDK با Manifest اپ Merge می‌شوند.
<application
    android:name=".App"
    ...>
</application>

تنظیمات کامل PushfaConfig

notificationChannelId را بعد از انتشار بی‌دلیل عوض نکنید؛ هر ID جدید یک Channel مستقل با تنظیمات جداگانه کاربر می‌سازد.
گزینهپیش‌فرضکاربرد
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)}")