Install and set up Flutter plugin

Installing Blueshift's Flutter plugin for the Blueshift iOS and Android SDK is pretty straightforward. Follow the step-by-step instructions provided.

Install the plugin

Run the following command to install the Flutter plugin.

flutter pub add blueshift_plugin

Android and iOS Integration

To integrate the Blueshift SDK for Android and iOS, see the following topics in the documentation:

Use the plugin

Import the Blueshift plugin to your Dart code.

import 'package:blueshift_plugin/blueshift_plugin.dart';

After you import the plugin, you can call the Blueshift methods.

// Call Blueshift functions
Blueshift.setUserInfoEmailId("[email protected]");
Blueshift.identifyWithDetails({
"user_type":"premium",
"country": "US",
"timezone":"PST"
});

For more information about the features and methods supported by the plugin and how to use them, see the information about Blueshift Dart methods.

Set user information

Using the plugin, you can set the information for the logged-in user in the Blueshift SDK. The SDK adds this user data to each event and sends it to the Blueshift server. This user data can be saved when the user logs in to the app and must be removed when the user logs out of the app.

In order to associate the events with the correct user, three primary identifiers are used to identify a user uniquely.

DeviceID - This is auto-generated by SDK and sent to the Blueshift server as the device_id attribute in every event.
EmailId - Email ID must be set whenever it changes as mentioned in the following code snippet and this is sent to the Blueshift server as part of every event.
CustomerId - Customer ID must be set whenever it changes as mentioned in the following code snippet and this is sent to the Blueshift server as part of every event.

Ensure that you fire an identify event after making changes to the user data so that the changes are reflected on the Blueshift server.

// Set data on successful login
Blueshift.setUserInfoEmailId("[email protected]");
Blueshift.setUserInfoCustomerId("cust123456");
// Set other user info as below. This info will be used for creating
// segments or running personalized campaigns
Blueshift.setUserInfoFirstName("John");
Blueshift.setUserInfoLastName("Cartor");
// Add any extra information you would like to capture.
Blueshift.setUserInfoExtras({
"profession":"software engineer",
"premium_user":true
});

When the user logs out, clear the cached information.

Blueshift.removeUserInfo();

Identify event

The Identify event is used to update the data for the user profile on the Blueshift server. Whenever you change any user data in the Blueshift SDK, we recommend you fire an identify event to reflect those changes on the Blueshift server. This ensures that we can continue to attribute the events to the correct user and generate recommendations for the user in case the device_id is reset due to the uninstalling of the app by the user.

// Identify event with custom (optional) data
Blueshift.identifyWithDetails({
"country": "US",
"timezone":"PST"
});

Custom Event

Use the following method to track custom events with custom data in your app.

Blueshift.trackCustomEvent("name_of_event", {}, false);

Request push notification permission

iOS

We highly recommend that you request permission for iOS push notifications using the Blueshift Plugin. Blueshift uses special categories for its rich push notifications like custom action buttons and carousel push notifications. The Blueshift SDK takes care of handling and registering the special categories used while requesting the push notification permission. Ensure that you do not request push notification permission using Firebase for iOS and instead request it using the Blueshift plugin.

The Blueshift iOS SDK requests push notification permission automatically when a user launches the app. If you don't want the push notification permission request to be displayed immediately after the app is launched, you can customize it to be displayed after the user signs up/signs in. To delay the push notification permission request, set config.enablePushNotification as false in your Xcode project when you initialize the Blueshift Plugin.

// Disable push notifications flag in the SDK configuration
// to delay the Push notification permission dialog
config.enablePushNotification = false

// Disable push notifications flag in the SDK configuration
// to delay the Push notification permission dialog
[config setEnablePushNotification:NO];

Invoke the following plugin method from your Flutter code when you want to request for push notification permission and show the push notification dialog to the user.

// Register for remote notifications using SDK.
// Calling this method will show push permission dialogue to the user.
Blueshift.requestPushNotificationPermission();

Android

Android 13 and above users must explicitly consent to receive push notifications from your app before you can send notifications to them. The following method requests for permission from the user. However if your app does not target Android 13, the OS will ask for the notification permission when the app is launched for the first time.

// This will bring up the OS's notifictaion permission dialog
// if you deny the permission two times, this will take you to
// settings page for enabling notifications
Blueshift.requestPushNotificationPermission();

In-App Notifications

Enable the in-app notifications from the SDK and register all the screens to receive in-app notifications as mentioned in the Android and iOS set-up documentation. After completing this setup, in-app notifications can be displayed on any screen when it is available to display.

Opt-in/Opt-out for notifications

Use the Blueshift plugin options to opt-in or opt-out of in-app messages and push notifications that we send from the Blueshift platform. When a user logs out of the app, opt them out of messaging. Similarly, when
a user logs in, opt them in for messaging.

Push notifications

Use the Blueshift plugin to change the opt-in status for push notifications. Once modified, you
must fire an identify event to Blueshift to update the customer profile.

