NotificationConfig Android only¶

export interface NotificationConfig {

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.

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({
  app: {
    notification: {
      title: "The Title",
      text: "The Text"
    }
  }
});

// Update notification fields at runtime.
// Only changed keys must be provided; existing values persist.
BackgroundGeolocation.setConfig({
  app: {
    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¶

actions?: string[];

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({
  app: {
    notification: {
      actions: [
        "notificationButtonPause"   // <-- register button listeners
      ]
    }
  }
});

// Listen to custom button clicks:
BackgroundGeolocation.onNotificationAction((buttonId) => {
  console.log("[onNotificationAction] - ", buttonId);
  switch (buttonId) {
    case "notificationButtonPause":
      BackgroundGeolocation.changePace(false);
      break;
    // ...
  }
});

Register button listeners¶

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

// Listen to custom button clicks:
BackgroundGeolocation.onNotificationAction((buttonId) => {
  console.log("[onNotificationAction] - ", buttonId);
  switch (buttonId) {
    case "notificationButtonPause":
      BackgroundGeolocation.changePace(false);
      break;
    // ...
  }
});

channelId¶

channelId?: string;

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¶

channelName?: string;

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({
  app: {
    notification: {
      channelName: "Location Tracker"
    }
  }
});

// Update at runtime
BackgroundGeolocation.setConfig({
  app: {
    notification: {
      channelName: "My new channel name"
    }
  }
});

color¶

color?: string;

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

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

largeIcon¶

largeIcon?: string;

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

// drawable resource
BackgroundGeolocation.ready({
  app: {
    notification: {
      largeIcon: "drawable/my_notification_large_icon"
    }
  }
});

// mipmap resource
BackgroundGeolocation.ready({
  app: {
    notification: {
      largeIcon: "mipmap/my_notification_large_icon"
    }
  }
});

layout¶

layout?: string;

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({
  app: {
    notification: {
      layout: "my_notification_layout",
      title: "The Notification Title",
      text: "The Notification Text",
      smallIcon: "mipmap/my_small_icon",
      largeIcon: "mipmap/my_large_icon"
    }
  }
});

Custom `<TextView />` elements¶

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

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

Custom `<Button />` elements¶

Define your own buttons and register click listeners using actions.

BackgroundGeolocation.ready({
  app: {
    notification: {
      actions: [
        "notificationButtonFoo",
        "notificationButtonBar"
      ]
    }
  }
});

BackgroundGeolocation.onNotificationAction((buttonId) => {
  console.log("[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>

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

BackgroundGeolocation.onNotificationAction((buttonId) => {
  console.log("[onNotificationAction]", buttonId);
  switch (buttonId) {
    case "notificationButtonFoo":
      break;
    case "notificationButtonBar":
      break;
  }
});

BackgroundGeolocation.ready({
  app: {
    notification: {
      actions: [
        "notificationButtonFoo",
        "notificationButtonBar"
      ]
    }
  }
});

BackgroundGeolocation.onNotificationAction((buttonId) => {
  console.log("[onNotificationAction]", buttonId);
  switch (buttonId) {
    case "notificationButtonFoo":
      break;
    case "notificationButtonBar":
      break;
  }
});

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

BackgroundGeolocation.onNotificationAction((buttonId) => {
  console.log("[onNotificationAction]", buttonId);
  switch (buttonId) {
    case "notificationButtonFoo":
      break;
    case "notificationButtonBar":
      break;
  }
});

priority¶

priority?:NotificationPriority;

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({
  app: {
    notification: {
      priority: NotificationPriority.High
    }
  }
});

smallIcon¶

smallIcon?: string;

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

// drawable resource
BackgroundGeolocation.ready({
  app: {
    notification: {
      smallIcon: "drawable/my_notification_icon"
    }
  }
});

// mipmap resource
BackgroundGeolocation.ready({
  app: {
    notification: {
      smallIcon: "mipmap/my_notification_icon"
    }
  }
});

sticky¶

sticky?: boolean;

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¶

strings?: Record<string, string>;

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