مستندات پوشفا
Android SDK v2

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 نیاز دارد.

پروژه Firebase اپلیکیشن باید با Firebase تنظیم‌شده برای همان سرویس پوشفا یکسان باشد. Service Account یک پروژه نمی‌تواند به FCM token پروژه دیگری پیام ارسال کند.
قابلیت رفتار
ثبت خودکار توکن اتصال 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 معرفی کنید.

ماژول برای انتشار Maven نیز آماده است و پس از انتشار مخزن می‌توان از مختصات com.pushfa:pushfa-android-sdk:2.0.0 استفاده کرد.
// 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 را فعال کنید.

فایل google-services.json شامل شناسه‌های عمومی پروژه Firebase است؛ کلید خصوصی پوشفا و فایل 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")
}

راه‌اندازی در Application

SDK را یک بار در Application.onCreate راه‌اندازی کنید. apiPublicKey همان کلید عمومی سرویس پوشفا است. آیکن کوچک باید یک drawable تک‌رنگ مناسب Status Bar باشد.

کلاس Application را با android:name در AndroidManifest اپ ثبت کنید. SDK هیچ api_private_key دریافت نمی‌کند.
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، Subscriber ID ساخته می‌شود و Alias/Topic/Event قابل استفاده است؛ اما FCM token به عنوان 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 و گزارش تحویل/کلیک را مدیریت می‌کند.

اگر Listener مقدار true برگرداند، گزارش تحویل خودکار ارسال نمی‌شود. برای نمایش با Renderer استاندارد و ثبت Delivery از Pushfa.displayNotification(context, message) استفاده کنید.
Pushfa.setNotificationListener { message ->
    analytics.track("push_received", message.additionalData)

    false // false: نمایش خودکار پوشفا ادامه پیدا کند
          // true: اپ نمایش اعلان را خودش انجام داده است
}

اگر اپ FirebaseMessagingService دارد

فقط یک سرویس باید رویداد MESSAGING_EVENT را دریافت کند. سرویس خودکار پوشفا را از Manifest ادغام‌شده حذف کنید و token/message را به SDK تحویل دهید. handleMessage برای پیام غیرپوشفا false برمی‌گرداند.

در این حالت با tools:node="remove" سرویس com.pushfa.sdk.PushfaFirebaseMessagingService را از Manifest اپ حذف کنید تا دو FirebaseMessagingService فعال نباشد.
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 را بدون تغییر قرارداد نسخه وب مصرف می‌کند.

گزارش تحویل فقط بعد از پذیرش واقعی اعلان توسط NotificationManager صف می‌شود. گزارش‌های ناموفق تا بازگشت اینترنت با WorkManager تکرار می‌شوند.
کلید 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