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, we need to initialized ENGAGE SDK before anything else because if it not initialized in application class than in device reboot event ENGAEG SDK not able to start.

import com.firstorion.engage.core.EngageApp
import com.firstorion.engage.core.IEngageLoggingInterceptor
import io.flutter.app.FlutterApplication
import android.util.Log

class MyApplication : FlutterApplication(), IEngageLoggingInterceptor {
    
  override fun onCreate() {
        super.onCreate()
       
        // Initilize the ENGAGE SDK //
        // if host app not use firebase in flutter app than call this method
        EngageApp.initializeEngage(this)

        // logging interceptpr 
        EngageApp.Settings.setLoggingInterceptor(this)
    }
  
    override fun intercept(message: String, level: Int) {
        println("engage.app  $message" )
    }
  
}

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 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.3 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.4 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);


 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

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.

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 for only ios platform and for android call in application class.
  if(Platform.isIOS){
    await Engage.instance.configureEngageForIOS(EngageEnvironment.production, "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.