Android SDK v2 Android

SDK اندروید v2

راهنمای نصب Pushfa Android SDK v2 از Maven Central، JitPack یا سورس GitHub؛ شامل ثبت FCM، Subscriber ID، تاپیک، External ID (همان Alias اصلی)، شناسه‌های سفارشی، رویدادها و مدیریت کامل اعلان.

Push اپ Android اعلان پوش در اپلیکیشن اندروید با Firebase و Pushfa SDK پوشفاپیام جدید برای شما Android PushPushfa SDK + Firebase Cloud Messaging

مخزن رسمی و راهنمای کامل GitHub

سورس رسمی Pushfa Android SDK، آخرین README فارسی، نمونه‌کد همه متدها و تاریخچه نسخه‌ها در مخزن رسمی GitHub پوشفا نگهداری می‌شود. برای نصب نسخه فعلی از 2.0.4 استفاده کنید و برای مشاهده راهنمای کامل و تغییرات نسخه‌های بعدی همیشه README همین مخزن را مرجع قرار دهید.

برای استفاده عادی نیازی به Clone کردن سورس نیست؛ روش پیشنهادی نصب Dependency از Maven Central است. JitPack نیز همان نسخه را مستقیماً از Tag رسمی همین مخزن GitHub ارائه می‌کند.

قابلیت‌ها و پیش‌نیازها

این SDK برای همه اپلیکیشن‌های Native Android با حداقل Android 6.0 (API 23) قابل استفاده است، با Android SDK Platform 35 کامپایل می‌شود و همان پروفایل پایدار Subscriber نسخه وب را به FCM token متصل می‌کند. دریافت FCM روی دستگاه به Google Play services نیاز دارد.

پروژه Firebase اپلیکیشن باید با Firebase تنظیم‌شده برای همان سرویس پوشفا یکسان باشد. Service Account یک پروژه نمی‌تواند به FCM token پروژه دیگری پیام ارسال کند.
قابلیترفتار
ثبت خودکار توکن اتصال FCM token به Subscriber ID و حفظ هویت هنگام تعویض توکن
نمایش اعلان عنوان، متن، تصویر، دکمه‌ها، لینک عمیق، Silent و Collapse ID
گزارش‌ها ثبت تحویل بعد از نمایش واقعی و ثبت کلیک با retry آفلاین
پروفایل Alias عادی (External ID)، Custom Alias، Topic، Visit و RetenX Event
زبان اپ قابل استفاده در پروژه‌های Kotlin و Java

نصب از Maven Central، JitPack یا ماژول SDK

روش پیشنهادی، نصب مستقیم Dependency از Maven Central است. اگر Maven Central در دسترس پروژه نیست، می‌توانید نسخه Tag شده همان مخزن رسمی GitHub را با JitPack نصب کنید. فایل ZIP سورس نیز برای نصب آفلاین یا افزودن ماژول pushfa کنار پروژه اندروید در دسترس است. فقط یکی از این سه روش را انتخاب کنید.

نسخه 2.0.4 در Maven Central و JitPack منتشر و بررسی شده است. روش پیشنهادی، مختصات com.pushfa:pushfa-android-sdk:2.0.4 با mavenCentral() است. برای JitPack از com.github.pushfa:pushfa-android-sdk:2.0.4 استفاده کنید. این دو Dependency را هم‌زمان اضافه نکنید؛ AAR نهایی هر دو انتشار دارای SHA-256 یکسان است.
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()

        // فقط برای روش JitPack:
        // maven { url = uri("https://jitpack.io") }
    }
}

// app/build.gradle.kts
dependencies {
    // روش پیشنهادی: Maven Central
    implementation("com.pushfa:pushfa-android-sdk:2.0.4")

    // روش جایگزین JitPack؛ با Dependency بالا هم‌زمان اضافه نکنید:
    // implementation("com.github.pushfa:pushfa-android-sdk:2.0.4")
}

// فقط برای نصب آفلاین از ZIP:
// include(":pushfa")
// project(":pushfa").projectDir = file("android-sdk/pushfa")
// implementation(project(":pushfa"))

ارتقا از 2.0.1، 2.0.2 یا 2.0.3 به 2.0.4

نسخه 2.0.4 اصلاح باز شدن لینک بدنه و دکمه‌ها در Android 12+ و جایگزینی اعلان‌های دارای collapse_id یکسان را همراه با انتشار امضاشده Maven Central ارائه می‌کند. از تگ 2.0.2 استفاده نکنید، چون آن تگ به سورس قدیمی بدون این اصلاحات اشاره می‌کند. اگر ماژول سورس را نصب کرده‌اید، کل پوشه android-sdk/pushfa قبلی را با پوشه نسخه جدید جایگزین کنید؛ فایل‌های دو نسخه را Merge نکنید، چون PushfaClickReceiver حذف و PushfaNotificationClickActivity اضافه شده است.

