Migrating from v1

Batch Flutter Plugin v2 is a major release based on natives SDK v2, which introduces breaking changes from 1.x. This guide describes how to update your application when using a previous version.

Upgrading the SDK version

To upgrade from v1 to v2 update your pubspec.yaml file as following:

dependencies:
  batch_flutter: ^2.0.0

and then run:

flutter pub upgrade

⚠️ Since this version is based on the Batch SDK 2.0, its now requires an Android minSdk level of 21 or higher and iOS 13.0 or higher.

If your application support lower Android versions, you will have to update it:

android {
  ...
  defaultConfig {
    ...
    minSdk = 21
  }
}

On iOS, update your target iOS minimum deployments version from Xcode if necessary.

Core migration

Android - Push Providers

This version also removed support for old push providers (Google Cloud Messaging and FCM Instance ID). Batch now only support for FCM's Token APIs. Overriding the Sender ID is no longer possible in any way.

You have to use firebase-messaging 22.0.0 or higher. We highly recommend to use the latest version when possible.

If you are using the flutter plugin ensure it's based on the fcm messaging version 22 or higher. If you did a native integration of firebase, add/update the following to your build.gradle if not already present:

implementation "com.google.firebase:firebase-messaging:22.0.0"

// or if you are using firebase-bom
// implementation platform('com.google.firebase:firebase-bom:28.0.0')
// implementation "com.google.firebase:firebase-messaging"

Advertising Identifier

Batch Flutter 1.4 had removed automatic collection of AAID (Android Advertising Identifier) and IDFA (Identifier For Advertisers). This version has totally drop the support of the AAID and IDFA and you can no longer set an advertising id to Batch since all related APIs have been removed.

Advanced Information

The Batch Flutter Plugin v1 allowed you to disable advanced information generally with setCanUseAdvancedDeviceInformation(false) and setUseAdvancedDeviceInformation(false). This has been removed and replaced with a more fine-tuning control of what you want to enable directly in your dart code with:

Batch.instance.setAutomaticDataCollection({
  "geoIP": true, // Enable GeoIP resolution on server side
  "deviceBrand": true, // Enable automatic collection of the device brand information (Android only)
  "deviceModel": true, // Enable automatic collection of the device model information
});

Note: All data configurable with this API are now disabled by default and should be enabled if you want to use it.

For more information, please visit our automatic data collection guide.

Deprecated APIs

All deprecated APIs in the Flutter Plugin v1 have been removed and some others have been renamed/reworked. To see in details the differences, please visit our changelog.

Project migration

This version follows Batch's pivot to being an omnichannel platform. It allows you to collect data for your Projects and Profiles. If you are not familiar with these two concepts, please see this guide beforehand.

Profile Attributes

First of all, most of the user-related write APIs have been removed. Reading methods are still usable since we do not provide yet a way to get synced data for a Profile, but keep in mind that the data returned is only about your installation and not your Profile.

To interacts with our user-centered model, you should now use the BatchProfile module. Let's see a migration example.

If you were previously doing something like that:

BatchUser.instance.editor()
  .setIdentifier("john.doe")
  .setLanguage("en")
  .setRegion("US")
  .setEmail("john.doe@batch.com")
  .setEmailMarketingSubscriptionState(BatchEmailSubscriptionState.SUBSCRIBED)
  .setIntegerAttribute("age", 26)
  .removeAttribute("firstname")
  .addTag("actions", "has_bought")
  .removeTag("actions", "has_bought")
  .clearTagCollection("actions")
  .save();
}

You should now do :

BatchProfile.instance.identify("john.doe");
BatchProfile.instance.editor()
  .setLanguage("en")
  .setRegion("US")
  .setEmailAddress("john.doe@batch.com")
  .setEmailMarketingSubscription(BatchEmailSubscriptionState.SUBSCRIBED)
  .setIntegerAttribute("age", 26)
  .removeAttribute("firstname")
  .addToArray("actions", "has_bought") // or addToArray("actions", ["has_bought"])
  .removeFromArray("actions", "has_bought") // or removeFromArray("actions", ["has_bought"])
  .removeAttribute("actions")
  .save();
}

For more information, please see the following sections :

Profile Data migration

To make it easier to collect data to a Profile, Batch has added two automatic ways to migrate old installation's data on a Profile. So the first time a user will launch your application running on v2 :

He will be automatically identified (logged-in) if he had a Batch custom_user_id set on the local storage.
Its natives (language/region) and customs data will be automatically migrate to a Profile if your app is attached to a Project.

These migrations are enabled by default, but you may want to disable them, to do so, please visit our profile data migration guide

Event data

Batch flutter Plugin v2 introduced two new types of attribute that can be attached to an event : Array and Object.

What's change:

BatchEventData has be renamed into BatchEventAttributes
addTag API is no longer available, you should now use the $tags reserved key with the putStringList method.
Optional label parameter is no longer available and has been replaced by a $label reserved key under BatchEventAttributes.

Note: Limits are unchanged and still 200 chars max for $label and 10 items max for $tags .

So if you were previously doing something like:

BatchEventData eventData = new BatchEventData();

eventData.putBoolean("premium", true);
eventData.putString("id", "ab-123456");
eventData.addTag("sports");
eventData.addTag("squash");

BatchUser.instance.trackEvent(name: "read_article", label: "daily_digest", data: eventData);

You should now do:

BatchEventAttributes eventAttributes = new BatchEventAttributes();

eventAttributes.putBoolean("premium", true);
eventAttributes.putString("id", "ab-123456");
eventAttributes.putString("\$label", "daily_digest");
eventAttributes.putStringList("\$tags", ["sports", "squash"]);

BatchProfile.instance.trackEvent(name: "read_article", attributes: eventAttributes);

For more information, please visit our custom event guide.

To see in details what's precisely changed since V1 please consult our changelog or visit the APIs Reference.

Documentation > Flutter > Advanced