|
1 | | -## My Project |
| 1 | +## Amplify Swift Utilities for Notifications |
2 | 2 |
|
3 | | -TODO: Fill this README out! |
| 3 | +Amplify Swift Utilities for Notifications provides helpful functionality for working with push notifications on iOS and macOS. |
4 | 4 |
|
5 | | -Be sure to: |
| 5 | +Although it was developed for use with AWS Amplify, it can also be used independently. |
6 | 6 |
|
7 | | -* Change the title in this README |
8 | | -* Edit your repository description on GitHub |
9 | 7 |
|
10 | | -## Security |
| 8 | +[API Documentation](https://aws-amplify.github.io/amplify-swift-utils-notifications/docs/) |
| 9 | + |
| 10 | + |
| 11 | +## Features |
| 12 | + |
| 13 | +- Convenience methods to support requesting notification permissions and registering with APNs |
| 14 | +- Push Notification Service extension to support fetching and attaching remote media to notifications |
| 15 | + |
| 16 | + |
| 17 | +## Platform Support |
| 18 | +Amplify Swift Utilities for Notifications package supports iOS 13+ and macOS 10.15+. |
11 | 19 |
|
12 | | -See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. |
13 | 20 |
|
14 | 21 | ## License |
15 | 22 |
|
16 | | -This project is licensed under the Apache-2.0 License. |
| 23 | +This package is licensed under the Apache-2.0 License. |
| 24 | + |
| 25 | + |
| 26 | +## Installation |
| 27 | + |
| 28 | +This package requires Xcode 13.4 or higher to build. |
| 29 | + |
| 30 | + |
| 31 | +### Swift Package Manager |
| 32 | +1. Swift Package Manager is distributed with Xcode. To start adding this package to your iOS project, open your project in Xcode and select **File > Add Packages**. |
| 33 | +  |
| 34 | + |
| 35 | +2. Enter the package GitHub repo URL (https://github.com/aws-amplify/amplify-swift-utils-notifications) into the search bar. |
| 36 | + |
| 37 | +3. You'll see the repository rules for which version you want Swift Package Manager to install. Choose **Up to Next Major Version** and enter **1.0.0** as the minimum version for the Dependency Rule, then click **Add Package**. |
| 38 | +  |
| 39 | + |
| 40 | +4. Select `AmplifyUtilsNotifications`, then click Add Package. |
| 41 | + |
| 42 | +5. In your app code, explicitly import the plugin as needed. |
| 43 | + |
| 44 | + ```swift |
| 45 | + import SwiftUI |
| 46 | + import AmplifyUtilsNotifications |
| 47 | + |
| 48 | + @main |
| 49 | + struct HelloWorldApp: App { |
| 50 | + @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate |
| 51 | + var body: some Scene { |
| 52 | + WindowGroup { |
| 53 | + ContentView() |
| 54 | + } |
| 55 | + } |
| 56 | + } |
| 57 | + |
| 58 | + class AppDelegate: NSObject, UIApplicationDelegate { |
| 59 | + func applicationDidFinishLaunching(_ application: UIApplication) { |
| 60 | + Task { |
| 61 | + let isPushNotificationAllowed = await AmplifyUtilsNotifications.AUNotificationPermissions.allowed |
| 62 | + // ... |
| 63 | + } |
| 64 | + } |
| 65 | + } |
| 66 | + ``` |
| 67 | + |
| 68 | +### Cocoapods |
| 69 | +1. This package is also available through [CocoaPods](https://cocoapods.org/). If you have not installed CocoaPods, follow the instructions [here](https://guides.cocoapods.org/using/getting-started.html#getting-started). |
| 70 | + |
| 71 | +2. Add the package as a dependency to your Podfile. |
| 72 | + ```ruby |
| 73 | + platform :ios, '13.0' |
| 74 | + use_frameworks! |
| 75 | + |
| 76 | + target 'HelloWorldApp' do |
| 77 | + pod 'AmplifyUtilsNotifications', '~> 1.0.0' |
| 78 | + end |
| 79 | + ``` |
| 80 | + |
| 81 | +3. Then run the following command: |
| 82 | + ```sh |
| 83 | + pod install |
| 84 | + ``` |
| 85 | + |
| 86 | +4. Open up *.xcworkspace with Xcode, and you will be able to use the `AmplifyUtilsNotifications` package in your project. |
| 87 | + |
| 88 | +## Notification Service Extension for AWS Pinpoint |
| 89 | + |
| 90 | +This package includes a ready to use implementation(`AUNotificationService`) for handling remote notifications sent by AWS Pinpoint. It helps with decoding notification json data and retrieving the remote media url as an attachment. |
| 91 | + |
| 92 | +#### Push notification in AWS Pinpoint format |
| 93 | +1. Add a Service App Extension to Your Project. [Apple Doc](https://developer.apple.com/documentation/usernotifications/modifying_content_in_newly_delivered_notifications). |
| 94 | + |
| 95 | +  |
| 96 | + |
| 97 | +2. Update `info.plist` of the newly created Notification Service Extension. |
| 98 | + |
| 99 | + ```xml |
| 100 | + <dict> |
| 101 | + <key>NSExtension</key> |
| 102 | + <dict> |
| 103 | + <key>NSExtensionPointIdentifier</key> |
| 104 | + <string>com.apple.usernotifications.service</string> |
| 105 | + <key>NSExtensionPrincipalClass</key> |
| 106 | + <string>AmplifyUtilsNotifications.AUNotificationService</string> |
| 107 | + </dict> |
| 108 | + </dict> |
| 109 | + ``` |
| 110 | + |
| 111 | + > Note: |
| 112 | + > |
| 113 | + > We suggest you either keep the auto generated `NotificationService.swift` source file or add an empty swift file for your Notification Service Extension target. An empty source list will cause an error when you try to install the extension to a real device. |
| 114 | + |
| 115 | +### Push notification not in AWS Pinpoint format |
| 116 | + |
| 117 | +You can also subclass `AUNotificationService` to support a different notification payload format or add custom functionality. |
| 118 | + |
| 119 | +For example, we want to send the push notification with a field name `video_url`. |
| 120 | + |
| 121 | +1. Define a `MyPayload` struct that conforms to the `AUNotificationPayload` protocol. It defines the `remoteMediaURL`. |
| 122 | + |
| 123 | +2. Subclass `AUNotificationService` and change the `payloadSchema` property to `MyPayload` that was defined in the previous step. |
| 124 | + |
| 125 | + ```swift |
| 126 | + import AmplifyUtilsNotifications |
| 127 | + |
| 128 | + struct MyPayload: AUNotificationPayload { |
| 129 | + var remoteMediaURL: String? { |
| 130 | + video_url |
| 131 | + } |
| 132 | + |
| 133 | + let video_url: String |
| 134 | + } |
| 135 | + |
| 136 | + class NotificationService: AUNotificationService { |
| 137 | + |
| 138 | + override init() { |
| 139 | + super.init() |
| 140 | + self.payloadSchema = MyPayload.self |
| 141 | + } |
| 142 | + } |
| 143 | + ``` |
| 144 | + |
| 145 | +3. Update the `info.plist` by setting `NSExtensionPrincipalClass` to `$(PRODUCT_MODULE_NAME).NotificationService`. |
| 146 | + |
| 147 | +You can also override the `didReceive` function to modify the content as desired. For example, attach suffix `[MODIFIED]` to your notification title. |
| 148 | + |
| 149 | +```swift |
| 150 | +override func didReceive( |
| 151 | + _ request: UNNotificationRequest, |
| 152 | + withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void |
| 153 | +) { |
| 154 | + super.didReceive(request) { content in |
| 155 | + self.contentHandler = contentHandler |
| 156 | + let mutableContent = content.mutableCopy() as? UNMutableNotificationContent |
| 157 | + mutableContent?.title = content.title + "[MODIFIED]" |
| 158 | + if let mutableContent { |
| 159 | + contentHandler(mutableContent) |
| 160 | + } |
| 161 | + } |
| 162 | +} |
| 163 | +``` |
| 164 | + |
| 165 | + |
| 166 | + |
| 167 | + |
| 168 | +## Reporting Bugs/Feature Requests |
| 169 | + |
| 170 | +[](https://github.com/aws-amplify/amplify-swift-utils-notifications/issues?q=is%3Aissue+is%3Aopen+label%3Abug) |
| 171 | +[](https://github.com/aws-amplify/amplify-swift-utils-notifications/issues?q=is%3Aissue+label%3A%22question%22+is%3Aopen+) |
| 172 | +[](https://github.com/aws-amplify/amplify-swift-utils-notifications/issues?q=is%3Aissue+label%3A%22feature-request%22+is%3Aopen+) |
| 173 | +[](https://github.com/aws-amplify/amplify-swift-utils-notifications/issues?q=is%3Aissue+is%3Aclosed+) |
| 174 | + |
| 175 | +We welcome you to use the GitHub issue tracker to report bugs or suggest features. |
| 176 | + |
| 177 | +When filing an issue, please check [existing open](https://github.com/aws-amplify/amplify-swift-utils-notifications/issues), or [recently closed](https://github.com/aws-amplify/amplify-swift-utils-notifications/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20), issues to make sure somebody else hasn't already |
| 178 | +reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: |
17 | 179 |
|
| 180 | +* Expected behavior and observed behavior |
| 181 | +* A reproducible test case or series of steps |
| 182 | +* The version of our code being used |
| 183 | +* Any modifications you've made relevant to the bug |
| 184 | +* Anything custom about your environment or deployment |
0 commit comments