Integrate your Flutter Android app

This article provides information on how to integrate your Flutter app with our platform.

Firebase Messaging

Blueshift uses Firebase Cloud Messaging to send push notifications to Android devices. To install the Firebase Messaging plugin, follow this documentation.

Once you install the Firebase Messaging plugin, add the following code to your app to let Blueshift handle the push notifications.

Future<void> _handleRemoteMessage(RemoteMessagemessage) async{
    Blueshift.handlePushNotification(message.data);
}

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
	
    await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
	
    // https://github.com/firebase/flutterfire/issues/6011
    await FirebaseMessaging.instance.getToken();
	
    // listen for notifications while the app is in the background or terminated.
    FirebaseMessaging.onBackgroundMessage(_handleRemoteMessage);
	
    FirebaseMessaging.onMessage.listen((RemoteMessagemessage){
        _handleRemoteMessage(message);
    });
	
    runApp(MyApp());
}

Permissions

Add the following permissions to your AndroidManifest file.

<!-- Internet permission is required to send events, 
get notifications and in-app messages. -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Network state access permission is required to detect changes 
in network connection to schedule sync operations. -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Location access permission is required if you want to track the 
location of the user. You can skip this step if you don't want to 
track the user location. -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

SDK Initialization

Blueshift's Android SDK will initialize automatically when the Flutter app starts. You must provide the required configuration in the form of meta-data inside AndroidManifest.xml to initialize the SDK successfully.

Mandatory Configuration

Obtain the Event API key from Blueshift's dashboard and add it to the AndroidManifest file as mentioned in the following example.

<meta-data
    android:name="com.blueshift.config.API_KEY"
    android:value="BLUESHIFT_EVENT_API_KEY" />

Optional configurations

If you are using Blueshift only to capture events, skip to the next section. Curious minds can read along.

Region

The region of Blueshift's data center.

<meta-data
    android:name="com.blueshift.config.REGION"
    android:value="US" /> <!-- Supported values: US, EU | default: US -->

In-app messages

To enable in-app messages, set the following two configurations in your AndroidManifest file.

<meta-data
    android:name="com.blueshift.config.ENABLE_IN_APP"
    android:value="true" /> <!-- Supported values: true, false | default: false -->

The in-app messages also support HTML content. To support JavaScript code execution, enable the following flag.

<meta-data
    android:name="com.blueshift.config.ENABLE_IN_APP_JS"
    android:value="true" /> <!-- Supported values: true, false | default: false -->
Register all screens

You must register the app's screens with the SDK to be able to display in-app messages to the user. Use the following configuration to register all the screens in the app.

<meta-data
    android:name="com.blueshift.config.IN_APP_ON_ALL_SCREENS"
    android:value="true" /> <!-- Supported values: true, false | default: false -->
Configure in-app interval

Configure the interval between two in-app messages in seconds. The default value is 60 seconds (1 minute).

<meta-data
    android:name="com.blueshift.config.IN_APP_INTERVAL"
    android:value="300" /> <!-- Supported values: time in seconds | default: 60 (1 minute) -->
Manual trigger

The in-app manual trigger is disabled by default. To change it, use the following configuration.

<meta-data
    android:name="com.blueshift.config.ENABLE_IN_APP_MANUAL_TRIGGER"
    android:value="true" /> <!-- Supported values: true, false | default: false -->
Background fetch

The in-app background fetch is enabled by default. To change it, use the following configuration.

<meta-data
    android:name="com.blueshift.config.ENABLE_IN_APP_BACKGROUND_FETCH"
    android:value="true" /> <!-- Supported values: true, false | default: true -->

Mobile Inbox

As Mobile inbox stores the in-app notifications for later use, you need to enable and set up the in-app notifications first. Once that is done, you can enable the mobile inbox. The mobile inbox is disabled by default. To enable it, use the following configuration.

<meta-data
            android:name="com.blueshift.config.ENABLE_INBOX"
            android:value="true" />

Batch interval

The plugin supports sending events in realtime and in batches of 100. Configure the time interval between batch events (in seconds) as follows. For more information, see Batched Events Time Interval.

<meta-data
    android:name="com.blueshift.config.BATCH_INTERVAL"
    android:value="3600" /> <!-- Supported values: time in seconds | default: 1800 (30 minute) -->

