APNS#

تُسهّل واجهة خدمة الإشعارات الفورية من Apple (Apple Push Notification Service، أو APNS) في Vapor المصادقة وإرسال الإشعارات الفورية إلى أجهزة Apple. وهي مبنية على APNSwift.

البدء#

لنلقِ نظرة على كيفية البدء باستخدام APNS.

الحزمة#

الخطوة الأولى لاستخدام APNS هي إضافة الحزمة إلى اعتمادياتك (dependencies).

// swift-tools-version:5.8
import PackageDescription

let package = Package(
    name: "my-app",
    dependencies: [
         // Other dependencies...
        .package(url: "https://github.com/vapor/apns.git", from: "4.0.0"),
    ],
    targets: [
        .target(name: "App", dependencies: [
            // Other dependencies...
            .product(name: "VaporAPNS", package: "apns")
        ]),
        // Other targets...
    ]
)

إذا حرّرت الملف الوصفي (manifest) مباشرة داخل Xcode، فسيلتقط التغييرات تلقائيًا ويجلب الاعتمادية الجديدة عند حفظ الملف. وإلا، من الطرفية (Terminal)، شغّل swift package resolve لجلب الاعتمادية الجديدة.

الإعداد#

تضيف وحدة APNS خاصية جديدة apns إلى Application. لإرسال الإشعارات الفورية، ستحتاج إلى ضبط الخاصية configuration ببيانات اعتمادك.

import APNS
import VaporAPNS
import APNSCore

// Configure APNS using JWT authentication.
let apnsConfig = APNSClientConfiguration(
    authenticationMethod: .jwt(
        privateKey: try .loadFrom(string: "<#key.p8 content#>"),
        keyIdentifier: "<#key identifier#>",
        teamIdentifier: "<#team identifier#>"
    ),
    environment: .development
)
app.apns.containers.use(
    apnsConfig,
    eventLoopGroupProvider: .shared(app.eventLoopGroup),
    responseDecoder: JSONDecoder(),
    requestEncoder: JSONEncoder(),
    as: .default
)

املأ العناصر النائبة (placeholders) ببيانات اعتمادك. يُظهر المثال أعلاه المصادقة القائمة على JWT باستخدام مفتاح .p8 الذي تحصل عليه من بوابة مطوّري Apple. أما المصادقة القائمة على TLS باستخدام شهادة، فاستخدم طريقة المصادقة .tls:

authenticationMethod: .tls(
    privateKeyPath: <#path to private key#>,
    pemPath: <#path to pem file#>,
    pemPassword: <#optional pem password#>
)

الإرسال#

بمجرد إعداد APNS، يمكنك إرسال الإشعارات الفورية باستخدام الطريقة apns.send على Application أو Request.

// Custom Codable Payload
struct Payload: Codable {
    let acme1: String
    let acme2: Int
}
// Create push notification Alert
let dt = "70075697aa918ebddd64efb165f5b9cb92ce095f1c4c76d995b384c623a258bb"
let payload = Payload(acme1: "hey", acme2: 2)
let alert = APNSAlertNotification(
    alert: .init(
        title: .raw("Hello"),
        subtitle: .raw("This is a test from vapor/apns")
    ),
    expiration: .immediately,
    priority: .immediately,
    topic: "<#my topic#>",
    payload: payload
)
// Send the notification
try! await req.apns.client.sendAlertNotification(
    alert, 
    deviceToken: dt, 
    deadline: .distantFuture
)

استخدم req.apns كلما كنت داخل معالج مسار.

// Sends a push notification.
app.get("test-push") { req async throws -> HTTPStatus in
    try await req.apns.client.send(...)
    return .ok
}

يقبل المُعامِل الأول تنبيه الإشعار الفوري (push notification alert)، والمُعامِل الثاني هو رمز الجهاز الهدف (device token).

Alert#

APNSAlertNotification هي البيانات الوصفية (metadata) الفعلية لتنبيه الإشعار الفوري المراد إرساله. تتوفّر تفاصيل أكثر حول تفاصيل كل خاصية هنا. وهي تتبع مخطّط تسمية واحد لواحد مذكورًا في وثائق Apple.

let alert = APNSAlertNotification(
    alert: .init(
        title: .raw("Hello"),
        subtitle: .raw("This is a test from vapor/apns")
    ),
    expiration: .immediately,
    priority: .immediately,
    topic: "<#my topic#>",
    payload: payload
)

يمكن تمرير هذا النوع مباشرة إلى الطريقة send.

بيانات الإشعار المخصّصة#

توفّر Apple للمهندسين القدرة على إضافة بيانات حمولة (payload) مخصّصة إلى كل إشعار. لتيسير ذلك، نقبل توافق Codable لمُعامِل الحمولة على جميع واجهات send.

// Custom Codable Payload
struct Payload: Codable {
    let acme1: String
    let acme2: Int
}

مزيد من المعلومات#

لمزيد من المعلومات حول الطرق المتاحة، راجع ملف README الخاص بـ APNSwift.