Tracking notification interactions

After completing the setup process you will be able to:

Automatically track interactions on your mobile notifications.
Define and analyze notification interaction events in Heap.

Before you begin

In order to collection notification interaction events with Heap, you must first have the Heap Core SDK installed for your platform. The minimum version of Heap Core that supports notification events is 0.7.0.

Installing the Notification Autocapture SDK

Once you have Heap Core installed and validated as working in your application, it's time to install the notification autocapture SDK. Notification autocapture is offered as a separate SDK from our Android View and UIKit autocapture SDKs for those customers that currently enjoy manual tracking, but would like to supplement that manual tracking with data about their notification events.

Android

On Android, the notification autocapture SDK can be added via Gradle from Maven Central, just like our other SDKs. If you're using an existing autocapture SDK, the notification SDK version will be the same. If you're not already using an autocapture SDK, the notification SDK version starts at 0.7.0.

dependencies {
  implementation 'io.heap.autocapture:heap-autocapture-notification:0.7.0'
}

dependencies {
  implementation("io.heap.autocapture:heap-autocapture-notification:0.7.0")
}

Additionally, you'll need to add the Heap Gradle Plugin using version 0.4.0 or higher.

plugins {
  id 'io.heap.gradle' version '0.4.+'
}

plugins {
  id("io.heap.gradle") version "0.4.+"
}

iOS

Swift Package Manager

In Xcode, open the package manager however you are accustomed to. The most direct path is navigating to File → Add Packages… in the menu.
Paste https://github.com/heap/heap-notification-autocapture-sdk.git into the Search or Enter Package URL text field at the top right corner of the dialog.
Select a Dependency Rule. We recommend Up to Next Major Version.
Click Add Package.
In the next dialog, check the checkbox next to HeapNotificationAutocapture and confirm that it will be added to your app target.
Click Add Package.
Before continuing, build your app target to help Swift resolve the modules.

CocoaPods

Add pod 'HeapNotificationAutocapture', '~> 0.7' to your app target in your Podfile.
1. pod 'HeapNotificationAutocapture_static', '~> 0.7' if installing for React Native.
Run pod install within your project directory.
Before continuing, build your app target to help Swift resolve the modules.

Initializing the Notification Autocapture SDK

The notification autocapture SDK can be initialized with a single API call that takes in two options. The options allow you to specify whether or not to capture the title and/or body text of the notification where an interaction was performed.

NotificationAutocaptureSDK.register(
  captureTitleText = true,
  captureBodyText = true
)

Heap.NotificationAutocaptureSource.register(
  captureTitle: true,
  captureBody: true
)

If your app is native Android or native iOS, that's it! Once registered, Heap will begin collecting interaction events on notifications.

Initialization for React Native and Flutter

In addition to the above steps for each of the native platforms, there's one additional step needed to ensure all events are properly captured in React Native and Flutter applications.

All notification interactions are captured at the native layer by code that is likely to execute before your application executes a call to startRecording() to begin tracking events. Because of this, to ensure you're tracking all notification interactions, you must add an additional API call to your application's entry point in native code. On Android, this will be your Application class. On iOS, this will be in your AppDelegate.

class ExampleApplication : Application() {
 override fun onCreate() {
   super.onCreate()
   
   NotificationAutocaptureSDK.captureInitialNotifications()
 }
}

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Heap.NotificationAutocaptureSource.captureInitialNotifications()
  }
}

This call will cause Heap to start tracking notifications for 10 seconds and store those events locally until your startRecording() call has executed. Once recording has started, those events will be uploaded to Heap. If recording doesn't start in those 10 seconds, those events will be dropped.

What next?

With notification data flowing, you'll want to jump into Heap and start defining notification interaction events. These events will show up as a special "Notification Interaction" event type in Heap and have several properties available to create definitions:

Notification Title: The title text of the notification. Capture can be enabled/disabled via a config option as described above.
Notification Body: The body text of the notification. Capture can be enabled/disabled via a config option as described above.
Notification Action: The text of the notification action that was interacted with, if any.
Notification Source: What caused the notification to fire. This could be a push service, a geofence, or unknown.
Notification Handling Component: The name of the component in code that handled the notification interaction. Only available on Android.
Notification Category: On iOS, this is the category of the notification. On Android, this is the notification channel that the notification was delivered to. This typically denotes the type of notification that with which the interaction occurred.