Swiftpack.co - Package - kylebrowning/APNSwift

sswg:incubating|94x20 License Build Swift

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/kylebrowning/APNSwift.git", .upToNextMinor(from: "1.3.0"))
]

Getting Started

struct BasicNotification: APNSwiftNotification {
    let aps: APNSwiftPayload
}
let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
var logger = Logger(label: "com.apnswift")
logger.logLevel = .debug
let apnsConfig = try APNSwiftConfiguration(
    authenticationMethod: .jwt(
        key: .private(filePath: "/Users/kylebrowning/Desktop/AuthKey_9UC9ZLQ8YW.p8"),
        keyIdentifier: "9UC9ZLQ8YW",
        teamIdentifier: "ABBM6U9RM5"
    ),
    topic: "com.grasscove.Fern",
    environment: .sandbox,
    logger: logger
)

let apns = try APNSwiftConnection.connect(configuration: apnsConfig, on: group.next()).wait()
let aps = APNSwiftPayload(alert: .init(title: "Hey There", subtitle: "Subtitle", body: "Body"), hasContentAvailable: true)
try apns.send(BasicNotification(aps: aps), pushType: .alert, to: "98AAD4A2398DDC58595F02FA307DF9A15C18B6111D1B806949549085A8E6A55D").wait()
try apns.close().wait()
try group.syncShutdownGracefully()
exit(0)

APNSwiftConfiguration

APNSwiftConfiguration is a structure that provides the system with common configuration.

let apnsConfig = try APNSwiftConfiguration(
    authenticationMethod: .jwt(
        key: .private(filePath: "/Users/kylebrowning/Desktop/AuthKey_9UC9ZLQ8YW.p8"),
        keyIdentifier: "9UC9ZLQ8YW",
        teamIdentifier: "ABBM6U9RM5"
    ),
    topic: "com.grasscove.Fern",
    environment: .sandbox,
    logger: logger
)

Example APNSwiftConfiguration

let signer = ...
let apnsConfig = try APNSwiftConfiguration(keyIdentifier: "9UC9ZLQ8YW",
                                   teamIdentifier: "ABBM6U9RM5",
                                   signer: signer),
                                   topic: "com.grasscove.Fern",
                                   environment: .sandbox)

APNSwiftConnection

APNSwiftConnection is a class with methods thats provides a wrapper to NIO's ClientBootstrap. The swift-nio-http2 dependency is utilized here. It also provides a function to send a notification to a specific device token string.

Example APNSwiftConnection

let apnsConfig = ...
let apns = try APNSwiftConnection.connect(configuration: apnsConfig, on: group.next()).wait()

APNSwiftAlert

APNSwiftAlert 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 APNSwiftAlert

let alert = APNSwiftAlert(title: "Hey There", subtitle: "Full moon sighting", body: "There was a full moon last night did you see it")

APNSwiftPayload

APNSwiftPayload 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 APNSwiftPayload

