Making the most of Kumulos Push

Here at Kumulos, we are committed to helping you retain and engage your audience to drive real business results from your mobile app. Push Notifications remain the single most effective way to keep users engaged with an app and we continually invest in our award-winning Push Notifications feature, adding new enhancements so you can deliver the right message to the right user at the right time. Some of these enhancements may have been added after you first integrated Kumulos into your app. This guide describes what you need to do to ensure you can access all of the latest enhancements and make the most out of the Kumulos Push Notifications feature.

Update to latest APNS/FCM APIs

In the same way Apple and Google continually update the iOS and Android operating systems, they also update the push notification gateway APIs that vendors use to send notifications to devices. Unlike other push vendors, Kumulos is committed to always using the latest version of the Apple Push Notification Service (APNS) and Google Firebase Cloud Messaging (FCM) push notification gateway APIs. This ensures that the messages you send to your users are sent over the latest, most robust and secure APIs and avoids any potential problems whenever Apple or Google deprecate older APIs. It also means we have access to more detailed feedback from the APNS and FCM gateways should there be any authentication or other errors, which we will show in the Error Log.

If you integrated Kumulos into your app before March 2020, you may need to update to the latest APNS and FCM APIs. All you need to do is re-upload the certificates and keys we use to authenticate with the gateways and then contact support. We will then check everything is in order before switching you over. There are no SDK updates or other changes in the app required.

Upload APNS Certificate

To upload your APNS Certificate, expand 'Messaging' in the left menu and select 'Configuration'.

Click the cog icon next to the Apple logo and upload the P12 file containing your APNS certificate. If you want to generate a new APNS certificate (for example: if your current certificate is about to expire) please follow the instructions in this video. Ensure that the bundle id in your certificate matches that of your XCode project. Please note, we recommend using a combined Sandbox & Production certificate to avoid any problems switching between debug and release builds.

Upload Google Service Account JSON file

Click the cog icon next to the Android logo, enter your FCM Server Key and upload your Google Service Account private key JSON File. Please note that the Google Service Account JSON file is different from the Google Services JSON file you add to your app. Please see the instructions in this video to download the right file. Please also ensure that Firebase Cloud Messaging API is enabled for your Firebase project in the Google Developer Console.

Contact Support

Once you have re-uploaded your certificates and keys, pleae contact technical support by clicking on the down arrow next to your login, selecting Account Settings and then Support from the left-hand menu.

Enter your first and last names as well as a contact telephone number or Skype ID in case we need to speak to you in person. Explain that you wish to update your app to use the latest APNS/FCM APIs and click Contact. You will receive an email confirming that a ticket has been opened. We will check everything is in order, update your app to the latest APIs and let you know when this is complete.

---

Get Delivery Receipts

Push notifications are sent from Kumulos to the native gateway for each device (e.g. APNS for iOS devices and FCM for Android devices). While in the vast majority of cases, the gateway will then deliver the notification to the device in near real-time, there are numerous legitimate reasons why this might not happen. For example if a device is powered down, has no network coverage or mobile data is switched off. The gateway will continue to attempt delivery for 3 days, but ultimately delivery cannot be guaranteed in this time.

In addition, the gateways (APNS in particular) can be very slow to report uninstalls or unsubscribes. Apple, for example, have recently introduced a variable delay before reporting a device as having unsubscribed for privacy reasons. All of this can result in sent counts giving an inflated view of the reachable audience and therefore deflating view open-rates and campaign performance.

For this reason, Kumulos also reports the number of devices to which your push notification was actually delivered to. When the device receives a push notification, the Kumulos SDK in your app makes a network request to confirm receipt. Furthermore, this delivery receipt is first persisted locally before being sent to Kumulos ensuring that even if a device should lose network coverage once the push is received, the delivery receipt will be sent when network connection is restored, giving a more accurate view of your reachable audience, open-rates and campaign performance.

