NotificationConfig Android only

class Notification

Foreground service notification configuration for the background geolocation SDK.

Android requires a persistent notification whenever the SDK runs its foreground service. NotificationConfig controls that notification's content, appearance, and behaviour while tracking is active.

Contents

• Overview
• Custom layout

---

Overview

Configure this via NotificationConfig on AppConfig.notification.

Category	Properties	Notes
Content	title, text, color	Notification text and accent color.
Icons	smallIcon, largeIcon	Resource references in type/name format.
Channel	channelName, channelId	Android O+ notification channel settings.
Behaviour	sticky, priority	Persistence and ordering.
Custom layout	layout, strings, actions	Custom XML layout with text fields and buttons.

BackgroundGeolocation.ready(Config(
  app: AppConfig(
    notification: Notification(
      title: "The Title",
      text: "The Text"
    )
  )
));

// Update notification fields at runtime.
// Only changed keys must be provided; existing values persist.
BackgroundGeolocation.setConfig(Config(
  app: AppConfig(
    notification: Notification(
      title: "The New Title",
    )
  )
));

---

Custom layout

Supply a custom Android Layout XML file via NotificationConfig.layout for complete control over the notification appearance.

See the Android Custom Notification Layout guide for full setup instructions.

---

Members

actions

List<String>? actions

Declare click listeners for <Button /> elements of a custom notification layout.

See Android Custom Notification Layout for setup instructions.

Declare <Button /> elements in your layout XML, then list their android:id values in the actions array to register click listeners.

Custom <Button /> element

<Button
  android:id="@+id/notificationButtonPause"
  style="@style/Widget.AppCompat.Button.Small"
  android:layout_width="60dp"
  android:layout_height="40dp"
  android:text="Foo" />

BackgroundGeolocation.ready(Config(
  app: AppConfig(
    notification: Notification(
      actions: [
        "notificationButtonPause"   // <-- register button listeners
      ]
    )
  )
));

// Listen to custom button clicks:
BackgroundGeolocation.onNotificationAction((buttonId) {
  print('[onNotificationAction] -  ${buttonId}');
  switch (buttonId) {
    case "notificationButtonPause":
      BackgroundGeolocation.changePace(false);
      break;
    // ...
  }
});

Register button listeners

BackgroundGeolocation.ready(Config(
  notification: Notification(
    actions: [  // <-- register button listeners
      "notificationButtonPause"
    ]
  )
));

// Listen to custom button clicks:
BackgroundGeolocation.onNotificationAction((String buttonId) {
  print("[onNotificationAction] - ${buttonId}");
  switch(buttonId) {
    case 'notificationButtonPause':
      BackgroundGeolocation.changePace(false);
      break;
  }
});

channelId

String? channelId

Identifier of the Android notification channel used for the foreground service notification. Defaults to "bggeo".

Note

Changing this is not typically required. A use case is sharing an existing notification channel with another foreground service in the same app.

channelName

String? channelName

Name of the Android notification channel used for the foreground service notification. Defaults to "BackgroundGeolocation".

On Android O and above, foreground services require a notification channel. The channel name is visible to users under:

Settings → Apps & Notifications → Your App

BackgroundGeolocation.ready(Config(
  notification: Notification(
    channelName: "Location Tracker"
  )
));

// or with #setConfig
BackgroundGeolocation.ready(Config(
  notification: Notification(
    channelName: "My new channel name"
  )
));

color

String? color

Accent color of the notification icon. Not set by default.

Applies to API level 21 and above. Supported formats: - #RRGGBB - #AARRGGBB

largeIcon

String? largeIcon

Large icon for the foreground notification. Not set by default.

Warning

• Specify the resource type (drawable or mipmap) followed by the icon name in the format type/icon_name.
• Do not include the file extension (e.g. .png).

See also - smallIcon

// 1. drawable
BackgroundGeolocation.ready(Config(
  notification: Notification(
    largeIcon: "drawable/my_custom_notification_large_icon"
  )
});

// 2. mipmap
BackgroundGeolocation.ready(Config(
  notification: Notification(
    largeIcon: "mipmap/my_custom_notification_large_icon"
  )
});

layout

String? layout

Name of a custom Android Layout XML file for the foreground notification.

See also - Android Custom Notification Layout

Custom layouts support <TextView />, <ImageView />, and <Button /> elements. All android:id values must be prefixed with notification (e.g. notificationText, notificationTitle). The one exception is applicationName, which the SDK populates with the app name automatically.

Layout special elements

When rendering a custom notification, the SDK searches for the following IDs and populates them from the associated data source:

Layout element android:id	Data source
applicationName	Application name from AndroidManifest
notificationTitle	title
notificationText	text
notificationSmallIcon	smallIcon
notificationLargeIcon	largeIcon

BackgroundGeolocation.ready(Config(
  notification: Notification(
    layout: "my_notification_layout",  // <-- custom layout xml file
    title: "The Notification Title",
    text: "The Notification Text",
    smallIcon: "mipmap/my_small_icon", // <-- defaults to app icon
    largeIcon: "mipmap/my_large_icon"
  )
));

Custom <TextView /> elements

You may define your own custom text fields and populate them using strings.

BackgroundGeolocation.ready(Config(
  notification: Notification(
    strings: {
      "myCustomElement": "My Custom Element Text"
    }
  )
));

Custom <Button /> elements

Define your own buttons and register click listeners using actions.

BackgroundGeolocation.ready(Config(
  notification: Notification(
    actions: [  // <-- register button listeners
      "notificationButtonFoo",
      "notificationButtonBar"
    ]
  )
));

// Listen to custom button clicks:
BackgroundGeolocation.onNotificationAction((String buttonId) {
  print("[onNotificationAction] - ${buttonId}");
  switch(buttonId) {
    case 'notificationButtonFoo':
      break;
    case 'notificationButtonBar':
      break;
  }
});