let alert = ...
let aps = APNSwiftPayload(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 APNSwiftNotification.

Example

struct AcmeNotification: APNSwiftNotification {
    let acme2: [String]
    let aps: APNSwiftPayload

    init(acme2: [String], aps: APNSwiftPayload) {
        self.acme2 = acme2
        self.aps = aps
    }
}

let apns: APNSwiftConnection: = ...
let aps: APNSwiftPayload = ...
let notification = AcmeNotification(acme2: ["bang", "whiz"], aps: aps)
let res = try apns.send(notification, to: "de1d666223de85db0186f654852cc960551125ee841ca044fdf5ef6a4756a77e").wait()

Using PEM instead of P8

Note: this is blocking


var apnsConfig = try APNSwiftConfiguration(
    authenticationMethod: .tls(
        privateKeyPath: "/Users/kylebrowning/Projects/swift/Fern/development_com.grasscove.Fern.pkey",
        pemPath: "/Users/kylebrowning/Projects/swift/Fern/development_com.grasscove.Fern.pem"
    ),
    topic: "com.grasscove.Fern",
    environment: .sandbox
)
let apns = try APNSwiftConnection.connect(configuration: apnsConfig, on: group.next()).wait()

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

Github

link
Stars: 348

Releases

2.1.0 - 2020-08-27 17:13:40

Avoids double namespacing of types used by APNSwiftPayload. Since they are already namespaced, they have been made top-level types.

let alert = APNSwiftAlert...
let soundDictionary = APNSSoundDictionary...
let soundType = APNSwiftSoundType...
let payload = APNSwiftPayload...

2.0.0 - 2020-08-26 16:59:49

This release contains the following

  • uses vapor/jwt-kit
  • removes deprecated methods
  • Adds support fort Swift 5.2 removes support for swift 5.1 and 5.0
  • Resolves a promise leak in #79
  • Allows PEM Password
  • Adds other push types, mdm, fileprovider, voip
  • updated APNSConnection API
  • New enum-style API for configuring auth

Release candidate 2 - 2020-08-06 13:56:06

Resolves a promise leak.

2.0.0 Release candidate 1 - 2020-03-26 13:15:15

  • uses vapor/jwt-kit
  • removes deprecated methods
  • Adds support got Swift 5.2 removes support for swift 5.1 and 5.0
  • Resolves a promise leak in #79
  • Allows PEM Password
  • Adds other push types, mdm, fileprovider, voip

Convenience release - 2019-12-09 19:53:21

This release adds a bunch of convenience functions to allow downstream packages quality of life. It resolves the following issues as well.

#74, #72

Homebrew: openssl@1.1 - 2019-12-07 00:02:40

Changes Homebrew (.brew) dependency to openssl@1.1 (https://github.com/kylebrowning/APNSwift/pull/73). This change is required as Homebrew has deprecated the openssl package name now that OpenSSL 1.0 is no longer available.

Quality of life release - 2019-12-05 16:20:19

Fixes a promise leak - 2019-11-26 18:09:34

This release fixes a promise leaking issue discovered in #62 and resolved in #63

Suport raw payload (semver safe) - 2019-10-04 14:14:20

The previous release violated server in that it added a public func but only incremented the patch.

This release does not violate semver

Supports raw payload to APNS - 2019-10-03 14:41:30

A small but fun update. If you'd like to send your own raw payload and not use much of the Typecasting that APNSwift offers, you now can. Checkout the bottom of the README for more information.

  • Fixes #50 (#51)

Swift 5.1 support + iOS 13 + bug fixes - 2019-09-25 02:05:07

Official 1.2.0 release

#49 - tooManyProviderTokens #48 - Correctly generate a signature #39 - Flaky Test #43 - Support apn-push-type #47 - Support PEM certificate #44 - Support Linux OpenSSL 5.1

Fixes an issue with valid JWT signing. - 2019-08-13 01:24:58

#37 Fix ES256 signing

Adds in support for token refreshes - 2019-07-27 15:44:57

  • thanks to #35 We now support token refresh.
  • Also includes unit tests.

APNSwift release 1.0.1 - 2019-07-23 17:29:17

This patch release addresses #31 a memory safety issue.

Official 1.0 Release of APNSwift - 2019-07-11 16:39:15

Official 1.0 release

  • Provides an API for handling connection to Apples HTTP2 APNS server
  • Provides proper error messages that APNS might respond with.
  • Uses custom/non dependency implementations of JSON Web Token specific to APNS (using [rfc7519])(https://tools.ietf.org/html/rfc7519)
  • Imports OpenSSL for SHA256 and ES256
  • Provides an interface for signing your Push Notifications
  • Signs your token request
  • Sends push notifications to a specific device.

Alpha 2, with APNSwift rename - 2019-07-06 16:54:59

Initial Alpha Release - 2019-06-10 17:17:06

This release includes all of the functionality in this proposal.