APNSwift
APNSwift copied to clipboard
📱HTTP/2 Apple Push Notification Service built with swift - send push notifications to iOS, iPadOS, tvOS, macOS, watchOS, visionOS, and Safari!
APNSwift
A non-blocking Swift module for sending remote Apple Push Notification requests to APNS built on http/2, SwiftNIO for use on server side swift platforms.
Installation
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: "4.0.0"),
]
If youd like to give our bleeding edge release a try, which is what the Readme is expecting use 5.0.0-alpha.N
. If you need the old Readme, see here
dependencies: [
.package(url: "https://github.com/swift-server-community/APNSwift.git", from: "5.0.0-alpha.4"),
]
Getting Started
struct BasicNotification: APNSNotification {
let aps: APNSPayload
}
var logger = Logger(label: "com.apnswift")
logger.logLevel = .debug
/// Create your `APNSConfiguration.Authentication`
let authenticationConfig: APNSConfiguration.Authentication = .init(
privateKey: try .loadFrom(filePath: "/Users/kylebrowning/Documents/AuthKey_9UC9ZLQ8YW.p8"),
teamIdentifier: "ABBM6U9RM5",
keyIdentifier: "9UC9ZLQ8YW"
)
/// If you need to use a secrets manager instead of reading from the disk, use
/// `loadfrom(string:)`
let apnsConfig = try APNSConfiguration(
authenticationConfig: authenticationConfig,
topic: "com.grasscove.Fern",
environment: .sandbox,
logger: logger
)
let apns = APNSClient(configuration: apnsConfig)
let aps = APNSPayload(alert: .init(title: "Hey There", subtitle: "Subtitle", body: "Body"), hasContentAvailable: true)
let deviceToken = "myDeviceToken"
try await apns.send(notification, pushType: .alert, to: deviceToken)
try await apns.shutdown()
exit(0)
APNSConfiguration
APNSConfiguration
is a structure that provides the system with common configuration.
let apnsConfig = try APNSConfiguration(
authenticationConfig: authenticationConfig,
topic: "com.grasscove.Fern",
environment: .sandbox,
logger: logger
)
APNSConfiguration.Authentication
APNSConfiguration.Authentication
is a struct that provides authentication keys and metadata to the signer.
let authenticationConfig: APNSConfiguration.Authentication = .init(
privateKey: try .loadFrom(filePath: "/Users/kylebrowning/Documents/AuthKey_9UC9ZLQ8YW.p8"),
teamIdentifier: "ABBM6U9RM5",
keyIdentifier: "9UC9ZLQ8YW"
)
APNSClient
APNSClient
provides functions to send a notification to a specific device token string.
Example APNSClient
let apns = APNSClient(configuration: apnsConfig)
APNSAlert
APNSAlert
is the actual meta data of the push notification alert someone wishes to send. More details on the specifics of each property are provided here. They follow a 1-1 naming scheme listed in Apple's documentation
Example APNSAlert
let alert = APNSAlert(title: "Hey There", subtitle: "Full moon sighting", body: "There was a full moon last night did you see it")
APNSPayload
APNSPayload
is the meta data of the push notification. Things like the alert, badge count. More details on the specifics of each property are provided here. They follow a 1-1 naming scheme listed in Apple's documentation
Example APNSPayload
let alert = ...
let aps = APNSPayload(alert: alert, badge: 1, sound: .normal("cow.wav"))
Custom Notification Data
Apple provides engineers with the ability to add custom payload data to each notification. In order to facilitate this we have the APNSNotification
.
Example
struct AcmeNotification: APNSwiftNotification {
let acme2: [String]
let aps: APNSPayload
init(acme2: [String], aps: APNSPayload) {
self.acme2 = acme2
self.aps = aps
}
}
let apns: APNSClient: = ...
let aps: APNSPayload = ...
let notification = AcmeNotification(acme2: ["bang", "whiz"], aps: aps)
let res = try apns.send(notification, to: "de1d666223de85db0186f654852cc960551125ee841ca044fdf5ef6a4756a77e")
Need a completely custom arbtirary payload and dont like being typecast?
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
let notificationJsonPayload = ...
let data: Data = try! encoder.encode(notificationJsonPayload)
try apns.send(raw: data, pushType: .alert, to: "<DEVICETOKEN>")
Original pitch and discussion on API
- Pitch discussion: Swift Server Forums
- Proposal: SSWG-0006