Sample layout

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="135dp"
    android:gravity="start"
    android:orientation="vertical"
    android:padding="15dp">

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginBottom="15dp"
        android:gravity="center"
        android:orientation="horizontal">

        <ImageView
            android:id="@+id/notificationSmallIcon"
            android:layout_width="16dp"
            android:layout_height="16dp"
            android:tint="@android:color/background_dark"
            tools:srcCompat="@tools:sample/avatars" />

        <TextView
            android:id="@+id/applicationName"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            android:paddingLeft="10dp"
            android:text="applicationName"
            android:textAppearance="@style/TextAppearance.Compat.Notification.Title"
            android:textColor="#888888"
            android:textSize="12sp" />
    </LinearLayout>

    <TextView
        android:id="@+id/notificationTitle"
        style="@style/TextAppearance.Compat.Notification.Title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="notificationTitle"
        android:textSize="14sp" />

    <TextView
        android:id="@+id/notificationText"
        style="@style/TextAppearance.Compat.Notification.Line2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="notificationText"
        android:textSize="14sp" />

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:gravity="right"
        android:orientation="horizontal">

        <Button
            android:id="@+id/notificationButtonFoo"
            style="@style/Widget.AppCompat.Button.Small"
            android:layout_width="60dp"
            android:layout_height="40dp"
            android:text="FooA" />

        <Button
            android:id="@+id/notificationButtonBar"
            style="@style/Widget.AppCompat.Button.Small"
            android:layout_width="60dp"
            android:layout_height="40dp"
            android:text="Bar" />
    </LinearLayout>
</LinearLayout>

// Listen to custom notification button clicks (notification.actions)
BackgroundGeolocation.onNotificationAction((buttonId) {
  print("[onNotificationAction] ${buttonId}");
  switch(buttonId) {
    case 'notificationButtonFoo':
      // Handle button click on [Foo]
      break;
    case 'notificationButtonBar':
      // Handle button click on [Bar]
      break;
  }
});

BackgroundGeolocation.ready(Config(
  notification: Notification(
    title: "The title",
    text: "The text",
    layout: "notification_layout",
    actions: [  // <-- register button listeners
      "notificationButtonFoo",
      "notificationButtonBar"
    ]
  )
));

BackgroundGeolocation.ready(Config(
  app: AppConfig(
    notification: Notification(
      actions: [
        "notificationButtonFoo",
        "notificationButtonBar"
      ]
    )
  )
));

BackgroundGeolocation.onNotificationAction((buttonId) {
  print('[onNotificationAction] ${buttonId}');
  switch (buttonId) {
    case "notificationButtonFoo":
      break;
    case "notificationButtonBar":
      break;
  }
});

BackgroundGeolocation.ready(Config(
  app: AppConfig(
    notification: Notification(
      title: "The title",
      text: "The text",
      layout: "notification_layout",
      actions: [
        "notificationButtonFoo",
        "notificationButtonBar"
      ],
      strings: {
        myCustomTextBox1: "custom TextBox element"
      }
    )
  )
));

BackgroundGeolocation.onNotificationAction((buttonId) {
  print('[onNotificationAction] ${buttonId}');
  switch (buttonId) {
    case "notificationButtonFoo":
      break;
    case "notificationButtonBar":
      break;
  }
});

priority

NotificationPriority? priority

Controls the position and visibility of the foreground notification in the system shade. Defaults to PRIORITY_LOW (-1).

priority affects both the ordering of the notification in the notification shade and the position/visibility of the small status-bar icon.

Value	Description
NotificationPriority.Default	Weighted toward the top; status-bar icon left-aligned.
NotificationPriority.High	Strongly weighted to the top; icon strongly left-aligned.
NotificationPriority.Low	Weighted toward the bottom; icon right-aligned.
NotificationPriority.Max	Equivalent to NOTIFICATION_PRIORITY_HIGH.
NotificationPriority.Min	Strongly weighted to the bottom; icon hidden.

BackgroundGeolocation.ready(Config(
  notification: Notification(
    priority: NotificationPriority.min
  )
));

smallIcon

String? smallIcon

Small status-bar icon for the foreground notification. Defaults to "mipmap/ic_launcher" (the app launcher icon).

Warning

• Specify the resource type (drawable or mipmap) followed by the icon name in the format type/icon_name.
• Do not include the file extension (e.g. .png).

See also - largeIcon

// 1. drawable
BackgroundGeolocation.ready(Config(
  notification: Notification(
    smallIcon: "drawable/my_custom_notification_small_icon"
  )
));

// 2. mipmap
BackgroundGeolocation.ready(Config(
  notification: Notification(
    smallIcon: "mipmap/my_custom_notification_small_icon"
  }
});

sticky

bool? sticky

Keeps the foreground service notification visible at all times, regardless of motion state. Defaults to false.

By default the notification is shown only while the SDK detects the device is moving. Set to true to show the notification continuously — for example, when full transparency to users is a requirement.

strings

Map<String, String>? strings

Custom strings to render into <TextView /> elements of a custom notification layout.

See Android Custom Notification Layout for setup instructions.

Declare your own <TextView /> elements in the layout XML and populate them by supplying matching key/value pairs in strings, where the key matches the android:id of the element.

<TextView
  android:id="@+id/myCustomElement"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:text="notificationTitle" />

BackgroundGeolocation.ready(Config(
  notification: Notification(
    strings: {
      "myCustomElement": "My Custom Element Text"
    }
  )
));

text

String? text

Body text of the foreground service notification. Defaults to "Tracking location".

title

String? title

Title of the foreground service notification. Defaults to "Background Geolocation".