// set the preference for push notification
Blueshift.setEnablePush(false);
// fire identify event
Blueshift.identifyWithDetails({});

In-app Messages

Use the Blueshift plugin to change the opt-in status for in-app messages. Once modified, you
must fire an identify event to Blueshift to update the customer profile.

// set the preference for in-app message
Blueshift.setEnableInApp(false);
// fire identify event
Blueshift.identifyWithDetails({});

Mobile Inbox

A mobile inbox contains in-app messages that are delivered directly to the inbox in a non-intrusive manner or displayed within the app while also being delivered to the inbox. Users will continue to see these messages in their inbox, until the messages expire or until they delete them after reading.

Blueshift's SDK automatically synchronizes the mobile inbox across all devices on which a user has installed your app and logged in, ensuring the message status (read/unread) is consistent.

The Blueshift Flutter Plugin offers a default user interface for the mobile inbox, which you can customize to match your brand's style and colors.

To save in-app messages to an inbox, your app must utilize Blueshift's Flutter Plugin version 1.1.0 or above. Additionally, you need to enable the mobile inbox feature in the Android and iOS configurations.

The Inbox is provided as a widget and allows for further customization. You can create an empty screen and add the Blueshift Inbox widget to it, and the Plugin will handle the rest.

The below code shows how you can use the Blueshift Inbox widget on a screen

class InboxPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        primarySwatch: Colors.green,
      ),
      home: Scaffold(
        appBar: AppBar(
          title: const Text('My Inbox'),
          leading: IconButton(
            icon: const Icon(Icons.arrow_back_ios_new),
            onPressed: () {
              Navigator.of(context).pop();
            },
          ),
        ),
        body: const BlueshiftInbox(),
      ),
    );
  }
}

The Blueshift Inbox screen offers the flexibility to customize various fields according to your requirements. The following example demonstrates how you can personalize the widget by passing specific parameters.

BlueshiftInbox(
    titleTextStyle: Theme.of(context).textTheme.bodyLarge,
    detailsTextStyle: Theme.of(context).textTheme.bodyMedium,
    dateTextStyle: Theme.of(context).textTheme.bodySmall,
    unreadIndicatorColor: Colors.red,
    dividerColor: Colors.blueGrey,
    dateFormatter: (date) => date.toIso8601String(),
    placeholder: const Text("Inbox is empty!"),
    loadingIndicator: const Icon(Icons.hourglass_top),
    inboxItem: (msg) => Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
        Text(msg.title.trim()),
        Text(msg.details.trim()),
        Text(msg.imageUrl),
      ],
    ),
  ),

You have the ability to customize the following elements:

titleTextStyle: Specify the text style for the inbox message title text.
detailsTextStyle: Specify the text style for the inbox message details text.
dateTextStyle: Specify the text style for the inbox message date text.
unreadIndicatorColor: Specify the color for the indicator of unread messages.
dividerColor: Specify the color of the row dividers.
dateFormatter: Specify a date formatting function to change the default date format in the list.
placeholder: Specify a placeholder widget to display when the inbox list is empty.
loadingIndicator: Specify the loading indicator to appear during asynchronous in-app loading (iOS only).
inboxItem: Customize the look and feel of the inbox list item according to your brand's theme.

These options provide you with the flexibility to tailor the Blueshift Inbox screen to your exact preferences and requirements.

Deep link handling

Deep links for the Inbox-originated in-app notifications are sent to the same event listener as push and in-app. You can see more information here.

Deep links Event Listener

The Blueshift plugin takes care of delivering the deep link added inside the Push and in-app notifications to Flutter once the user interacts with the notification.

The Blueshift plugin also takes care of handling email deep links. Email deep links are basically App links for Android and Universal links for iOS. To enable the App links and Universal links you must set them up as mentioned in the Android and iOS integration documentation.

The Blueshift plugin delivers the deep link to Flutter using the event stream. You must add a listener in your project to receive the deep link.

Blueshift.getInstance.onDeepLinkReceived.listen((String deeplink) {
print("Blueshift deep link received: " + deeplink);
});

For the Android OS, when the app is brought to the foreground state from the background state, use the getInitialUrl method to get the original URL that caused the app to start.

String url = await Blueshift.getInitialUrl;
// use the url to navigate the user to the proper screen/widget

iOS Push notification payload Listener

The Blueshift plugin v1.1.1 takes care of delivering the iOS push notification payload to Flutter when the user clicks on the iOS push notification. This listener is only for iOS, while the push notification payload for Android is by default handled and delivered to Flutter by the Firebase.

For automatic integration, the Blueshift plugin takes care of sharing the payload automatically. For manual integration, you will have to send the push payload to the plugin explicitly from the userNotificationCenter didReceive response method as mentioned in this code snippet.

The Blueshift plugin delivers the push payload to Flutter using the event stream. You must add a listener to your project to receive the iOS push notification payload.

Blueshift.getInstance.oniOSPushNotificationClick.listen((Object payload) {
     //process the payload
      print(payload);
});

Sample application

You can refer to this Blueshift sample application code to check the SDK integration.