نسخه 2.0.4 در Maven Central و JitPack تأیید شده است؛ برای نسخه‌های بعدی نیز فقط پس از Build و Resolve موفق مختصات جدید را اعلام کنید. از کاربر نخواهید اپ قبلی را Uninstall کند؛ حذف اپ داده محلی Subscriber و وضعیت FCM را پاک می‌کند. اعلان‌های قدیمی نیز به‌صورت گذشته‌نگر اصلاح نمی‌شوند؛ برای تست Collapse آن‌ها را یک‌بار پاک کنید و سپس دو پیام جدید با collapse_id کاملاً یکسان بفرستید.
چه کسیاقدام لازم
توسعه‌دهنده اپ Dependency را ارتقا دهد یا ماژول سورس را کامل جایگزین کند، پروژه را Sync/Rebuild کند و یک به‌روزرسانی عادی اپ منتشر کند.
کاربر نهایی اپ فقط نسخه جدید اپ را از Google Play یا کانال قبلی نصب کند؛ حذف و نصب دوباره، عضویت مجدد یا اجازه جدید لازم نیست.
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.pushfa:pushfa-android-sdk:2.0.4")
}

اتصال Firebase به اپلیکیشن

برای سرویس Android، فیلد Firebase config وب در پنل لازم نیست. اپ Android تنظیمات Client را از فایل google-services.json می‌خواند و سرور پوشفا برای ارسال پیام از Service Account همان Firebase Project استفاده می‌کند. در Firebase Console از Project overview روی Add app و سپس Android بزنید، Package Name دقیق applicationId اپ را ثبت کنید، فایل google-services.json را دانلود و در ریشه ماژول app قرار دهید.

مسیر فایل باید app/google-services.json باشد و نام فایل نباید به google-services (1).json یا نام مشابه تغییر کند. این فایل شامل شناسه‌های غیرمحرمانه اپ است؛ Service Account کلید خصوصی و محرمانه سرور است و هرگز نباید داخل اپلیکیشن، APK یا GitHub قرار بگیرد.
// 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")
}

دریافت Service Account برای ارسال Android

در Firebase Console پروژه را باز کنید و از آیکن چرخ‌دنده وارد Project settings شوید. تب Service accounts را باز کنید، در بخش Firebase Admin SDK روی Generate new private key بزنید و ساخت کلید را تایید کنید. فایل JSON دانلودشده را باز کنید و محتوای کامل آن را در فیلد Service Account پنل پوشفا قرار دهید. Firebase Project این فایل باید دقیقاً همان پروژه فایل google-services.json اپ باشد.

Service Account یک کلید خصوصی است. آن را داخل سورس اپ، فایل ZIP عمومی، GitHub یا پیام پشتیبانی ارسال نکنید. اگر افشا شد، کلید را از Google Cloud IAM حذف و یک کلید جدید ایجاد کنید.
اطلاعاتمحل استفاده
Firebase config پنل برای سرویس Android لازم نیست و در فرم نمایش داده نمی‌شود.
google-services.json داخل پروژه Android در مسیر app/google-services.json قرار می‌گیرد و در پنل Paste نمی‌شود.
Service Account JSON فقط در پنل پوشفا وارد می‌شود تا سرور بتواند از FCM HTTP v1 پیام ارسال کند.

راه‌اندازی در 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 همان Alias عادی و اصلی کاربر است و یک نوع شناسه جداگانه نیست. هر پروفایل فقط یک 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: اپ نمایش اعلان را خودش انجام داده است
}

لینک خارجی، Deep Link و مسیر داخلی اپ

کلیک بدنه اعلان و هر دو دکمه مستقیماً یک Activity PendingIntent را اجرا می‌کنند و در Android 12+ از BroadcastReceiver واسط استفاده نمی‌شود. لینک کامل مانند https://google.com، Android App Link تاییدشده و Custom Scheme با ACTION_VIEW باز می‌شود. مسیر نسبی مانند /promotion اپ را باز می‌کند و همان مسیر در intent.data و Pushfa.EXTRA_TARGET_URL قرار می‌گیرد.

handlePushfaRoute را در onCreate نیز برای حالتی که اپ بسته بوده اجرا کنید. Pushfa.EXTRA_ACTION_ID مشخص می‌کند کلیک مربوط به body، btn-left یا btn-right بوده است.
private fun handlePushfaRoute(intent: Intent) {
    val route = intent.getStringExtra(Pushfa.EXTRA_TARGET_URL)
        ?: intent.data?.path

    when (route) {
        "/promotion" -> openPromotionScreen()
    }
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    handlePushfaRoute(intent)
}

رفتار Collapse ID در اندروید

اگر دو پیام collapse_id یکسان داشته باشند، SDK همان tag و همان notification ID را به NotificationManager می‌دهد؛ بنابراین اعلان دوم، اعلان نمایش‌داده‌شده قبلی را به‌روزرسانی و جایگزین می‌کند. بدون collapse_id هر پیام با id مستقل نمایش داده می‌شود.

بعد از ارتقا به SDK 2.0.4، از یک مقدار collapse_id کاملاً یکسان در ارسال‌های متوالی استفاده کنید.
{
  "title": "وضعیت جدید سفارش",
  "body": "سفارش شما ارسال شد",
  "collapse_id": "order-42"
}

اگر اپ 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_idCollapse IDPro جایگزینی اعلان قبلی با همان شناسه
silentپوش بی‌صدا نمایش بدون صدا و لرزش
additional_dataAdditional DataPro داده JSON سفارشی قابل خواندن از PushfaMessage
Ctrl+I