Skip to content

Commit f09767a

Browse files
kylebrowningkylebrowning
authored
Add's docc document (#160)
Adds documentation
1 parent 2418889 commit f09767a

File tree

1 file changed

+138
-0
lines changed

1 file changed

+138
-0
lines changed

‎Sources/APNSwift/APNSwift.docc/APNSwift.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# ``APNSwift``
2+
A non-blocking Swift package for sending remote Apple Push Notification requests to Apple's APNS.
3+
4+
## Installation
5+
6+
To install `APNSwift`, just add the package as a dependency in your [**Package.swift**](https://github.com/apple/swift-package-manager/blob/master/Documentation/PackageDescriptionV4.md#dependencies).
7+
8+
```swift
9+
dependencies: [
10+
.package(url: "https://github.com/swift-server-community/APNSwift.git", from: "4.0.0"),
11+
]
12+
```
13+
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](https://github.com/swift-server-community/APNSwift/tree/4.0.0)
14+
15+
```swift
16+
dependencies: [
17+
.package(url: "https://github.com/swift-server-community/APNSwift.git", from: "5.0.0-alpha.5"),
18+
]
19+
```
20+
21+
## Foundations
22+
`APNSwift` is built with a layered approach. It exposes three tiers of API's.
23+
1. A [raw API](https://github.com/swift-server-community/APNSwift/blob/d60241fe2b6eb193331567a871697d3f4bdf70fb/Sources/APNSwift/APNSClient.swift#L254) that takes basic types such as `String`'s
24+
2. A slightly more [semantically safe API](https://github.com/swift-server-community/APNSwift/blob/d60241fe2b6eb193331567a871697d3f4bdf70fb/Sources/APNSwift/APNSClient.swift#L183), which takes types, like [`APNSPriority`](https://github.com/swift-server-community/APNSwift/blob/main/Sources/APNSwift/APNSPriority.swift), [`APNSPushType`](https://github.com/swift-server-community/APNSwift/blob/main/Sources/APNSwift/APNSPushType.swift), [`APNSNotificationExpiration`](https://github.com/swift-server-community/APNSwift/blob/main/Sources/APNSwift/APNSNotificationExpiration.swift), etc.
25+
3. The [safest API](https://github.com/swift-server-community/APNSwift/blob/d60241fe2b6eb193331567a871697d3f4bdf70fb/Sources/APNSwift/Alert/APNSClient%2BAlert.swift#L32) which takes fully semantic types such as [`APNSAlertNotification`](https://github.com/swift-server-community/APNSwift/blob/d60241fe2b6eb193331567a871697d3f4bdf70fb/Sources/APNSwift/Alert/APNSAlertNotification.swift#L177)
26+
27+
**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!)
28+
29+
## Getting Started
30+
APNSwift aims to provide sementically correct structures to sending push notifications. You first need to setup a [`APNSClient`](https://github.com/swift-server-community/APNSwift/blob/main/Sources/APNSwift/APNSClient.swift). To do that youll need to know your authentication method
31+
32+
```swift
33+
let client = APNSClient(
34+
configuration: .init(
35+
authenticationMethod: .jwt(
36+
privateKey: try .init(pemRepresentation: privateKey),
37+
keyIdentifier: keyIdentifier,
38+
teamIdentifier: teamIdentifier
39+
),
40+
environment: .sandbox
41+
),
42+
eventLoopGroupProvider: .createNew,
43+
responseDecoder: JSONDecoder(),
44+
requestEncoder: JSONEncoder(),
45+
byteBufferAllocator: .init(),
46+
backgroundActivityLogger: logger
47+
)
48+
defer {
49+
client.shutdown { _ in
50+
logger.error("Failed to shutdown APNSClient")
51+
}
52+
}
53+
```
54+
55+
## Sending a simple notification
56+
All notifications require a payload, but that payload can be empty. Payload just needs to conform to `Encodable`
57+
58+
```swift
59+
struct Payload: Codable {}
60+
61+
try await client.sendAlertNotification(
62+
.init(
63+
alert: .init(
64+
title: .raw("Simple Alert"),
65+
subtitle: .raw("Subtitle"),
66+
body: .raw("Body"),
67+
launchImage: nil
68+
),
69+
expiration: .immediately,
70+
priority: .immediately,
71+
topic: "com.app.bundle",
72+
payload: Payload()
73+
),
74+
deviceToken: "device-token",
75+
deadline: .distantFuture,
76+
logger: myLogger
77+
)
78+
```
79+
80+
## Authentication
81+
`APNSwift` provides two authentication methods. `jwt`, and `TLS`.
82+
83+
**`jwt` is preferred and recommend by Apple**
84+
These can be configured when created your `APNSClientConfiguration`
85+
86+
*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*
87+
```
88+
openssl pkcs8 -nocrypt -in /path/to/my/key.p8 -out ~/Downloads/key.pem
89+
```
90+
91+
## Logging
92+
By default APNSwift has a no-op logger which will not log anything. However if you pass a logger in, you will see logs.
93+
94+
There are currently two kinds of loggers.
95+
#### **Background Activity Logger**
96+
This logger can be passed into the `APNSClient` and will log background things like connection pooling, auth token refreshes, etc.
97+
98+
#### **Notification Send Logger**
99+
This logger can be passed into any of the `send:` methods and will log everything related to a single send request.
100+
101+
## Using the non semantic safe APIs
102+
103+
APNSwift provides the ability to send raw payloads. You can use `Data`, `ByteBuffer`, `DispatchData`, `Array`
104+
Though this is to be used with caution. APNSwift cannot gurantee delivery if you do not have the correct payload.
105+
For more information see: [Creating APN Payload](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html)
106+
107+
```swift
108+
/// Extremely Raw,
109+
try await client.send(
110+
payload: payload,
111+
deviceToken: token,
112+
pushType: "alert", deadline: .distantFuture
113+
)
114+
115+
/// or a little safer but still raw
116+
try await client.send(
117+
payload: payload,
118+
deviceToken: token,
119+
pushType: .alert,
120+
expiration: .immediatly,
121+
priority: .immediatly,
122+
deadline: .distantFuture
123+
)
124+
```
125+
126+
## Server Example
127+
Take a look at [Program.swift](https://github.com/swift-server-community/APNSwift/blob/main/Sources/APNSwiftExample/Program.swift)
128+
129+
## iOS Examples
130+
131+
For an iOS example, open the example project within this repo.
132+
133+
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
134+
135+
## Original pitch and discussion on API
136+
137+
* Pitch discussion: [Swift Server Forums](https://forums.swift.org/t/apple-push-notification-service-implementation-pitch/20193)
138+
* Proposal: [SSWG-0006](https://forums.swift.org/t/feedback-nioapns-nio-based-apple-push-notification-service/24393)

0 commit comments

Comments
 (0)