SDK integration
This guide assumes that you've already followed the iOS and Android prerequisites.
Installation
batch_flutter requires Flutter 2.0 and Dart 2.15 or higher. Flutter 3 is supported.
Setting up the plugin
Batch requires that the native projects are modified to configure the plugin.
This is required as Android and iOS might kill your applications process only to launch it at a later date to handle background tasks, such as displaying a notification. Integrating natively allows Batch to work even if the Flutter engine is not started.
Before proceeding, you will need your SDK API key. In the following documentation samples YOUR_BATCH_API_KEY
should be replaced with your Batch SDK API key. You'll find it in Settings → General.
You should not use the same API key for iOS and Android.
Android
Adding Firebase Cloud Messaging
Batch requires Firebase Cloud Messaging (FCM) for push to be enabled. It can be added using a Flutter plugin, or natively in the Android project by following Firebase's native FCM documentation.
Adding Huawei Push (Optional)
Batch supports notifications using Huawei Mobile Services (HMS) for devices that don't support Play Services. If you require this, please follow the native Android Huawei documentation.
Setting up a custom application class
If you already have a custom android.app.Application
subclass registered, you can skip this step.
Open your project's Android folder in Android Studio.
First, create a new class that subclasses android.app.Application
. It can be named however you want, but we will call it ExampleApplication
for the sake of this example.
Place it in your root package.
Then, add an onCreate()
override. The class should look like this:
Finally, open your AndroidManifest.xml
and find the application
tag.
In it, add an android:name
attribute, and set the value to your class' name, prefixed by a dot (.
).
Enabling the plugin
In your Application
subclass' onCreate()
method, call BatchFlutterPlugin.setup(this)
.
Example:
iOS
Run flutter build ios --no-codesign
after adding the plugin to your pubspec
to initialize the native dependency.
Minimum iOS version
Default iOS Flutter projects can run on iOS 12.0 or higher. However, Batch requires iOS 13.
This can lead to the following error when flutter build ios
is ran:
To fix this, you need to make your application require iOS 13 or higher:
Open
ios/Podfile
and addplatform :ios, '13.0'
at the beginning of the file. Make sure you do not have any other line starting withplatform :ios
. If your app should require an higher iOS version, replace13.0
with your minimum OS version.Update the iOS deployment target in the Xcode project. This can be done later, as this will only produce a warning for now, but it must be fixed before submitting to the store.
Enable Push Capabilities
Open the xcworkspace
in the ios/
folder. In the project window:
Select your project in the sidebar
Go to
Signing & Capabilities
Press on
+ Capability
Add
Push Notifications
Modifying the AppDelegate
Open AppDelegate.swift
(or .m if you have an Objective-C plugin). In it:
Import the
Batch
andbatch_flutter
modules.Inside of
didFinishLaunchingWithOptions
:Add
BatchUNUserNotificationCenterDelegate.registerAsDelegate()
if you do not already have a customUNUserNotificationCenterDelegate
. If you do, please follow this documentation.Call
BatchFlutterPlugin.setup()
.Call
BatchPush.refreshToken()
.
Here is an example Swift implementation of the AppDelegate:
Rich notifications
Rich notifications require setting up a Notification Service Extension. Please follow the native Rich notifications setup documentation.
Configuring the plugin
As shown by the examples earlier, the plugin needs to be configured with the API Key. There are two ways to do so:
Code configuration, in your
Application
subclass on Android,AppDelegate
on iOS.Static configuration, using
AndroidManifest.xml
on Android,Info.plist
on iOS.
Not configuring an API key will result in any batch_flutter
dart method call to throw an exception
Android
Code based configuration should be done in your Application
subclass, right before BatchFlutterPlugin.setup
: configuration changes made after calling this method will not be applied.
Call BatchFlutterPlugin.getConfiguration(this)
to get the configuration object, which can be used as a builder. Changes will automatically be saved.
Example:
The following methods are available:
setAPIKey
: Batch API Key.setInitialDoNotDisturbState
: Enables Do Not Disturb by default. Default: false.setProfileCustomIdMigrationEnabled
: Enables profile custom id migration. See profile data migration for more info. Default: true.setProfileCustomDataMigrationEnabled
: Enables profile custom data migration. See profile data migration for more info. Default: true.
Manifest configuration automatically looks for the following keys:
com.batch.flutter.apikey
: Batch API Key.com.batch.flutter.do_not_disturb_initial_state
: Enables Do Not Disturb by default. Default: false.com.batch.flutter.profile_custom_id_migration_enabled
: Enables profile custom id migration. See profile data migration for more info. Default: true.com.batch.flutter.profile_custom_data_migration_enabled
: Enables profile custom data migration. See profile data migration for more info. Default: true.
Boolean keys should be set as "true"
/"false"
.
iOS
Code based configuration should be done in your application delegate class, right before BatchFlutterPlugin.setup
: configuration changes made after calling this method will not be applied.
Call BatchFlutterPlugin.configuration
to get the configuration object. Changes will automatically be saved.
Example:
The following properties can be used to configure the plugin:
APIKey
(string): Batch API Key.initialDoNotDisturbState
(boolean): Enables Do Not Disturb by default. Default: false.profileCustomIdMigrationEnabled
(boolean): Enables profile custom id migration. See profile data migration for more info. Default: true.profileCustomDataMigrationEnabled
(boolean): Enables profile custom data migration. See profile data migration for more info. Default: true.
Info.plist
-based configuration looks for the following keys:
BatchFlutterAPIKey
(string): Batch API Key.BatchFlutterDoNotDisturbInitialState
(boolean): Enables Do Not Disturb by default. Default: false.BatchFlutterProfileCustomIdMigrationEnabled
(boolean): Enables profile custom id migration. See profile data migration for more info. Default: true.BatchFlutterProfileCustomDataMigrationEnabled
(boolean): Enables profile custom data migration. See profile data migration for more info. Default: true.
Asking for the permission to display notifications
On iOS and Android (13+), your app needs to request for the permission to display notifications. This is done on the Flutter side of the app, as it can be asked as a step of an onboarding. Once the user consents, the push token will automatically be fetched by the SDK.
This can be done using BatchPush.instance.requestNotificationAuthorization()
:
Your first notification
You can now build and launch your application! Batch should automatically start. We can now display a test push notification.
1. Obtaining Your Device Token on iOS
You can find your device's token using the debug tool or locating the token Batch posts to the Xcode console:
Based on your Provisioning Profile, the token shown in the console will be Development ("Sandbox/Development") or Production ("Production").
If you're not running your Flutter application using Xcode, you can find the logs in macOS' Console app. Filter using the com.batch.ios
subsystem.

2. Obtaining Your Device Token on Android
You can find your device's token using the debug tool or locating the token Batch posts to the logcat (see here to know more):
3. Sending A Test Push
You can send test notifications to your device with a push token. In the push notification creation form, click the ⚙️ and copy your push token in the corresponding field. Hit "Send a test".

What's next
Congratulations on finishing the integration of Batch Push!
Here are a couple of extra steps you can take before releasing your app:
Small icon / Accent color: Make sure the small icon you are using is opaque white. We also recommend you use an accent color. You will find more information here.
Analytics: Add an event dispatcher to automatically track your campaigns in your third-party analytics tool.
Last updated
Was this helpful?