نسخه‌های Android SDK؛ تفاوت 2.0.4 و 2.1.0
هر دو نسخه 2.0.4 و 2.1.0 کار می‌کنند و متدها و تنظیمات یکسانی دارند. این صفحه فقط تفاوت‌هایی را توضیح می‌دهد که برنامه‌نویس اپ باید بداند: دریافت توکن، پیام‌های قابل نمایش، displayNotification، خطای 403 و مراحل ارتقا.
کدام نسخه را نصب کنم؟
برای اپ جدید و برای به‌روزرسانی بعدی اپ‌های فعلی، نسخه 2.1.0 پیشنهاد می‌شود. نسخه 2.0.4 همچنان کار می‌کند و ارتقا اجباری نیست. نام کلاس‌ها، متدها و گزینه‌های PushfaConfig در هر دو نسخه یکسان است؛ برای ارتقا معمولاً فقط شماره نسخه Dependency عوض می‌شود و کافی است موارد بخش «ارتقا» را بررسی کنید.
// app/build.gradle.kts — فقط یکی از این دو خط را نگه دارید
dependencies {
implementation("com.pushfa:pushfa-android-sdk:2.1.0") // پیشنهادی
// implementation("com.pushfa:pushfa-android-sdk:2.0.4")
}
// بررسی نسخه نصب‌شده در زمان اجرا
Log.d("Pushfa", "SDK=${Pushfa.VERSION}")منابع هر نسخه
مرجع کامل هر نسخه README همان نسخه در GitHub است. اگر اپ شما روی 2.0.4 مانده است، از README و فایل‌های همان نسخه استفاده کنید.
| منبع | نسخه 2.1.0 (پیشنهادی) | نسخه 2.0.4 |
|---|---|---|
| Maven Central | com.pushfa:pushfa-android-sdk:2.1.0 | com.pushfa:pushfa-android-sdk:2.0.4 |
| JitPack | com.github.pushfa:pushfa-android-sdk:2.1.0 | com.github.pushfa:pushfa-android-sdk:2.0.4 |
| README کامل | README نسخه 2.1.0 | README نسخه 2.0.4 |
| ماژول سورس (ZIP) | دانلود 2.1.0 | دانلود 2.0.4 |
| یادداشت انتشار | Release 2.1.0 | Release 2.0.4 |
تفاوت‌ها از دید برنامه‌نویس اپ
| موضوع | نسخه 2.0.4 | نسخه 2.1.0 |
|---|---|---|
| متدها و PushfaConfig | API عمومی فعلی | بدون تغییر؛ کد فراخوانی SDK لازم نیست عوض شود |
| ساخت توکن FCM | Firebase هنگام اجرای اپ خودش توکن می‌سازد | توکن فقط پس از تأیید پوشفا، در initialize با autoRegister=true یا در registerForPush ساخته می‌شود |
| autoRegister=false | اگر اعلان‌ها فعال باشند، ممکن است توکن بدون registerForPush هم ثبت شود | هیچ ثبت خودکاری انجام نمی‌شود؛ registerForPush را بعد از رضایت کاربر صدا بزنید |
| Android 13 و بالاتر | پس از قبول اجازه اعلان، registerForPush | بدون تغییر |
| پیام‌های نمایش‌داده‌شده | هر پیام data دارای فیلد id | فقط پیام عادی یا لایتی که از پنل یا وب‌سرویس پوشفا برای همین دستگاه ارسال شده است |
| displayNotification | هر PushfaMessage را نمایش می‌دهد | فقط پیام دریافتی از پوشفا را با محتوای اصلی آن نمایش می‌دهد؛ پیام ساخته‌شده یا ویرایش‌شده false برمی‌گرداند |
| توقف ثبت مشترک جدید توسط پوشفا | نصب جدید خطای 403 می‌گیرد، ولی Firebase روی دستگاه توکن می‌سازد | نصب جدید خطای 403 می‌گیرد و هیچ توکنی از Firebase گرفته نمی‌شود |
| rawData پیام | فیلد sign را نادیده می‌گیرد | فیلد sign برای تأیید پیام لازم است؛ آن را تغییر یا حذف نکنید |
| Android 6.0 | ثبت بازدید روزانه و trackEvent با خطا متوقف می‌شوند | اصلاح شده است |
| ساعت و تاریخ گوشی | بی‌اثر | بی‌اثر؛ تأیید پیام به ساعت دستگاه وابسته نیست |
| تعداد درخواست به سرور پوشفا | مبنا | بیشتر از 2.0.4 نیست |
دریافت و ثبت توکن در نسخه 2.1.0
روش استفاده تغییر نکرده است؛ تفاوت در این است که تا پوشفا نصب را نپذیرد، هیچ توکنی از Firebase گرفته نمی‌شود. برای پوشفا خودتان FirebaseMessaging.getInstance().token را صدا نزنید و توکن و شناسه را از SDK بخوانید.
Application
Pushfa.initialize را یک بار در Application.onCreate اجرا کنید. با autoRegister=true (پیش‌فرض) و اعلان فعال، SDK پس از تأیید پوشفا توکن را می‌گیرد و ثبت می‌کند.
Android 13 و بالاتر
پس از قبول اجازه اعلان توسط کاربر، Pushfa.registerForPush را اجرا کنید؛ مثل نسخه قبل.
autoRegister=false
ثبت فقط با registerForPush انجام می‌شود؛ آن را پس از رضایت کاربر صدا بزنید.
خواندن نتیجه
پس از نتیجه موفق، Subscriber ID را با getSubscriberId بخوانید و hasPush را بررسی کنید. getPushToken تا پیش از ثبت موفق null است.
// Application.onCreate
Pushfa.initialize(this, PushfaConfig(apiPublicKey = "YOUR_PUBLIC_KEY")) { result ->
if (result.error?.httpStatus == 403) {
// پوشفا ثبت مشترک جدید را برای این سرویس متوقف کرده است.
}
}
// پس از قبول اجازه اعلان (Android 13+) یا رضایت کاربر (autoRegister = false)
Pushfa.registerForPush { result ->
val state = result.value
if (result.isSuccess && state != null && state.hasPush) {
saveSubscriberIdOnBackend(state.subscriberId)
}
}خطای 403؛ توقف ثبت مشترک جدید
پوشفا می‌تواند ثبت مشترک و توکن جدید را برای یک سرویس اندرویدی متوقف کند. در این حالت، در نصب جدید initialize و registerForPush، و همچنین Topic، Alias و Event، خطای PushfaException با httpStatus برابر 403 برمی‌گردانند. مشترکینی که قبلاً ثبت شده‌اند مثل قبل پیام می‌گیرند.
| نسخه | رفتار در نصب جدید |
|---|---|
| 2.1.0 | نه مشترکی ساخته می‌شود و نه توکنی از Firebase گرفته می‌شود. |
| 2.0.4 | مشترکی ساخته نمی‌شود، ولی Firebase روی دستگاه توکنی می‌سازد که در پوشفا ثبت نمی‌شود. |
نمایش پیام در نسخه 2.1.0
نسخه 2.1.0 فقط پیامی را نمایش می‌دهد یا به Listener می‌دهد که از پنل یا وب‌سرویس پوشفا برای همین دستگاه ارسال شده باشد؛ ارسال عادی و لایت هر دو پشتیبانی می‌شوند. پیامی که سرور خودتان مستقیم از Firebase و با فیلد id بفرستد نمایش داده نمی‌شود و handleMessage برای آن true برمی‌گرداند. پیام‌های غیرپوشفای بدون فیلد id مثل قبل false برمی‌گردانند و در FirebaseMessagingService خودتان قابل پردازش‌اند.
| اگر در اپ شما… | در 2.1.0 چه کنید؟ |
|---|---|
| پیام را از سرور خودتان مستقیم با Firebase می‌فرستید | ارسال را به وب‌سرویس پوشفا منتقل کنید، یا برای پیام‌های خودتان فیلد id نگذارید و آن‌ها را در Service خودتان نمایش دهید. |
| با displayNotification اعلان محلی می‌سازید | برای اعلان محلی از NotificationCompat خود اپ استفاده کنید؛ displayNotification فقط پیام دریافتی از پوشفا را نمایش می‌دهد. |
| در Listener متن پیام را تغییر می‌دهید و بعد displayNotification را صدا می‌زنید | تغییر روی اعلان اثری ندارد و محتوای اصلی نمایش داده می‌شود؛ برای ظاهر متفاوت، اعلان را خودتان بسازید و true برگردانید. |
| rawData را پردازش یا ذخیره می‌کنید | فیلد sign را نادیده بگیرید و rawData را تغییر ندهید. |
ارتقا از 2.0.x به 2.1.0
Dependency
نسخه را در Maven Central یا JitPack به 2.1.0 تغییر دهید. اگر ماژول سورس دارید، کل پوشه android-sdk/pushfa را با پوشه نسخه جدید جایگزین کنید و فایل‌ها را Merge نکنید.
Manifest
اگر در Manifest اپ firebase_messaging_auto_init_enabled را true کرده‌اید، آن خط را حذف کنید. آن را با tools:replace روی true نگذارید؛ در این صورت توقف ثبت مشترک جدید پوشفا روی اپ شما عمل نمی‌کند.
autoRegister=false
مطمئن شوید registerForPush پس از رضایت کاربر اجرا می‌شود؛ ثبت خودکار دیگری وجود ندارد.
پیام‌ها
موارد جدول «نمایش پیام در نسخه 2.1.0» را بررسی کنید؛ به‌خصوص ارسال مستقیم از Firebase و ساخت اعلان محلی با displayNotification.
انتشار
پروژه را Sync و Rebuild و یک به‌روزرسانی عادی اپ منتشر کنید. حذف و نصب دوباره اپ لازم نیست؛ Subscriber ID، توکن، Alias و Topicهای کاربران فعلی حفظ می‌شوند.
اگر فعلاً روی 2.0.4 می‌مانید
اپ بدون تغییر کار می‌کند و پیام‌های پوشفا مثل قبل نمایش داده می‌شوند. فیلد sign که در rawData پیام‌ها می‌بینید مربوط به نسخه جدید است و این نسخه آن را نادیده می‌گیرد. اگر پوشفا ثبت مشترک جدید سرویس شما را متوقف کند، نصب‌های جدید خطای 403 می‌گیرند. اگر اپ روی Android 6.0 هم اجرا می‌شود، برای کارکرد درست ثبت بازدید و trackEvent به 2.1.0 ارتقا دهید. مرجع کامل استفاده از این نسخه README نسخه 2.0.4 است.