To see delivery receipts, you must update your app to include a recent version of our SDK e.g. Swift v8.4.0 and Android v7.0.0 or later. If you are using another SDK, please see the changelog for that SDK to see in which version support for delivery receipts was added. However, we would always recommend updating to the latest version of the SDK(s) you are using.

To see delivery receipts for iOS devices, you need to add a service extension - instructions for how to do this is described in the integration guide for each SDK:

• Swift
• Obj-C
• Cordova & Ionic & Capacitor
• React Native
• Xamarin
• Unity

---

Add Images to Push Notifications

Adding images to your push notifications can make them much more engaging and is an effective way to increase open-rates. With Kumulos, you can upload your own brand images or use images from the Unsplash stock image library.

To add images to your push notifications, you must update your app to include a recent version of our SDK. Please see the changelog for the SDK(s) you are using to see in which version support for images was added. However, we would always recommend updating to the latest version of the SDK(s) you are using.

If you have already updated your SDK and followed the instructions to add the service extension for iOS in order to see delivery receipts, then you do not need to do anything more - you can add images to your push notifications now.

To see images on iOS devices, you need to add a service extension - instructions for how to do this is described in the integration guide for each SDK:

• Swift
• Obj-C
• Cordova & Ionic & Capacitor
• React Native
• Xamarin
• Unity

---

Reach Users on Huawei Devices

The latest Huawei handsets such as the P40 family of phones do not use FCM for push notifications and instead use Huawei Cloud Messaging (HCM). If you want to message all of your Android users, including those using Huawei phones, then in addition to FCM you also need to configure HCM as described in this section. After completing the above FCM configuration, you also need to:

1. Set up an app on the Huawei Mobile Developer Console
2. Configure Push in the Kumulos Agency Console
3. Add Huawei Mobile Services dependencies, files, and plugins to your project
4. Add Huawei-specific manifest entries

All other push behavior & customization works identically to FCM.

To begin, configure a project on the Huawei Developer Console, and enable the Push feature by following the Push Kit developer guide step 1.

Note that your app needs a valid signing configuration for both debug and release builds. The SHA-256 fingerprint of your signing key is required to match the Huawei app configuration prior to continuing.

Once you have created the app, configure the HCM gateway in Kumulos. Expand 'Messaging' in the left menu and select 'Configuration' and click the cog next to the Huawei icon. You need to enter the App ID and App Secret from the Huawei Developer Console.

Once configured, now add the agconnect-services.json file (downloaded from the Huawei developer console) to your Android application directory.

Next, add the Huawei repository and plugin dependency to your root build.gradle:

buildscript {
    repositories {
        ...
        maven {
            url 'https://developer.huawei.com/repo/'
        }
    }
    dependencies {
        ...
        classpath 'com.huawei.agconnect:agcp:1.2.1.301'
    }
}

allprojects {
    repositories {
        ...
        maven {
            url 'http://developer.huawei.com/repo/'
        }
    }
}

Next, in your app-level build.gradle, add the HMS Push Kit dependency and apply the HMS plugin:

dependencies {
    ...
    implementation 'com.huawei.hms:push:6.1.0.300'
}

// Add to bottom of file
apply plugin: 'com.huawei.agconnect'

Finally, add the HMS push service to your AndroidManifest.xml:

<!-- Kumulos HMS Messaging Service -->
<service
    android:name="com.kumulos.android.HmsMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.huawei.push.action.MESSAGING_EVENT" />
    </intent-filter>
</service>

Push registration should be performed as with FCM.

Huawei Troubleshooting

• Whilst the Kumulos SDK minSdk is 16, when you use the HMS Push Kit, the minSdk will need to be 17 for your app
• Ensure the app signing key fingerprint matches in the Huawei developer console
• Ensure the app package matches the configuration in the Huawei developer console
• Ensure the Push Kit service is enabled for your app in AppGallery Connect > App > Develop > Grow > Push Kit. You must enable the service and choose a data storage location.