مستندات راهنمای توسعه‌دهندگان توسعه اپ Android مرجع کامل متدهای Pushfa Android SDK
Android SDK API Android

مرجع کامل متدهای Pushfa Android SDK

متدهای عمومی نسخه 2.0.4 را همراه با خروجی و کاربرد هرکدام بشناسید و از نمونه‌های Kotlin و Java برای استفاده از آن‌ها کمک بگیرید.

راه‌اندازی، وضعیت و اجازه دریافت اعلان

متدخروجیکاربرد
Pushfa.initialize(application, config, callback) PushfaState مقداردهی SDK، ساخت Subscriber، ثبت خودکار توکن، Visit و همگام‌سازی state
Pushfa.currentState() PushfaState? خواندن فوری آخرین state محلی بدون شبکه
Pushfa.syncState(callback) PushfaState دریافت وضعیت معتبر Subscriber از سرور
Pushfa.getSubscriberId() String? شناسه پایدار همین نصب؛ حتی پیش از اجازه دریافت اعلان ساخته می‌شود. در دریافت، ذخیره و ارسال، Subscriber ID به دلیل پایداری بیشتر توصیه می‌شود؛ برای یک مخاطب از subscriber_id و برای چند مخاطب از subscriber_ids[] استفاده کنید. توکن FCM ممکن است تغییر کند و کلیدهای fcm_token و fcm_tokens[] فقط برای سازگاری قدیمی پشتیبانی می‌شوند.
Pushfa.getPushToken() String? توکن FCM ثبت‌شده فعلی؛ ممکن است null باشد. در دریافت، ذخیره و ارسال، Subscriber ID به دلیل پایداری بیشتر توصیه می‌شود؛ برای یک مخاطب از subscriber_id و برای چند مخاطب از subscriber_ids[] استفاده کنید. توکن FCM ممکن است تغییر کند و کلیدهای fcm_token و fcm_tokens[] فقط برای سازگاری قدیمی پشتیبانی می‌شوند.
Pushfa.areNotificationsEnabled(context) Boolean بررسی اجازه دریافت اعلان و فعال‌بودن اعلان‌های اپ در سیستم
Pushfa.requestNotificationPermission(activity, requestCode) Boolean نمایش اجازه دریافت اعلان در Android 13+؛ true یعنی درخواست اجرا شد
Pushfa.registerForPush(callback) PushfaState دریافت و ثبت توکن FCM بعد از فعال‌بودن اجازه دریافت اعلان

Topic و هویت

متدخروجی Callbackکاربرد
subscribeTopic(topicUuid) List<String> عضویت با UUID تاپیک و بازگرداندن فهرست فعلی
unsubscribeTopic(topicUuid) List<String> لغو عضویت Topic
getTopics() List<String> دریافت فهرست معتبر تاپیک‌ها از سرور
setExternalId(externalId) String? ثبت شناسه اصلی کاربر؛ null یعنی حذف در Logout
getExternalId() String? خواندن شناسه کاربر در سیستم شما (External ID) معتبر از سرور
addAlias(label, value) Map<String,String> افزودن یا به‌روزرسانی یک Alias
addAliases(map) Map<String,String> ثبت چند Alias در یک درخواست
removeAlias(label) Map<String,String> حذف یک Alias
removeAliases(labels) Map<String,String> حذف چند Alias
getAliases() Map<String,String> دریافت شناسه‌های مستعار معتبر از سرور

Event، دریافت و نمایش

متدخروجیکاربرد
trackEvent(eventName, params, aliases) PushfaEventResult ارسال event و داده‌های RetenX همراه Alias اختیاری
setNotificationListener(listener) Unit مشاهده پیام پیش از نمایش خودکار؛ null یعنی حذف Listener
displayNotification(context, message) Boolean اجرای Renderer استاندارد و Queue کردن گزارش تحویل
handleMessage(context, remoteMessage) Boolean تحویل پیام از FirebaseMessagingService اختصاصی؛ false برای پیام غیرپوشفا
handleNewToken(context, token) Unit تحویل توکن جدید از Service اختصاصی به SDK

ثابت‌های عمومی

ثابتمقدار/کاربرد
Pushfa.VERSION نسخه SDK در زمان اجرا؛ برای این راهنما 2.0.4
DEFAULT_PERMISSION_REQUEST_CODE کد پیش‌فرض 7402 برای اجازه دریافت اعلان
EXTRA_TARGET_URL مقصد نسبی اعلان در Intent اپ
EXTRA_NOTIFICATION_ID شناسه اعلان کلیک‌شده
EXTRA_ACTION_ID body یا شناسه دکمه مانند btn-left و btn-right

مدل Callback و خطا

متدهای شبکه Async هستند و Callback روی Main Thread اجرا می‌شود. نتیجه همیشه PushfaResult<T> است. isSuccess را بررسی کنید؛ value نتیجه موفق و error شامل message و httpStatus است. getOrThrow نیز در صورت خطا exception پرتاب می‌کند.

Pushfa.syncState { result ->
    if (result.isSuccess) {
        val state = result.value
        Log.d("Pushfa", "topics=${state?.topics}")
    } else {
        Log.e("Pushfa", "http=${result.error?.httpStatus}", result.error)
    }
}

فیلدهای PushfaState

فیلدمعنی
subscriberId شناسه پایدار نصب در پوشفا
pushToken توکن فنی فعلی یا null؛ برای دریافت، ذخیره و ارسال، subscriberId توصیه می‌شود
hasPush آیا توکن معتبر Push به پروفایل متصل است
externalId شناسه اصلی کاربر در سیستم شما
aliases شناسه‌های مستعار برچسب‌دار پروفایل
topics UUID تاپیک‌های عضو شده

شناسه پایدار مخاطب و سازگاری با کلیدهای قدیمی

از subscriber_id برای یک مخاطب و subscriber_ids[] برای چند مخاطب استفاده کنید؛ این شناسه‌ها با چرخش توکن تغییر نمی‌کنند و پایدارترند. کلیدهای fcm_token و fcm_tokens[] به دلیل پایداری کمتر منسوخ شده‌اند، اما برای سازگاری همچنان پشتیبانی می‌شوند. ارسال هم‌زمان subscriber_id و fcm_token یا subscriber_ids و fcm_tokens، حتی با مقدار خالی، خطای اعتبارسنجی 422 می‌دهد.

Ctrl+I