Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

CHNL-12941: Add badge count instructions to README #247

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

CHNL-12941: Add badge count instructions to README #247

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b8899bc
Add badge count to README
belleklaviyo Dec 20, 2024
f6d901f
copilot proof
belleklaviyo Jan 2, 2025
092b045
remove duplication
belleklaviyo Jan 2, 2025
e8682bb
fix typo, add release tag to sandbox
belleklaviyo Jan 2, 2025
626db28
verbiage
belleklaviyo Jan 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 54 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,12 @@
- [Receiving Push Notifications](#receiving-push-notifications)
- [Tracking Open Events](#tracking-open-events)
- [Deep Linking](#deep-linking)
- [Option 1: URL Schemes](#option-1-URL-schemes)
- [Option 1: URL Schemes](#option-1-url-schemes)
- [Option 2: Universal Links](#option-2-universal-links)
- [Rich Push](#rich-push)
- [Badge Count](#badge-count)
- [Autoclearing](#autoclearing)
- [Handling Other Badging Sources](#handling-other-badging-sources)
- [Additional Details](#additional-details)
- [Sandbox Support](#sandbox-support)
- [SDK Data Transfer](#sdk-data-transfer)
Expand All @@ -43,7 +46,7 @@ Once integrated, your marketing team will be able to better understand your app
## Installation

1. Enable push notification capabilities in your Xcode project. The section "Enable the push notification capability" in this [Apple developer guide](https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns#2980170) provides detailed instructions.
2. [Optional but recommended] If you intend to use [rich push notifications](#rich-push) add a [Notification service extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) to your xcode project. A notification service app extension ships as a separate bundle inside your iOS app. To add this extension to your app:
2. If you intend to use [rich push notifications](#rich-push) or [custom badge counts](#custom-badge-count) add a [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) to your Xcode project. A Notification Service Extension ships as a separate bundle inside your iOS app. To add this extension to your app:
- Select File > New > Target in Xcode.
- Select the Notification Service Extension target from the iOS > Application extension section.
- Click Next.
Expand All @@ -54,6 +57,15 @@ Once integrated, your marketing team will be able to better understand your app
If this exceeds your app's minimum supported iOS version, push notifications may not display attached media on older devices.
To avoid this, ensure the extension's minimum deployment target matches that of your app. ⚠️

Set up an App Group between your main app target and your Notification Service Extension.
- Select your main app target > Signing & Capabilities
- Select + Capability (make sure it is set to All not Debug or Release) > App Groups
- Create a new App Group based on the recommended naming scheme `group.com.[MainTargetBundleId].[descriptor]`
- In your app's `Info.plist`, add a new entry for `klaviyo_app_group` as a String with the App Group name
- Select your Notification Service Extension target > Signing & Capabilities
- Add an App Group with the same name as the main target's App Group
- In your Notification Service Extension's `Info.plist`, add a new entry for `klaviyo_app_group` as a String with the App Group name

3. Based on which dependency manager you use, follow the instructions below to install the Klaviyo's dependencies.

<details>
Expand Down Expand Up @@ -91,7 +103,7 @@ Once integrated, your marketing team will be able to better understand your app
</details>

4. Finally, in the `NotificationService.swift` file add the code for the two required delegates from [this](Examples/KlaviyoSwiftExamples/SPMExample/NotificationServiceExtension/NotificationService.swift) file.
This sample covers calling into Klaviyo so that we can download and attach the media to the push notification.
This sample covers calling into Klaviyo so that we can download and attach the media to the push notification as well as handle custom badge counts.

## Initialization
The SDK must be initialized with the short alphanumeric [public API key](https://help.klaviyo.com/hc/en-us/articles/115005062267#difference-between-public-and-private-api-keys1)
Expand Down Expand Up @@ -252,24 +264,24 @@ func application(_ application: UIApplication, didFinishLaunchingWithOptions lau
UIApplication.shared.registerForRemoteNotifications()

let center = UNUserNotificationCenter.current()
center.delegate = self as? UNUserNotificationCenterDelegate // the type casting can be removed once the delegate has been implemented
let options: UNAuthorizationOptions = [.alert, .sound, .badge]
// use the below options if you are interested in using provisional push notifications. Note that using this will not
// show the push notifications prompt to the user.
// let options: UNAuthorizationOptions = [.alert, .sound, .badge, .provisional]
center.requestAuthorization(options: options) { granted, error in
if let error = error {
// Handle the error here.
print("error = ", error)
}

// Irrespective of the authorization status call `registerForRemoteNotifications` here so that
// the `didRegisterForRemoteNotificationsWithDeviceToken` delegate is called. Doing this
// will make sure that Klaviyo always has the latest push authorization status.
center.delegate = self as? UNUserNotificationCenterDelegate // the type casting can be removed once the delegate has been implemented
let options: UNAuthorizationOptions = [.alert, .sound, .badge]
// use the below options if you are interested in using provisional push notifications. Note that using this will not
// show the push notifications prompt to the user.
// let options: UNAuthorizationOptions = [.alert, .sound, .badge, .provisional]
center.requestAuthorization(options: options) { granted, error in
if let error = error {
// Handle the error here.
print("error = ", error)
}

// Irrespective of the authorization status call `registerForRemoteNotifications` here so that
// the `didRegisterForRemoteNotificationsWithDeviceToken` delegate is called. Doing this
// will make sure that Klaviyo always has the latest push authorization status.
DispatchQueue.main.async {
UIApplication.shared.registerForRemoteNotifications()
}
}
}

return true
}
Expand Down Expand Up @@ -313,44 +325,6 @@ extension AppDelegate: UNUserNotificationCenterDelegate {
}
}
```
When tracking opened push notification, you can also decrement the badge count on the app icon by adding the following code to the `userNotificationCenter:didReceive:withCompletionHandler` method:

```swift
func userNotificationCenter(
_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler completionHandler: @escaping () -> Void) {
// decrement the badge count on the app icon
if #available(iOS 16.0, *) {
UNUserNotificationCenter.current().setBadgeCount(UIApplication.shared.applicationIconBadgeNumber - 1)
} else {
UIApplication.shared.applicationIconBadgeNumber -= 1
}

// If this notification is Klaviyo's notification we'll handle it
// else pass it on to the next push notification service to which it may belong
let handled = KlaviyoSDK().handle(notificationResponse: response, withCompletionHandler: completionHandler)
if !handled {
completionHandler()
}
}
```

Additionally, if you just want to reset the badge count to zero when the app is opened(note that this could be from
the user just opening the app independent of the push message), you can add the following code to
the `applicationDidBecomeActive` method in the app delegate:

```swift

func applicationDidBecomeActive(_ application: UIApplication) {
// reset the badge count on the app icon
if #available(iOS 16.0, *) {
UNUserNotificationCenter.current().setBadgeCount(0)
} else {
UIApplication.shared.applicationIconBadgeNumber = 0
}
}
```

Once your first push notifications are sent and opened, you should start to see _Opened Push_ metrics within your Klaviyo dashboard.

Expand Down Expand Up @@ -387,16 +361,16 @@ In order to edit the Info.plist directly, just fill in your app specific details
```xml
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLName</key>
<string>{your_unique_identifier}</string>
<key>CFBundleURLSchemes</key>
<array>
<string>{your_URL_scheme}</string>
</array>
</dict>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLName</key>
<string>{your_unique_identifier}</string>
<key>CFBundleURLSchemes</key>
<array>
<string>{your_URL_scheme}</string>
</array>
</dict>
</array>
```

Expand All @@ -409,7 +383,7 @@ This needs to be done in the Info.plist directly:
```xml
<key>LSApplicationQueriesSchemes</key>
<array>
<string>{your custom URL scheme}</string>
<string>{your custom URL scheme}</string>
</array>
```

Expand Down Expand Up @@ -519,6 +493,19 @@ project setup with the code from the `KlaviyoSwiftExtension`. Below are instruct

Once you have these three things, you can then use the push notifications tester and send a local push notification to make sure that everything was set up correctly.

#### Badge Count
> ℹ️ Incrementing are supported in SDK version [4.1.0](https://github.com/klaviyo/klaviyo-swift-sdk/releases/tag/4.1.0) and higher
belleklaviyo marked this conversation as resolved.
Show resolved Hide resolved

Klaviyo supports setting or incrementing the badge count when you send a push notification. For this functionality to work, you must set up the Notification Service Extension and an App Group as outlined under the [Installation](#installation) section.

##### Autoclearing

By default, the Klaviyo SDK automatically clears the badge count on app open. If you want to disable this behavior, add a new entry for `klaviyo_badge_autoclearing` as a Boolean set to `NO` in your app's `Info.plist`. You can re-enable automatically clearing badges by setting this value to `YES`.

##### Handling Other Badging Sources

Klaviyo SDK will automatically handle the badge count associated with Klaviyo pushes. If you need to manually update the badge count to account for other notification sources, use the `KlaviyoSDK().setBadgeCount(:)` method, which will update the badge count and keep it in sync with the Klaviyo SDK. This method should be used instead of (rather than in addition to) setting the badge count using `UNUserNotificationCenter` and/or `UIApplication` methods.

## Additional Details

### Sandbox Support
Expand Down
Loading