intercom_flutter
Flutter wrapper for Intercom Android, iOS, and Web projects.
- Uses Intercom Android SDK Version
18.13.0. - The minimum Android SDK
minSdkrequired is 23. - The compile Android SDK
compileSdkrequired is 36. - Uses Intercom iOS SDK Version
19.11.0. - The minimum iOS target version required is 15.
- The Xcode version required is 15.
Usage
Import package:intercom_flutter/intercom_flutter.dart and use the methods in Intercom class.
Example:
import 'package:flutter/material.dart';
import 'package:intercom_flutter/intercom_flutter.dart';
void main() async {
// initialize the flutter binding.
WidgetsFlutterBinding.ensureInitialized();
// initialize the Intercom.
// make sure to add keys from your Intercom workspace.
// don't forget to set up the custom application class on Android side.
await Intercom.instance.initialize('appIdHere', iosApiKey: 'iosKeyHere', androidApiKey: 'androidKeyHere');
runApp(App());
}
class App extends StatelessWidget {
@override
Widget build(BuildContext context) {
return FlatButton(
child: Text('Open Intercom'),
onPressed: () async {
// messenger will load the messages only if the user is registered in Intercom.
// either identified or unidentified.
await Intercom.instance.displayMessenger();
},
);
}
}
See Intercom Android and iOS package documentation for more information.
Android
Make sure that your app's MainActivity extends FlutterFragmentActivity (you can check the example).
Permissions:
<uses-permission android:name="android.permission.INTERNET"/>
Optional permissions:
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
Enable AndroidX + Jetifier support in your android/gradle.properties file (see example app):
android.useAndroidX=true
android.enableJetifier=true
According to the documentation, Intercom must be initialized in the Application onCreate. So follow the below steps to achieve the same:
- Setup custom application class if you don't have any.
- Create a custom
android.app.Applicationclass namedMyApp. - Add an
onCreate()override. The class should look like this:
import android.app.Application class MyApp: Application() { override fun onCreate() { super.onCreate() } }- Open your
AndroidManifest.xmland find theapplicationtag. In it, add anandroid:nameattribute, and set the value to your class' name, prefixed by a dot (.).
<application android:name=".MyApp" > - Create a custom
- Now initialize the Intercom SDK inside the
onCreate()of custom application class according to the following:
import android.app.Application
import io.maido.intercom.IntercomFlutterPlugin
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
// Add this line with your keys
IntercomFlutterPlugin.initSdk(this, appId = "appId", androidApiKey = "androidApiKey")
}
}
iOS
Make sure that you have a NSPhotoLibraryUsageDescription entry in your Info.plist.
Location permission in Mobile Carousels
Intercom does not request location permission itself, so your app does not need a location purpose string just because it includes Intercom.
Mobile Carousel screens that ask for location permission are only shown once your app sets a provider with setLocationPermissionProvider.
Add NSLocationWhenInUseUsageDescription to your Info.plist, and NSLocationAlwaysAndWhenInUseUsageDescription if you want Intercom to ask for "Always" access.
Then implement the provider with your own permission handling. The example below uses permission_handler. Follow its iOS setup and enable PERMISSION_LOCATION, which it needs to request "Always" access:
Future<IntercomLocationAuthorizationStatus> locationStatus() async {
if (await Permission.locationAlways.isGranted) {
return IntercomLocationAuthorizationStatus.authorizedAlways;
}
switch (await Permission.locationWhenInUse.status) {
case PermissionStatus.granted:
return IntercomLocationAuthorizationStatus.authorizedWhenInUse;
case PermissionStatus.restricted:
return IntercomLocationAuthorizationStatus.restricted;
case PermissionStatus.permanentlyDenied:
return IntercomLocationAuthorizationStatus.denied;
default:
// On iOS, permission_handler reports `denied` when the user has not been
// asked yet. `permanentlyDenied` is the actual denial.
return IntercomLocationAuthorizationStatus.notDetermined;
}
}
Future<void> reportLocationStatus() async {
await Intercom.instance.updateLocationAuthorizationStatus(await locationStatus());
}
await Intercom.instance.setLocationPermissionProvider(
IntercomLocationPermissionProvider(
authorizationStatus: await locationStatus(),
// Report in `finally` so Intercom gets an answer even if a request throws.
requestWhenInUsePermission: () async {
try {
await Permission.locationWhenInUse.request();
} finally {
await reportLocationStatus();
}
},
requestAlwaysPermission: () async {
try {
// permission_handler only asks for "Always" once "When In Use" is granted.
if (!await Permission.locationWhenInUse.isGranted) {
await Permission.locationWhenInUse.request();
}
if (await Permission.locationWhenInUse.isGranted) {
await Permission.locationAlways.request();
}
} finally {
await reportLocationStatus();
}
},
),
);
Call updateLocationAuthorizationStatus after every request, even if the status did not change, and when the user changes the permission in Settings.
setLocationPermissionProvider, updateLocationAuthorizationStatus and removeLocationPermissionProvider have no effect on Android. They are not supported on web and throw there, so guard the calls with !kIsWeb if your app also runs on web.
Push notifications setup
This plugin works in combination with the firebase_messaging plugin to receive Push Notifications. To set this up:
- First, implement
firebase_messaging - Then, add the Firebase server key to Intercom, as described here (you can skip 1 and 2 as you have probably done them while configuring
firebase_messaging) - Follow the steps as described here to enable push notification in iOS.
- Starting from Android 13 you may need to ask for notification permissions (as of version 13
firebase_messagingshould support that) - Ask FirebaseMessaging for the token that we need to send to Intercom, and give it to Intercom (so Intercom can send push messages to the correct device), please note that in order to receive push notifications in your iOS app, you have to send the APNS token to Intercom. The example below uses
firebase_messagingto get either the FCM or APNS token based on the platform:
final firebaseMessaging = FirebaseMessaging.instance;
final intercomToken = Platform.isIOS ? await firebaseMessaging.getAPNSToken() : await firebaseMessaging.getToken();
Intercom.instance.sendTokenToIntercom(intercomToken);
Now, if either Firebase direct (e.g. by your own backend server) or Intercom sends you a message, it will be delivered to your app.
Web
You don't need to do any extra steps for the web. Intercom script will be automatically injected. But you can pre-define some Intercom settings, if you want (optional).
<script>
window.intercomSettings = {
hide_default_launcher: true, // hide the default launcher
};
</script>
Following functions are not yet supported on Web:
unreadConversationCountsetInAppMessagesVisibilitysendTokenToIntercomisIntercomPushhandlePushdisplayCarouseldisplayHelpCenterCollectionsgetWindowDidHideStreamsuppressProactiveContentsetUserJwtProviderremoveUserJwtProvidersetLocationPermissionProviderupdateLocationAuthorizationStatusremoveLocationPermissionProvider
Using Intercom keys with --dart-define
Use --dart-define variables to avoid hardcoding Intercom keys.
Pass the Intercom keys with flutter run or flutter build command using --dart-define.
flutter run --dart-define="INTERCOM_APP_ID=appID" --dart-define="INTERCOM_ANDROID_KEY=androidKey" --dart-define="INTERCOM_IOS_KEY=iosKey"
Note: You can also use --dart-define-from-file which is introduced in Flutter 3.7.
Reading keys in Dart side and initialize the SDK.
String appId = String.fromEnvironment("INTERCOM_APP_ID", "");
String androidKey = String.fromEnvironment("INTERCOM_ANDROID_KEY", "");
String iOSKey = String.fromEnvironment("INTERCOM_IOS_KEY", "");
Intercom.instance.initialize(appId, iosApiKey: iOSKey, androidApiKey: androidKey);
Reading keys in Android native side and initialize the SDK.
- Add the following code to
build.gradle.
def dartEnvironmentVariables = []
if (project.hasProperty('dart-defines')) {
dartEnvironmentVariables = project.property('dart-defines')
.split(',')
.collectEntries { entry ->
def pair = new String(entry.decodeBase64(), 'UTF-8').split('=')
[(pair.first()): pair.last()]
}
}
- Place
dartEnvironmentVariablesinside the build config
defaultConfig {
...
buildConfigField 'String', 'INTERCOM_APP_ID', "\"${dartEnvironmentVariables.INTERCOM_APP_ID}\""
buildConfigField 'String', 'INTERCOM_ANDROID_KEY', "\"${dartEnvironmentVariables.INTERCOM_ANDROID_KEY}\""
}
- Read the build config fields
import android.app.Application
import android.os.Build
import io.maido.intercom.IntercomFlutterPlugin
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
// Add this line with your keys
IntercomFlutterPlugin.initSdk(this,
appId = BuildConfig.INTERCOM_APP_ID,
androidApiKey = BuildConfig.INTERCOM_ANDROID_KEY)
}
}
Support
If you find this package helpful, you can support the development by: