Standard

Remote notifications allow your application to receive messages from Actito in real time, even when the app is not active. To enable this functionality, include the actito-push module in your project. This module provides all the components necessary to register the push subscription and handle incoming notifications. You may implement a custom user interface to present notifications. However, we recommend including the actito-push-ui module to take advantage of the managed notification UI, which simplifies implementation and ensures a consistent user experience.

dependencies {
    def actito_version = 'REPLACE_WITH_LATEST_VERSION'
    implementation "com.actito:actito-push:$actito_version"
    implementation "com.actito:actito-push-ui:$actito_version"
}

Requirements

Before getting started with this module, ensure that the following steps have been completed:

• You have successfully completed the Getting Started guide
• You have set up Firebase Cloud Messaging (FCM) for your application

Notification provider environments

As described in the Environments section of the Getting Started guide, maintaining separate environments for development and production is essential. This separation becomes even more critical when implementing remote notifications.

Each environment should use its own Actito Services configuration to ensure consistent and isolated registration of push subscriptions. For example, development builds should receive notifications only from the development environment, while production builds communicate exclusively with the production environment. This approach ensures data consistency and a clean testing process.

Requesting permission

To receive remote notifications on Android, your application must request the user’s permission to display notifications. This can typically be done during the onboarding flow or at the point where notifications are first needed.

class MainActivity : AppCompatActivity() {
    private val notificationsPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->
        if (granted) {
            // Permission granted — enable remote notifications
            enableRemoteNotifications()
        } else {
            // Permission denied — handle accordingly
            // You may show a dialog explaining why notifications are useful
        }
    }

    private fun onEnableRemoteNotificationsClicked() {
        // On older Android versions, permission is granted by default
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
            enableRemoteNotifications()
            return
        }

        // Request permission only on Android 13 and above

        when {
            ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED -> {
                // Already granted
                enableRemoteNotifications()
            }

            shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS) -> {
                // Explain to the user why the permission is needed before requesting again
                AlertDialog.Builder(this)
                    .setTitle(R.string.app_name)
                    .setMessage(R.string.notifications_permission_rationale)
                    .setPositiveButton(android.R.string.ok) { _, _ ->
                        notificationsPermissionLauncher.launch(permission)
                    }
                    .show()
            }

            else -> {
                // Request the permission
                notificationsPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
            }
        }
    }

    private fun enableRemoteNotifications() {
        lifecycleScope.launch {
            try {
                Actito.push().enableRemoteNotifications()
            } catch (e: Exception) {
                // Gracefully handle the error
            }
        }
    }
}

note

• For Android 12 (API 32) and lower, no explicit user permission is required.
• It is recommended to request notification permission during onboarding or at a time when the value of notifications is clear to the user.
• Always handle the case where the user denies permission gracefully.

Enabling remote notifications

Once the necessary permissions are granted, you can enable remote notifications through the Actito SDK:

Actito.push().enableRemoteNotifications()

After enabling, the SDK will register the device for notifications with Actito.

You can check the user’s current enrollment and permission status using:

// Check if the user has previously enabled remote notifications.
Actito.push().hasRemoteNotificationsEnabled

// Check if the device is allowed to receive remote notifications.
Actito.push().allowedUI

These checks can help you update your app’s UI to reflect the user’s notification status or guide them to re-enable permissions if needed.

Disabling remote notifications

If the user chooses to stop receiving notifications, you can disable them programmatically:

Actito.push().disableRemoteNotifications()

This action unregisters the device from receiving further remote notifications. It is recommended to provide a clear opt-out option in your app’s settings to comply with privacy and consent requirements.

Handling remote notifications

To properly handle remote notifications, your application’s Activity must act as a trampoline — receiving and processing the intents triggered when a user opens a notification or taps a notification action.

Typically, this will be your MainActivity. To enable it to receive these intents, declare the appropriate intent filters in your AndroidManifest.xml.

<activity android:name=".MainActivity" android:launchMode="singleTask">
    <intent-filter>
        <action android:name="com.actito.intent.action.RemoteMessageOpened" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Launch mode configuration

The Activity responsible for handling notification intents must use android:launchMode="singleTask". This configuration ensures that the activity is not recreated multiple times when processing a series of intents triggered by opening notifications from the system tray.

For additional details, refer to the official Android documentation on Activity launch modes.

Declaring intent filter for notification events

A notification can be opened either by tapping the notification itself or by selecting one of its actions. In both cases, the SDK emits an intent targeted at any Activity that declares the corresponding intent filters.

Add the following entries to your AndroidManifest.xml to handle both scenarios:

<activity android:name=".MainActivity" android:launchMode="singleTask">
    <intent-filter>
        <action android:name="com.actito.intent.action.NotificationOpened" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>

    <intent-filter>
        <action android:name="com.actito.intent.action.ActionOpened" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Handling notification intents

In order to process these intents, your MainActivity must handle them appropriately in its lifecycle methods. The following example illustrates how to handle the notification intents:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Prevent processing the intent again on configuration changes
        if (intent != null && savedInstanceState == null) {
            handleIntent(intent)
        }
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleIntent(intent)
    }

    private fun handleIntent(intent: Intent) {
        // Handle trampoline intent
        if (Actito.push().handleTrampolineIntent(intent)) return

        // Handle notification opened
        Actito.push().parseNotificationOpenedIntent(intent)?.also { result ->
            // Using managed approach to display notification UI
            Actito.pushUI().presentNotification(this, result.notification)
            return
        }

        // Handle notification action opened
        Actito.push().parseNotificationActionOpenedIntent(intent)?.also { result ->
            // Using managed approach to display action UI
            Actito.pushUI().presentAction(this, result.notification, result.action)
            return
        }

        // Additional app-specific intent handling...
    }
}

To achieve a seamless presentation of Alert type notification over your app's content, we recommend theming the NotificationActivity with a transparent background style. You can find out more about theming the NotificationActivity in our customization guide.

Managed vs. Manual handling

You can handle these notification events in one of two ways:

• Managed Approach (Recommended) — Include and use the actito-push-ui module to display notifications, actions, and track their engagement. This approach ensures consistency, proper event tracking, and integration with Actito.
• Manual Approach — Implement your own notification presentation logic. This provides full control over the UI and behavior but requires handling all notification types, user interactions, and event reporting manually.

caution

If you choose the manual approach, you are responsible for managing the full notification lifecycle, including engagement tracking required for analytics and reporting.