engage

Description:

engage

Engage Flutter Plugin #
Engage is all you need to deliver personalized customer messaging and marketing automation through email, SMS and in-app messaging. This flutter plugin makes it easy to identify customers, sync customer data (attributes, events and device tokens) to the Engage dashboard and send in-app messages to the device.
Features #

Identify customers
Update customer attributes
Track customer events
Track device token

Getting started #

Create an Engage account and set up an account to get your public API key.
Learn about connecting user data to Engage.
Add the Engage Flutter Plugin to your project.
flutter pub add engage

Initializing the plugin #
Import package:engage/engage.dart and initialize the plugin.
// ...
import 'package:engage/engage.dart';

void main() async {
// Run this before you initialize the Engage plugin
WidgetsFlutterBinding.ensureInitialized();
// Initialize the plugin
await Engage.init('publicKey');
// ...
runApp(const MyApp());
}
copied to clipboard
Identifying users and updating attributes #
The plugin uses your user's unique identifier (this is mostly the id field of the users' table) to update the user's attributes, track events and perform other user-related actions. Here is the code to update a set of user attributes for example:
Engage.addAttributes('uniqueUserId', {
'plan': 'Pro'
});
copied to clipboard
addAttributes adds the attribute to the user profile if it doesn't exist and updates it if it does already. You will want to add that to parts of your application where user attributes are updated. For example, to add a last_login date attribute, you need to call addAttributes on successful login within your code.
void logIn() async {
// ...
Engage.addAttributes('user_id_1234', {
'last_login': DateTime.now()
});
}
copied to clipboard
To help you correctly "identify" the user beyond just the ID, we recommend you track a few additional user attributes. This can be anything depending on what properties you request from users on your product. Example: location, gender, plan. These are some we have standardized within Engage: first_name, last_name, email, number (user's phone number), tz (user's timezone). We call them standard attributes. However, remember you can track other attributes outside the standard ones.
You only need to track an attribute once, unless they change and you use addAttributes to update them. We call this "identifying" the user.
// This maps the user ID user_id_1234 to Opeyemi O.
Engage.identify('user_id_1234', {
'first_name': 'Opeyemi',
'last_name': 'O.'
});
copied to clipboard
We recommend you do this in two places:

After login - this helps identify old users that have sent data to Engage but are yet to be identified.
On signup - this helps identify new users.

By default, Engage sets the signup date of a newly identified user to the current timestamp. This can be changed with the created_at parameter.
Engage.identify('user_id_1234', {
'first_name': 'Opeyemi',
'last_name': 'O.',
'created_at': '2021-09-14'
});
copied to clipboard
Anonymous ID #
Sometimes, you want to track user events before you identify them. For example, a user may download your app and explore some of the available features before they sign up and are assigned a unique ID. We call this an anonymous user. You can use any random ID (we call this an anonymous ID) to track events for the anonymous user and merge it with the actual user when identified.
If we need to track stuff before the user is identified:
// import 'package:uuid/uuid.dart';

// Generate a random unique ID
var anonId = uuid.v4()
Engage.trackEvents(anonId, 'Launched app');
// ...Somewhere else, using same id
Engage.trackEvents(anonId, 'Opened gallery');
copied to clipboard
Once user is identified:
void logIn() async {
// ...
// User user = User.fromJson(result);
// Merge the anonymous id to the identified user
Engage.merge(anonId, user.id);
}
copied to clipboard
Tracking events #
To track user events, use trackEvents. Here it is in the most basic form:
Engage.trackEvents('user_id_1234', 'Sign up');
copied to clipboard
Events can have a value:
Engage.trackEvents('user_id_1234', 'Paid', 35);
Engage.trackEvents('user_id_1234', 'Clicked', 'pro_course_3');
copied to clipboard
Or properties:
Engage.trackEvents('user_id_1234', 'Transfer', {
'to': 'user_id_6789',
'amount': 345.50,
'deliver_on': DateTime.now()
});
copied to clipboard
By default, the events are stamped by your current timestamp. To use a custom date, add a date argument.
Engage.trackEvents('user_id_1234', 'Sign up', DateTime.now());
copied to clipboard
Push notifications and Setting device token #
Finally, to use Engage for push notifications, we require you add your user's device token to their profile. To send this to Engage, get the token and call setDeviceToken. (You need to have installed and configured Firebase to get the device token). We recommend you call setDeviceToken at every application launch so that if for any unlikely reason the device token has changed, it would be updated on Engage
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Engage.init('publicKey');
await Firebase.initializeApp(
options: DefaultFirebaseOptions.currentPlatform
);
FirebaseMessaging.instance
.getToken()
.then((String? token) {
if (token != null) {
Engage.setDeviceToken('user_id_1334', token);
}
});
runApp(const MyApp());
}
copied to clipboard
To remove the device token from the user's profile, use logout. You should do this when the user logs out of your application so they do not continue to get push notifications when they are not logged in.
Engage.logout()
copied to clipboard
The logout method without any parameters assumes that setDeviceToken has been called earlier. If not, you can pass the user's ID and device token to the method.
Engage.logout('user_id_1334', token)
copied to clipboard
Managing Accounts #
The plugin has some additional methods to help you manage Accounts.
They are:

addToAccount: Add the Customer to an Account
removeFromAccount: Remove the Customer from an Account
changeAccountRole: Change the Customer's role in the Account
convertToAccount: Convert the Customer profile to an Account
convertToCustomer: convert the Account profile to a Customer