A non-blocking Swift module for sending remote Apple Push Notification requests to APNS built on AsyncHttpClient.

• Installation
• Foundations
• Getting Started
• Sending a simple notification
• Sending Live Activity Update
• Authentication
• Logging
  • Background Activity Logger
  • Notification Send Logger
• Using the non semantic safe APIs
• Server Example
• iOS Examples
• Original pitch and discussion on API

To install APNSwift, just add the package as a dependency in your Package.swift.

dependencies: [
    .package(url: "https://github.com/swift-server-community/APNSwift.git", from: "5.0.0"),
]

APNSwift is built with a layered approach. It exposes three tiers of API's.

1. A raw API that takes basic types such as String's
2. A slightly more semantically safe API, which takes types, like APNSPriority, APNSPushType, APNSNotificationExpiration, etc.
3. The safest API which takes fully semantic types such as APNSAlertNotification

We recommened using number 3, the semantically safest API to ensure your push notification is delivered correctly. This README assumes that you are using number 3. However if you need more granular approach, or something doesn't exist in this library, please use 2 or 1. (Also please open an issue if we missed something so we can get a semantically correct version!)

APNSwift aims to provide sementically correct structures to sending push notifications. You first need to setup a APNSClient. To do that youll need to know your authentication method

let client = APNSClient(
    configuration: .init(
        authenticationMethod: .jwt(
            privateKey: try .init(pemRepresentation: privateKey),
            keyIdentifier: keyIdentifier,
            teamIdentifier: teamIdentifier
        ),
        environment: .sandbox
    ),
    eventLoopGroupProvider: .createNew,
    responseDecoder: JSONDecoder(),
    requestEncoder: JSONEncoder(),
    byteBufferAllocator: .init(),
    backgroundActivityLogger: logger
)
defer {
    client.shutdown { _ in
        logger.error("Failed to shutdown APNSClient")
    }
}

All notifications require a payload, but that payload can be empty. Payload just needs to conform to Encodable

struct Payload: Codable {}

try await client.sendAlertNotification(
    .init(
        alert: .init(
            title: .raw("Simple Alert"),
            subtitle: .raw("Subtitle"),
            body: .raw("Body"),
            launchImage: nil
        ),
        expiration: .immediately,
        priority: .immediately,
        topic: "com.app.bundle",
        payload: Payload()
    ),
    deviceToken: "device-token",
    deadline: .nanoseconds(Int64.max),
    logger: myLogger
)

It requires sending ContentState matching with the live activity configuration to successfully update activity state. ContentState needs to conform to Encodable

        try await client.sendLiveActivityNotification(
            .init(
                  expiration: .immediately,
                  priority: .immediately,
                  appID: "com.app.bundle",
                  contentState: ContentState,
                  event: .update,
                  timestamp: Int(Date().timeIntervalSince1970)
            ),
            activityPushToken: activityPushToken,
            deadline: .distantFuture
        )

        try await client.sendLiveActivityNotification(
            .init(
                  expiration: .immediately,
                  priority: .immediately,
                  appID: "com.app.bundle",
                  contentState: ContentState,
                  event: .end,
                  timestamp: Int(Date().timeIntervalSince1970),
                  dismissalDate: .dismissImmediately // Optional to alter default behaviour
            ),
            activityPushToken: activityPushToken,
            deadline: .distantFuture
        )

APNSwift provides two authentication methods. jwt, and TLS.

jwt is preferred and recommend by Apple These can be configured when created your APNSClientConfiguration

Notes: jwt requires an encrypted version of your .p8 file from Apple which comes in a pem format. If you're having trouble with your key being invalid please confirm it is a PEM file

 openssl pkcs8 -nocrypt -in /path/to/my/key.p8 -out ~/Downloads/key.pem

By default APNSwift has a no-op logger which will not log anything. However if you pass a logger in, you will see logs.

There are currently two kinds of loggers.

This logger can be passed into the APNSClient and will log background things like connection pooling, auth token refreshes, etc.

This logger can be passed into any of the send: methods and will log everything related to a single send request.

APNSwift provides the ability to send raw payloads. You can use Data, ByteBuffer, DispatchData, Array Though this is to be used with caution. APNSwift cannot gurantee delivery if you do not have the correct payload. For more information see: Creating APN Payload

/// Extremely Raw,
try await client.send(
    payload: payload, 
    deviceToken: token, 
    pushType: "alert", deadline: .distantFuture
)

/// or a little safer but still raw
try await client.send(
    payload: payload, 
    deviceToken: token, 
    pushType: .alert, 
    expiration: .immediatly, 
    priority: .immediatly, 
    deadline: .distantFuture
)

Take a look at Program.swift

For an iOS example, open the example project within this repo.

Once inside configure your App Bundle ID and assign your development team. Build and run the ExampleApp to iOS Simulator, grab your device token, and plug it in to server example above. Background the app and run Program.swift

• Pitch discussion: Swift Server Forums
• Proposal: SSWG-0006
• 5.0 breaking changings: [Swift Server Forums](Blog post here on breaking changing)