ENGAGE® Flutter Plugin Firebase for Android

The app must communicate with Firebase in order for apps to receive content and to perform Registration for Android only. By default, the ENGAGE Plugin will use First Orion's Firebase instance to send and receive ENGAGE content. It does this without needing additional integration steps aside from including the required Firebase components.

📘

NOTE

A host app can still use their own Firebase instance to handle host app specific features. Additional setup is required for this use case (discussed below).

Firebase Integration

The ENGAGE SDK requires the host app to include one of the two ENGAGE Firebase components. The needs of the host app will dictate which component needs to be imported.

Host App Does Not Use Firebase

If the host app does not use its own Firebase instance, no additional setup is required except to import the desired ENGAGE Firebase component.

Host App Uses Firebase

If the host app uses its own Firebase instance, then some additional setup is required to make sure ENGAGE FCM pushes come through correctly.

Step1. Configure Firebase Messaging Background Handler

The _firebaseMessagingBackgroundHandler must be a top-level function to execute correctly. This is necessary for handling background messages effectively.

1.1 Call Firebase.initializeApp to initialize Firebase services before performing any other Firebase-related operations. This ensures that Firebase is ready to handle background tasks.

1.2 Use Engage.instance.configureSDK to configure the Engage SDK. This is important because Engage's work manager auto-initialization is disabled, and we need to ensure it is initialized manually.

1.3 Check if the incoming message is an Engage push notification using Engage.instance.isEngagePush(message.data). If it is, handle it using Engage.instance.handlePushNotification(message.data).

1.4 Set up a listener for Firebase messages received while the app is in the foreground using FirebaseMessaging.onMessage.listen. This ensures that notifications are handled even when the app is actively being used.

1.5 Set up a listener for Firebase messages received while the app is in the background using FirebaseMessaging.onBackgroundMessage. This allows handling notifications when the app is not in the foreground.

// this must be top level function otherwise it not executed
@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
 // If you're going to use other Firebase services in the background, such as Firestore,
 // make sure you call `initializeApp` before using other Firebase services.
 await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

 // Ensure the Engage SDK Is configured, since we disabled Engage work manager
 // auto initialization. Will do nothing if Engage is already initialized.
 await Engage.instance.configureSDK(null, null);

 if (await Engage.instance.isEngagePush(message.data)) {
   Engage.instance.handlePushNotification(message.data);
 }
}

class FirebaseApi {
 static void initNotification() {
   // Setup Firebase foreground and background listeners.
   FirebaseMessaging.onMessage.listen(_firebaseMessagingBackgroundHandler);
   FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
 }
}

Step 2. Initialize Firebase and ENGAGE SDK

Initialize the Firebase and ENGAGE SDK before starting the app in the main.dart.

2.1 Initialize Firebase using Firebase.initializeApp with the appropriate options.

2.2 Call FirebaseApi.initNotification() to set up Firebase notification handlers. This configures listeners for handling notifications.

2.3 Initialize the Engage SDK using Engage.instance.configureSDK after Firebase initialization to ensure Firebase services are ready for any interactions.

void main() async {
 WidgetsFlutterBinding.ensureInitialized();

 if (Platform.isAndroid) {
   // For Android, the client must initialize their Firebase instance before
   // calling configureSDK on Engage.
   await Firebase.initializeApp(options: DefaultFirebaseOptions.android);

   // Initialize Firebase Notification handlers. These will handle logic to hand
   // off Engage pushes to the Engage SDK.
   FirebaseApi.initNotification();
 }

 // Initialize the Engage SDK.
 await Engage.instance.configureSDK(EngageEnvironment.debug, “group.your-app-group-id");

 runApp(const EngageApp());
}

The host app should now be able to receive FCM pushes without interfering with the ENGAGE SDK's functionality.

Host App Uses Own Firebase For ENGAGE SDK

By default, the ENGAGE SDK uses First Orion's Firebase instance to handle ENGAGE content pushes. This can be paired up with the host app's own Firebase instance allowing the ENGAGE SDK to use First Orion's Firebase instance to handle all ENGAGE-related functionality and the host app to use its own Firebase instance to deal with non-ENGAGE-related functionality. Refer to the sections above.

ENGAGE can be configured to skip First Orion's Firebase instance and use the host app's Firebase instance instead. Under the rare circumstance that the host app is required use its own Firebase instance for ENGAGE instead of using First Orion's Firebase instance, please reach out to the First Orion platform team.