MirrorFly Lightweight Flutter Chat & Video Calls Plugin Docs

Quick Start#

Chat Plugin for Flutter#

With CONTUS MirrorFly Chat Plugin for Flutter, you can easily add real-time chat features to your client app within 30 minutes. Through our client SDK, you can initialize and configure chat into your app with minimal efforts.

Note : If you're looking for the fastest way to build your app’s UI with MirrorFly Chat Plugin, you can use our sample apps. To get our sample apps, click here

Requirements#

The requirements for Android

  • Android Lollipop 5.0 (API Level 21) or above
  • Java 7 or higher
  • Gradle 4.1.0 or higher
  • targetSdkVersion,compileSdk 34 or above.

The minimum requirements for iOS

  • iOS 12.1 or later

Things to be Noted Before Making a Start#

Mirrorfly License Key#

Follow the below steps to get your license key:

Step 1: Sign up into MirrorFly Console page (https://console.mirrorfly.com/register) for free MirrorFly account, If you already have a MirrorFly account, sign into your account

Step 2: Once you’re in! You get access to your MirrorFly account ‘Overview page’ where you can find a license key for further integration process

Step 3: Copy the license key from the ‘Application info’ section

license-key

Create Android dependency#

Step 4: Add the following to your root build.gradle file in your Android folder.

allprojects {
repositories {
...
...
jcenter()
maven {
url "https://repo.mirrorfly.com/release"
}
}
}

make sure below attributes are included in the app/build.gradle file in your Android folder.

android {
compileSdk 34 // or higher
...
defaultConfig {
...
minSdkVersion 21
targetSdkVersion 34 // or higher
}
}

Create iOS dependency#

Step 5: Check and Add the following code at end of your ios/Podfile

post_install do |installer|
installer.aggregate_targets.each do |target|
target.xcconfigs.each do |variant, xcconfig|
xcconfig_path = target.client_root + target.xcconfig_relative_path(variant)
IO.write(xcconfig_path, IO.read(xcconfig_path).gsub("DT_TOOLCHAIN_DIR", "TOOLCHAIN_DIR"))
end
end
installer.pods_project.targets.each do |target|
flutter_additional_ios_build_settings(target)
target.build_configurations.each do |config|
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.1'
config.build_settings['ENABLE_BITCODE'] = 'NO'
config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'No'
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = 'arm64'
shell_script_path = "Pods/Target Support Files/#{target.name}/#{target.name}-frameworks.sh"
if File::exist?(shell_script_path)
shell_script_input_lines = File.readlines(shell_script_path)
shell_script_output_lines = shell_script_input_lines.map { |line| line.sub("source=\"$(readlink \"${source}\")\"", "source=\"$(readlink -f \"${source}\")\"") }
File.open(shell_script_path, 'w') do |f|
shell_script_output_lines.each do |line|
f.write line
end
end
end
end
end
end

Step 6: Now, enable all the below mentioned capabilities into your project.

Goto Project -> Target -> Signing & Capabilities -> Click + at the top left corner -> Search for the capabilities below
Capabilities
App Groups

AppGroups

Create Flutter dependency#

Step 7: Add the below dependencies in pubspec.yaml.

dependencies:
mirrorfly_plugin: ^1.0.6

STEP 8: Run flutter pub get command in your project directory. You can use all classes and methods just with the following import statement

import 'package:mirrorfly_plugin/mirrorfly.dart';

Initialize MirrorFly Plugin#

To initialize the plugin, place the below code in your main.dart file inside main function before runApp().

void main(){
WidgetsFlutterBinding.ensureInitialized();
Mirrorfly.initializeSDK(
licenseKey: LICENSE_KEY,
iOSContainerID: iOS_APP_GROUP_ID,
chatHistoryEnable: ENABLE_CHAT_HISTORY,
flyCallback: (FlyResponse response) {
runApp(const MyApp());
}
);
}

Chat init Function Description#

FunctionParameter TypeDescription
LICENSE_KEYStringLicense key is required to proceed with registration
iOS_APP_GROUP_IDStringCreate App groups and assign the obtained group container id. Plugin uses this string to create the path for the local storage.
ENABLE_CHAT_HISTORYbooltrue To enable chat history and false for normal chat, default false
storageFolderNameStringshould be defined to set your own local path to store app media files. default "Mirrorfly"
flyCallbackFlyResponsecallback to observe the action status

Note : The chat history feature allows us to retrieve chat history every time you log into the newly acquired device. The feature stores chat history securely and provides access to the users whenever they need it. This ensures that users can access the same conversation thread across devices without any data loss.

Login#

Use the below method to login a user in sandbox Live mode.

Unless you log out the session, make a note that should never call the login method more than once in an application

Note: While registration, the below login method will accept the FCM_TOKEN as an optional param and pass it across. The connection will be established automatically upon completion of registration and not required for seperate login.

Mirrorfly.login(userIdentifier: userIdentifier,
fcmToken: token,
isForceRegister: isForceRegister,
identifierMetaData: identifierMetaData,
flyCallback: (FlyResponse response) {
if(response.isSuccess && response.hasData){
// you will get the user registration response
var userData = registerModelFromJson(value);
}
});
ArgumentTypeDescription
userIdentifierStringA unique Id to Register the User. We accept only the AlphaNumeric String
tokenStringA registration token that is generated by FCM Plugin for the user's app instance to send message for free
identifierMetaDataList<IdentifierMetaData>list of key - value pair of metadata object. Maximum size is 3
isForceRegisterBooleandefault value true, provide true to force the logout of the old session if the login user has reached the maximum no of multi-sessions or provide false to allow registration till the maximum no of multi-sessions
flyCallbackFlyResponsecallback to observe the action status

Note : After login, make sure to update the profile of the login user Update Profile.

Note : You need to re-login when the onLoggedOut event is triggered.

Note : It is recommended to disallow users to backup an app if it contains sensitive data. Having access to backup files (i.e. when android:allowBackup="true"), it is possible to modify/read the content of an app even on a non-rooted device.

caution

If FORCE_REGISTER is false and it reached the maximum no of multi-sessions then registration will not succeed it will throw a 405 exception, Either FORCE_REGISTER should be true or one of the existing session need to be logged out to continue registration.

Terminology#

Some of the most common terminologies used in MirrorFly Plugin with description

keywordExplanation
userID/userBareIDUnique Id to Register the User. User identifiers can only contain lowercase alphanumeric characters, (-) hyphens, and (_) underscores.
userJid (or) JIDuserID+@+domain of the chat server Ex. 12345678@xmpp.chatsystem.dev.contus.us
groupID/groupBareIDUnique ID assigned for each group Ex: group123456 (any alphanumeric). GroupJID = groupID +@mix.+domain of the chat server Ex: group123456@mix.xmpp.mirrorfly.dev.contus.us`
Plugin will have built-in functions to prepare the JID, Group JID, and more.

Send a One-to-One Message#

Use the below method to send a text message to other user,

Note: To generate a unique user jid by username, you must call the below method

var userJid = await Mirrorfly.getJid(username);
var textMessage = MessageParams.text(
toJid: toJid,
replyMessageId: replyMessageId, // Optional
topicId: topicId, // Optional
textMessageParams: TextMessageParams(messageText: messageText);
Mirrorfly.sendMessage(messageParams: textMessage, flyCallback: (response){
if(response.isSuccess){
}
});
ArgumentTypeDescription
jidStringJID of the end user
messageTextStringIndicates the text message that needs to be sent
replyMessageIdStringSpecifies the Message ID of replied message (Optional)

Receive a One-to-One Message#

Here the listeners would be called only when a new message is received from other user. To get more details please visit this callback listeners

Mirrorfly.onMessageReceived.listen(result){
// you will get the new messages
var chatMessage = sendMessageModelFromJson(result)
}