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);

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({});

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.

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

Sample application

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