Real-Time Listeners

Overview

Instead of querying the SDK for data or insights, you can subscribe to listeners to receive notifications whenever specific events occur or when insights are processed and available. This is done through listeners.

Listeners can operate:

• In the foreground – while the app is open and visible.

• In the background – even when the app is closed or the screen is turned off.

Background listeners are available for the following main features:

• Driving Insights Notifies when a transport is fully processed and driving insights are available.

• Lifestyle Insights Notifies when the user's current context changes (e.g. a new segment is detected, the user's venue is detected (such as home or work), or the user transitions between stationary and transport).

• Mobility Insights Notifies when a new timeline event is detected (e.g., stationary, transport).

• Smart Geofences Notifies when the user enters or exits a place of interest.

• Crash Detection Near real-time notification when a crash is detected, including crash details.

• SDK Status Changes Notifies when the SDK's status changes (permissions, location availability, detection status, etc.).

Listeners should be subscribed as early as possible during app startup, ideally in the main thread, and after a successful SDK initialization. This ensures that your app does not miss any notifications.

Platform Configuration

When implementing background listeners, you must include the required platform dependencies and perform the necessary initialization in the native code of your application.

Refer to the code examples below to understand how to register and initialize background listeners. In the following example, we use the Event Timeline listener, but the same workflow applies to the other background listeners.

iOS

The dependecies are already included in the SDK module, so no new imports are nessesary.

1. To register, set: Sentiance.shared.eventTimelineDelegate = yourDelegate

   This delegate will trigger the logic defined in the onEventTimelineUpdate(e) method of your delegate class.

2. Make sure to implement the necessary actions inside the onEventTimelineUpdate method.

public class EventTimelineUpdateReceiver: EventTimelineDelegate {
    init() {
        ...
    }
    
    public func listenForUpdates() {
        // Set the delegate to start listening for timeline updates.
        Sentiance.shared.eventTimelineDelegate = self
    }
    
    public func onEventTimelineUpdate(event: SENTTimelineEvent) {
        // Note: this delegate method invocation happens on the main/UI thread.
        // Logic to run when notified
    }
    
    // Unset the delegate to stop receiving updates
    public func stopListening() {
        Sentiance.shared.eventTimelineDelegate = nil
    }
}

Android

1. Include the nessesary dependecies in your app module's build.gradle file

// example for EventTimeline Listener:
dependencies {
    implementation(platform('com.sentiance:sdk-bom:<sentiance-version>'))
    implementation('com.sentiance:sdk-event-timeline')
}

1. Implement the listeners using the setTimelineUpdateListener method.

public class EventTimelineUpdateReceiver(val context: Context) {
    private val api = EventTimelineApi.getInstance(context.applicationContext)
    
    init {
        ...
    }

    fun listenForUpdates() {
        api.setTimelineUpdateListener { event ->
            // Note: this invocation happens on the main/UI thread.
           // logic to run when event is detected.
        }
    }
    
    // Stop listening for updates
    fun stopListening() {
        api.setTimelineUpdateListener(null)
    }
}

React Native

To get the listener to work when your app is in the background, place the code inside your app's entrypoint (ex. index.js / index.ts). if you are only interested in the listener when the app is in the foreground, you can place the logic in the appropriate UI code instead.

import EventTimelineApi from '@sentiance-react-native/event-timeline';

// Make sure the SDK is initialized by awaiting SentianceCore.ensureInitialized()
// before you call this function.
async function startListening(){
    const suscribtion = await EventTimelineApi.addTimelineUpdateListener( 
        async (event)=> {
            // logic to run when event is detected.
        } 
    )
}

async function stopListening(){
    // pass null as the argument to stop listenning.
    EventTimelineApi.addTimelineUpdateListener(null)
}

Flutter

To enable background listeners in Flutter, you need to subscribe to them through a Dart VM entry point. This creates a separate background process that can run independently from the main application logic.

Keep in mind that this background process has its own memory space and cannot directly communicate with the main process. To exchange data between them, you must set up communication channels such as ReceivePort/SendPort.

Additionally, some initialization code is required for background functions to work correctly.

Recommended Approach

1. Create a background.dart file This file will contain your listeners and vm:entry-point functions

2. Import the required dependencies For example: import SentianceEventTimeline

3. Define a Dart VM entry point create a function and annotate the function with @pragma('vm:entry-point') this will tell the OS that the function can be executed in a separate background isolate

4. Subscribe to listeners Within the entry point function, subscribe to the appropriate listener and define the logic that should run when an event is detected.

background.dart

...
import 'package:flutter/material.dart';
import 'package:sentiance_core/sentiance_core.dart';
import 'package:sentiance_event_timeline/sentiance_event_timeline.dart';

@pragma('vm:entry-point')
void registerEventTimelineListener() async {
    WidgetFlutterBinding.ensureInitialized();
    await SentianceCore.ensureInitialized(); // Make sure the SDK is initialized
    
    SentianceEventTimeline.registerEventTimelineUpdateListener((event){
        // Logic to run when event is detected
    })
}

Make sure to import background.dart in your main.dart file. This guarantees that the Dart VM entry point and related background code are retained and included in the final compiled binary.

Register the listener in Native code

Every Sentiance plugin your app depends on is registered automatically on the background engine, so you can call any Sentiance API from inside your listener. checkout this page if your callback also uses non-Sentiance plugins, as they need to be properly initialized and registered together with the Sentiance Background Listener.

iOS

• Initialize the listener in the AppDelegate class.

• Point it to the Dart VM entry point method.

• Add the following code inside your AppDelegate.swift file:

AppDelegate Class

import Flutter
import UIKit
import sentiance_core
import sentiance_event_timeline

@main
@objc class AppDelegate: FlutterAppDelegate {

    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // other code

        SentianceCorePlugin.shared.initializeAsync(launchOptions: launchOptions) { result, error in
            if result != nil {
                // Replace '<your_app_package_name>' with the name of your app package
                // as shown inside your project's pubspec.yaml file
                let libraryURI = "package:<your_app_package_name>/background.dart"
                let dartCallbackName = "registerEventTimelineListener"

                SentianceEventTimelinePlugin.initializeListener(
                    withEntryPoint: dartCallbackName,
                    libraryURI: libraryURI,
                    includeProvisionalEvents: true
                )
            }
        }

        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}

Android

• Initialize the listener in your Application class.

• Point it to the Dart VM entry point method.

• Create an Application class (if you haven't already) and add the following code inside:

Application Class

import android.app.Application
import com.sentiance.event_timeline_plugin.EventTimelinePlugin

// Don't forget to update your app's manifest:
// <application android:name=".MainApplication" ...></application>
class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize the Sentiance SDK first
        CorePlugin.initializeAsync(this)
            .addOnSuccessListener {
                // Replace '<your_app_package_name>' with the name of your app package
                // as shown inside your project's pubspec.yaml file
                val dartLibrary = "package:<your_app_package_name>/background.dart"
                // Make sure the callback name specified here matches the name of the
                // callback you previously defined in your Dart code
                val dartCallbackName = "registerEventTimelineListener"

                EventTimelinePlugin.initializeListener(
                    context = this,
                    dartEntryPointLibrary = dartLibrary,
                    dartEntryPointFunctionName = dartCallbackName,
                    includeProvisionalEvents = true
                )
            }

        // Other code
    }
}