Push Notifications

Push notifications are enabled by default. To disable the same, use the following configuration.

Note: This is a client side setting. An app update is required to change this.

<meta-data
    android:name="com.blueshift.config.ENABLE_PUSH"
    android:value="true" /> <!-- Supported values: true, false | default: true -->
Notification Small Icon and Notification Big Icon

The small icon on the notification and the big icon on the notification can be configured as shown in the following example.

<!--Notification Small Icon-->
<meta-data
    android:name="com.blueshift.config.NOTIFICATION_ICON_SMALL"
    android:resource="@mipmap/ic_launcher" />

<!--Notification Big Icon-->
<meta-data
    android:name="com.blueshift.config.NOTIFICATION_ICON_BIG"
    android:resource="@mipmap/ic_launcher" />
Notification Color

The color of the notification can be customised as per the app's theme. To add a new colour to the app, add it as a resource inside the android project here - res/values/colors.xml.

<color name="notificationColor">#ff32ff</color>

After you add the color, use the reference as shown in the following example.

<meta-data
    android:name="com.blueshift.config.NOTIFICATION_ICON_COLOR"
    android:resource="@color/notificationColor" />
Notification Channel

For Android 8 and above, a notification channel is required to show notifications. Blueshift has a default channel for push notifications. To customise the channel based on the app requirements, update the Notification Channel ID, Notification Channel Name, and the Notification Channel Description as shown in the following example.

<!--Notification Channel ID-->
<meta-data
    android:name="com.blueshift.config.NOTIFICATION_CHANNEL_ID"
    android:value="DefaultChannelId" />

<!--Notification Channel Name-->
<meta-data
    android:name="com.blueshift.config.NOTIFICATION_CHANNEL_NAME"
    android:value="DefaultChannelName" />

<!--Notification Channel Description-->
<meta-data
    android:name="com.blueshift.config.NOTIFICATION_CHANNEL_DESCRIPTION"
    android:value="DefaultChannelDescription" />
Push App Links

By default the SDK opens the app and delivers the deep link when someone clicks on the push notification. To change this, use the following configuration.

When enabled, the SDK will try to open the deep link based on App Link configuration. All App Links will open the app and rest of the links will open in the default browser.

<meta-data
    android:name="com.blueshift.config.ENABLE_PUSH_APP_LINKS"
    android:value="true" /> <!-- Supported values: true, false | default: false -->

App Icon

The app icon is used as backup when notification icons are provided. If not provided, the SDK will try to get this value automatically.

<meta-data
    android:name="com.blueshift.config.APP_ICON"
    android:resource="@mipmap/ic_launcher" />

Device ID source

The SDK uses a combination of Firebase Installation ID and package name as the default Device ID. To change this, use the following setting.

Supported values are, INSTANCE_ID, INSTANCE_ID_PKG_NAME, GUID, and CUSTOM.

<meta-data
    android:name="com.blueshift.config.DEVICE_ID_SOURCE"
    android:value="INSTANCE_ID" />
Custom device ID

When the Device ID source is CUSTOM , use the following configuration to supply the custom Device ID.

<meta-data
    android:name="com.blueshift.config.CUSTOM_DEVICE_ID"
    android:value="YOUR_CUSTOM_DEVICE_ID" />

Handle Job ID conflict

If the job ID of Blueshift's job scheduler conflicts with your app's job scheduler's job ID, change it as shown in the following example:

<meta-data
    android:name="com.blueshift.config.JOB_ID_BULK_EVENT"
    android:value="911" />

<meta-data
    android:name="com.blueshift.config.JOB_ID_NETWORK_CHANGE"
    android:value="911" />

Deep link configurations

If you are using the Blueshift Deep Links feature, ensure that you set up the prerequisites. Then add the following intent filter to MainActivity inside your AndroidManifest file and replace links.clientdomain.com with your email domain.

To receive the URL on Flutter code, see Deep Links Event Listener.

<intent-filter>
  <action android:name="android.intent.action.VIEW" />

  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />

  <data
        android:host="links.clientdomain.com"
        android:pathPrefix="/track"
        android:scheme="https" />

  <data
        android:host="links.clientdomain.com"
        android:pathPrefix="/z"
        android:scheme="https" />
</intent-filter>