راهنمای Pushfa iOS SDK
نصب SDK نیتیو پوشفا با Swift Package، اتصال Firebase و APNs، ثبت دستگاه و دریافت اعلان در iOS.
قابلیتهای نسخه 1.0.0
SDK نیتیو iOS توکن APNs/FCM و Subscriber ID را مدیریت میکند و Topic، External ID، Custom Alias، RetenX Event، Deep Link، Additional Data، Rich Notification و گزارش تحویل/کلیک را روی زیرساخت مشترک پوشفا ارائه میدهد.
| قابلیت | API یا رفتار |
|---|---|
| راهاندازی | Pushfa.initialize() |
| Permission و ثبت Push | requestNotificationPermission() / registerForPush() |
| شناسه نصب | Pushfa.subscriberId / Pushfa.pushToken |
| Topic | subscribeTopic() / unsubscribeTopic() / getTopics() |
| هویت | setExternalId() / addAlias(es) / removeAlias(es) |
| RetenX | trackEvent() |
| دریافت سفارشی | notificationHandler / notificationTapHandler |
| تصویر و Delivery | PushfaNotificationServiceExtension |
پیشنیازهای Firebase و Apple
Apple App را در Firebase بسازید
Bundle ID باید دقیقاً با Target اصلی Xcode یکسان باشد و GoogleService-Info.plist به همان Target اضافه شود.
Push Notifications را فعال کنید
Capability مربوط به Push Notifications و Background Modes > Remote notifications را در Xcode فعال کنید.
APNs Key را در Firebase بارگذاری کنید
APNs Authentication Key مربوط به Apple Developer Team را در تب Cloud Messaging پروژه Firebase ثبت کنید.
Service Account را در پوشفا ثبت کنید
JSON سرویساکانت همان Firebase Project را فقط در پنل پوشفا وارد کنید؛ این فایل نباید داخل اپ باشد.
نصب مستقیم از GitHub با Swift Package Manager
روش پیشنهادی این است که در Xcode از File > Add Package Dependencies، URL رسمی زیر را وارد کنید. Dependency Rule را روی Up to Next Major Version و حداقل نسخه را روی 1.0.0 قرار دهید. Product اصلی Pushfa فقط به Target اپ و Product مستقل PushfaExtension فقط به Notification Service Extension متصل میشود.
https://github.com/pushfa/pushfa-ios-sdk.gitinitialize و نصب جایگزین با ZIP
پس از نصب Product با نام Pushfa، SDK را initialize کنید. اگر GitHub در دسترس نیست، ZIP رسمی را دانلود و پوشهای را که Package.swift در ریشه آن است بهعنوان Local Package به Xcode اضافه کنید.
import Pushfa
Task { @MainActor in
try await Pushfa.initialize(
PushfaConfig(
apiPublicKey: "YOUR_PUBLIC_KEY",
deepLinkBaseURL: URL(string: "myapp://")
)
)
}
let granted = try await Pushfa.requestNotificationPermission()Rich Notification و گزارش تحویل
برای دانلود تصویر قبل از نمایش و ثبت دقیقتر Delivery در پسزمینه، یک Notification Service Extension بسازید. Product اصلی Pushfa را فقط به Target اپ و Product مستقل PushfaExtension را فقط به Target اکستنشن اضافه کنید.
import PushfaExtension
import UserNotifications
final class NotificationService: UNNotificationServiceExtension {
private var pushfaTask: PushfaNotificationServiceTask?
override func didReceive(
_ request: UNNotificationRequest,
withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
) {
pushfaTask = PushfaNotificationServiceExtension.process(
request,
contentHandler: contentHandler
)
}
override func serviceExtensionTimeWillExpire() {
pushfaTask?.serviceExtensionTimeWillExpire()
pushfaTask = nil
}
}Topic، هویت و RetenX
try await Pushfa.subscribeTopic("TOPIC_UUID")
try await Pushfa.setExternalId("user-123")
try await Pushfa.addAlias(label: "crm_id", value: "8451")
try await Pushfa.trackEvent(
"purchase",
parameters: ["order_id": 9182, "amount": 120000]
)