NotificationConfig Android only

classNotificationConfig

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.

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // Notification config is managed via the Android notification builder
    // or through the config.app namespace.
}

// Update notification fields at runtime.
bgGeo.config.edit {
    // Notification title/text are configured via Android's
    // foreground service notification builder pattern.
}

---

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

val actions: List<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" />

Register button listeners

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // Register button actions via Android notification layout configuration.
    // Custom notification actions are configured through the Android
    // notification builder pattern with custom layout XML.
}

// Note: onNotificationAction is not exposed in the Kotlin API.
// Use Android's notification action handling directly in your
// headless job service or activity.

channelId

val 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

val 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

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // channelName is configured through the Android notification
    // channel setup in your Application class.
}

color

val color: String

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

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

largeIcon

val 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

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // Large icon is configured through the Android notification builder.
    // Use NotificationCompat.Builder.setLargeIcon() in your notification setup.
}

layout

val 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

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // Custom notification layout is configured through Android's
    // NotificationCompat.Builder with RemoteViews pointing to
    // your custom layout XML resource (e.g., R.layout.my_notification_layout).
}

Custom <TextView /> elements

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

Custom <Button /> elements

Define your own buttons and register click listeners using actions.

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // Custom notification strings are set via Android's RemoteViews API:
    // remoteViews.setTextViewText(R.id.myCustomElement, "My Custom Element Text")
}

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>

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // Notification button actions are configured via Android's
    // notification builder with PendingIntent actions.
}

// Note: onNotificationAction is not exposed in the Kotlin API.
// Handle notification button clicks via Android's BroadcastReceiver
// or your headless job service.

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // Custom notification layout, title, text, actions, and strings
    // are configured through Android's NotificationCompat.Builder
    // with RemoteViews and PendingIntent actions.
}

priority

val 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.

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    app.notification.priority = NotificationPriority.HIGH
}

smallIcon

val 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

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // Small icon is configured through the Android notification builder:
    // NotificationCompat.Builder.setSmallIcon(R.drawable.my_custom_notification_small_icon)
    // or
    // NotificationCompat.Builder.setSmallIcon(R.mipmap.my_custom_notification_small_icon)
}

sticky

val 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

val strings: Map<String, String>

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" />

// Within a coroutine scope
val bgGeo = BGGeo.instance

bgGeo.ready {
    // Custom notification strings are set via Android's RemoteViews API:
    // remoteViews.setTextViewText(R.id.myCustomElement, "My Custom Element Text")
}

text

val text: String

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

title

val title: String

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