Skip to content

Commit 6b604c1

Browse files
committed
Update Provider documentation
1 parent ab6ece8 commit 6b604c1

File tree

1 file changed

+29
-6
lines changed

1 file changed

+29
-6
lines changed

doc/provider.markdown

Lines changed: 29 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,36 @@ The `Provider` can continue to be used for sending notifications and the counter
6363

6464
## Class: apn.Provider
6565

66+
`apn.Provider` provides a number of methods for sending notifications, broadcasting notifications, and managing channels. Calling any of the methods will return a `Promise` for each notification and is discussed more in [Results from APN Provider Methods](#results-from-apnprovider-methods).
67+
6668
### connection.send(notification, recipients)
6769

68-
This is main interface for sending notifications. Create a `Notification` object and pass it in, along with a single recipient or an array of them and node-apn will take care of the rest, delivering a copy of the notification to each recipient.
70+
This is the main interface for sending notifications. Create a `Notification` object and pass it in, along with a single recipient or an array of them and node-apn will take care of the rest, delivering a copy of the notification to each recipient.
6971

7072
> A "recipient" is a `String` containing the hex-encoded device token.
7173
72-
Calling `send` will return a `Promise`. The Promise will resolve after each notification (per token) has reached a final state. Each notification can end in one of three possible states:
74+
Calling `send` will return a `Promise`. The Promise will resolve after each notification (per token) has reached a final state.
75+
76+
### connection.manageChannels(notification, bundleId, action)
77+
This is the interface for managing broadcast channels. Create a single `Notification` object or an aray of them and pass the notification(s) in, along with a bundleId, and an action (`create`, `read`, `readAll`, `delete`) and node-apn will take care of the rest, asking the APNs to perform the action using the criteria specified in each notification.
78+
79+
> A "bundleId" is a `String` containing bundle identifier for the application.
80+
81+
> An "action" is a `String` containing: `create`, `read`, `readAll`, or `delete` and represents what action to perform with a channel (See more in [Apple Documentation](https://developer.apple.com/documentation/usernotifications/sending-channel-management-requests-to-apns)).
82+
83+
Calling `manageChannels` will return a `Promise`. The Promise will resolve after each notification has reached a final state.
84+
85+
### connection.broadcast(notification, bundleId)
86+
87+
This is the interface for broadcasting Live Activity notifications. Create a single `Notification` object or an aray of them and pass the notification(s) in, along with a bundleId and node-apn will take care of the rest, asking the APNs to broadcast using the criteria specified in each notification.
88+
89+
> A "bundleId" is a `String` containing bundle identifier for the application.
90+
91+
Calling `broadcast` will return a `Promise`. The Promise will resolve after each notification has reached a final state.
92+
93+
### Results from apn.Provider methods
94+
95+
Each notification can end in one of three possible states:
7396

7497
- `sent` - the notification was accepted by Apple for delivery to the given recipient
7598
- `failed` (rejected) - the notification was rejected by Apple. A rejection has an associated `status` and `reason` which is included.
@@ -79,15 +102,15 @@ When the returned `Promise` resolves, its value will be an Object containing two
79102

80103
#### sent
81104

82-
An array of device tokens to which the notification was successfully sent and accepted by Apple.
105+
An array of device tokens or bundle identifiers to which the notification was successfully sent and accepted by Apple.
83106

84107
Being `sent` does **not** guarantee the notification will be _delivered_, other unpredictable factors - including whether the device is reachable - can ultimately prevent delivery.
85108

86109
#### failed
87110

88-
An array of objects for each failed token. Each object will contain the device token which failed and details of the failure which will differ between rejected and errored notifications.
111+
An array of objects for each failed token or bundle identifier. Each object will contain the device token or bundle identifier which failed and details of the failure which will differ between rejected and errored notifications.
89112

90-
For **rejected** notifications the object will take the following form
113+
For **rejected** notifications using `send()`, the object will take the following form
91114

92115
```javascript
93116
{
@@ -101,7 +124,7 @@ For **rejected** notifications the object will take the following form
101124

102125
More details about the response and associated status codes can be found in the [HTTP/2 Response from APN documentation][http2-response].
103126

104-
If a failed notification was instead caused by an **error** then it will have an `error` property instead of `response` and `status`:
127+
If a failed notification using `send()` was instead caused by an **error** then it will have an `error` property instead of `response` and `status`:
105128

106129
```javascript
107130
{

0 commit comments

Comments
 (0)