Quick start (with call invitation)
You can refer to this document to understand the effects of the offline call invitation (system-calling UI) and complete the basic integration.
-
If your project needs Firebase integration or customization of features like ringtone and UI, complete the basic integration first and then refer to calling config and invitation config for further configuration.
-
Offline call invitation configuration is complex. If you only require online call invitations, please skip the steps related to firebase console and apple certificate.
UI Implementation Effects
Recorded on Xiaomi and iPhone, the outcome may differ on different devices.
Online call | online call (Android App background) | offline call (Android App killed) | offline call (Android App killed) |
---|---|---|---|
Integration Guide for Common Components
It is recommended that you start by completing the integration of the common parts, and then proceed with the configuration for Android and iOS in sequence. After successfully setting up the first platform, you can begin configuring the second platform.
Prerequisites
- Go to ZEGOCLOUD Admin Console to create a UIKit project.
- Get the AppID and AppSign of the project.
- Download Sample code here.
If you don't know how to create a project and obtain an app ID, please refer to this guide.
Add ZegoUIKitPrebuiltCall as a dependency
- Run the following code in your project root directory:
flutter pub add zego_uikit_prebuilt_call
flutter pub add zego_uikit_signaling_plugin
- Run the following code in your project root directory to install all dependencies.
flutter pub get
Import the SDK
Now in your Dart code, import the prebuilt Call Kit SDK.
import 'package:zego_uikit_prebuilt_call/zego_uikit_prebuilt_call.dart';
import 'package:zego_uikit_signaling_plugin/zego_uikit_signaling_plugin.dart';
Initialize the call invitation service
To receive the call invites from others and let the calling notification show on the top bar when receiving it, you will need to initialize the call invitation service (ZegoUIKitPrebuiltCallInvitationService) first.
-
1.1 Set up the
navigatorkey
.To make the UI show when receiving a call invite, you will need to set the
navigatorkey
. To do so, do the following steps:-
1.1.1 Define a
navigatorkey
. -
1.1.2 Set the
navigatorKey
toZegoUIKitPrebuiltCallInvitationService
. -
1.1.3 Register the
navigatorKey
toMaterialApp
.(If you are using GoRouter, you need to register thenavigatorKey
toGoRouter
.)
-
-
1.2 call the
useSystemCallingUI
method in themain.dart
file.
/// 1.1.1 define a navigator key
final navigatorKey = GlobalKey();
void main() async {
WidgetsFlutterBinding.ensureInitialized();
/// 1.1.2: set navigator key to ZegoUIKitPrebuiltCallInvitationService
ZegoUIKitPrebuiltCallInvitationService().setNavigatorKey(navigatorKey);
// call the useSystemCallingUI
ZegoUIKit().initLog().then((value) {
ZegoUIKitPrebuiltCallInvitationService().useSystemCallingUI(
[ZegoUIKitSignalingPlugin()],
);
runApp(MyApp(navigatorKey: navigatorKey));
});
}
class MyApp extends StatefulWidget {
final GlobalKey navigatorKey;
const MyApp({
required this.navigatorKey,
Key? key,
}) : super(key: key);
@override
State createState() => MyAppState();
}
class MyAppState extends State {
@override
Widget build(BuildContext context) {
return MaterialApp(
/// 1.1.3: register the navigator key to MaterialApp
navigatorKey: widget.navigatorKey,
...
);
}
}
/// 1.1.1: define a navigator key
final navigatorKey = GlobalKey();
void main() async {
WidgetsFlutterBinding.ensureInitialized();
/// 1.1.2: set navigator key to ZegoUIKitPrebuiltCallInvitationService
ZegoUIKitPrebuiltCallInvitationService().setNavigatorKey(navigatorKey);
/// call the useSystemCallingUI
ZegoUIKit().initLog().then((value) {
ZegoUIKitPrebuiltCallInvitationService().useSystemCallingUI(
[ZegoUIKitSignalingPlugin()],
);
runApp(const MyApp());
});
}
final GoRouter routerConfig = GoRouter(
/// 1.1.3: register the navigator key to GoRouter
navigatorKey: navigatorKey,
initialLocation: currentUser.id.isEmpty ? PageRouteNames.login : PageRouteNames.home,
routes: [
GoRoute(
path: PageRouteNames.home,
builder: (BuildContext context, GoRouterState state) => const HomePage(),
),
GoRoute(
path: PageRouteNames.login,
builder: (BuildContext context, GoRouterState state) => const LoginPage(),
),
],
);
class MyApp extends StatefulWidget {
const MyApp({Key? key}) : super(key: key);
@override
State createState() => MyAppState();
}
class MyAppState extends State {
@override
Widget build(BuildContext context) {
return MaterialApp.router(
routerConfig: routerConfig,
...
);
}
}
- 1.3 Initialize/Deinitialize the call invitation service.
- After the user logs in, it is necessary to Initialize the ZegoUIKitPrebuiltCallInvitationService to ensure that it is initialized, every time the application starts, whether the user logs in automatically or manually, it is necessary to ensure that init is called.
- When the user logs out, it is important to perform Deinitialize to clear the previous login records, preventing any impact on the next login.
/// on App's user login
void onUserLogin() {
/// 1.2.1. initialized ZegoUIKitPrebuiltCallInvitationService
/// when app's user is logged in or re-logged in
/// We recommend calling this method as soon as the user logs in to your app.
ZegoUIKitPrebuiltCallInvitationService().init(
appID: yourAppID /*input your AppID*/,
appSign: yourAppSign /*input your AppSign*/,
userID: currentUser.id,
userName: currentUser.name,
plugins: [ZegoUIKitSignalingPlugin()],
);
}
/// on App's user logout
void onUserLogout() {
/// 1.2.2. de-initialization ZegoUIKitPrebuiltCallInvitationService
/// when app's user is logged out
ZegoUIKitPrebuiltCallInvitationService().uninit();
}
The parameters of the ZegoUIKitPrebuiltCallInvitationService().init
Property | Type | Description |
---|---|---|
appID | int | The App ID you get from ZEGOCLOUD Admin Console. |
appSign | String | The App Sign you get from ZEGOCLOUD Admin Console. |
userID | String | userID can be something like a phone number or the user ID on your own user system. userID can only contain numbers, letters, and underlines (_), with a maximum length of 32 bytes or less. |
userName | String | userName can be any character or the user name on your own user system, A utf8 string with a maximum length of 256 bytes or less. |
plugins | List< IZegoUIKitPlugin > | Fixed value. Set it to ZegoUIKitSignalingPlugin as shown in the sample. |
Please refer to the API reference for complete parameters.
Add a call invitation button
Add the button for making call invitations, and pass in the ID of the user you want to call.
ZegoSendCallInvitationButton(
isVideoCall: true,
//You need to use the resourceID that you created in the subsequent steps.
//Please continue reading this document.
resourceID: "zegouikit_call",
invitees: [
ZegoUIKitUser(
id: targetUserID,
name: targetUserName,
),
...
ZegoUIKitUser(
id: targetUserID,
name: targetUserName,
)
],
)
You will create a resourceID
in the zegocloud console, Please refer to the video tutorial below for details.
See <Firebase Console and ZEGO Console Configuration> and <Apple Developer Center and ZEGOCLOUD Console Configuration>
Props of ZegoSendCallInvitationButton
Property | Type | Description |
---|---|---|
invitees | List< ZegoUIKitUser > | The information of the callee. userID and userName are required. For example: [{ userID: inviteeID, userName: inviteeName }] |
isVideoCall | bool | If true, a video call is made when the button is pressed. Otherwise, a voice call is made. |
resourceID | String? | resourceID is a resource identifier used for configuring offline call invitations. See <Firebase Console and ZEGO Console Configuration> and <Apple Developer Center and ZEGOCLOUD Console Configuration> |
Please refer to the API reference for complete parameters.
Configure your project (Android)
Please refer to the following steps to configure your Android project. If you want to experience the functionality before integration, we have provided sample code that includes steps 2 through 6 so you can quickly test it.
1. Firebase Console and ZEGO Console Configuration
- step1. In the Firebase console: Create a project. (Resource may help: Firebase Console)
- step2. In the ZegoCloud console: Add FCM certificate, create a resource ID;
In the create resource ID popup dialog, you should switch to the VoIP option for APNs, and switch to Data messages for FCM.
When you have completed the configuration, you will obtain the resourceID
. You can refer to the image below for comparison.
- step3. In the Firebase console: Create an Android application and modify your code;
2. Modify the compileSdkVersion and minSdkVersion
- step1. Modify the
compileSdkVersion
to 33 in theyour_project/android/app/build.gradle
file.
- step2. Modify the
minSdkVersion
in the same file
minSdkVersion 21
3. Set the Kotlin & Gradle versions
- step1. Modify the
kotlin
version to >= 1.8.0 and thegradle classpath
version to 7.3.0 in theyour_project/android/app/build.gradle
file:
buildscript {
ext.kotlin_version = '1.8.0'
repositories {
google()
mavenCentral()
}
dependencies {
classpath 'com.android.tools.build:gradle:7.3.0'
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
// support notification
classpath 'com.google.gms:google-services:4.3.14'
}
}
- step2. Make the
gradle
version >= 7.0: In theyour_project/android/gradle/wrapper/gradle-wrapper.properties
file, modify thedistributionUrl
tohttps://services.gradle.org/distributions/gradle-7.4-all.zip
.
distributionUrl=https://services.gradle.org/distributions/gradle-7.4-all.zip
4. Add firebase-messaging dependency
Add this line to your project's your_project/android/app/build.gradle
file as instructed.
implementation 'com.google.firebase:firebase-messaging:21.1.0'
5. Add app permissions
Open the file your_project/app/src/main/AndroidManifest.xml
, and add the following code:
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-permission android:name="android.permission.ACCESS_NOTIFICATION_POLICY"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
<!--for bring app to foreground from background in Android 10 -->
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
6. Prevent code obfuscation
To prevent obfuscation of the SDK public class names, do the following:
- step1. In your project's
your_project > android > app
folder, create aproguard-rules.pro
file with the following content as shown below:
Please copy the following content directly instead of typing it manually
-keep class **.zego.** { *; }
-keep class **.**.zego_zpns.** { *; }
- step2. Add the following config code to the
release
part of theyour_project/android/app/build.gradle
file.
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
7. Check whether the local config is set up properly
Download the zego_check_android_offline_notification.py to your project's root directory, and run the following command:
python3 zego_check_android_offline_notification.py
You will see the following if everything goes well:
✅ The google-service.json is in the right location.
✅ The package name matches google-service.json.
✅ The project level gradle file is ready.
✅ The plugin config in the app-level gradle file is correct.
✅ Firebase dependencies config in the app-level gradle file is correct.
✅ Firebase-Messaging dependencies config in the app-level gradle file is correct.
8. Guide your users to set app permissions (Android only)
Some devices require special permissions to be enabled in order for your app to automatically display in the foreground when receiving a phone call (such as Xiaomi). Therefore, you need to guide your app users to enable the necessary app permissions to make the system-calling UI effective.
Here are the permissions that an app needs on Xiaomi devices for reference:
- Show on locked screen: Switch to Enable
- Display pop-up windows while running in the background: Switch to Enable
- Display pop-up window: Switch to Enable
image description text | image description text | image description text |
Due to the complexity of Android models and systems, regarding how to set app permissions, you can refer to this article.
9. Run & Test
Now you have finished all the Android steps!
You can simply click the Run or Debug to run and test your App on your device.
Please use real device testing, as the simulator does not support offline call invitation.
Configure your project (iOS)
Please refer to the following steps to configure your iOS project. If you want to experience the functionality before integration, we have provided sample code that includes steps 2 through 6 so you can quickly test it.
1. Apple Developer Center and ZEGOCLOUD Console Configuration
- step1. You need to refer to Create VoIP services certificates to create the VoIP service certificate, and export a .p12 file on your Mac.
- step2. Add the voip service certificate .p12 file. Then, create a resource ID;
In the create resource ID popup dialog, you should switch to the VoIP option for APNs, and switch to Data messages for FCM.
When you have completed the configuration, you will obtain the resourceID
. You can refer to the image below for comparison.
2. Add app permissions
- step1. Open the
your_project/ios/Podfile
file, and add the following to thepost_install do |installer|
part:
# Start of the permission_handler configuration
target.build_configurations.each do |config|
config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
'$(inherited)',
'PERMISSION_CAMERA=1',
'PERMISSION_MICROPHONE=1',
]
end
# End of the permission_handler configuration
- step2. Open the
your_project/ios/Runner/Info.plist
file, and add the following to thedict
part:
<key>NSCameraUsageDescription</key>
<string>We require camera access to connect</string>
<key>NSMicrophoneUsageDescription</key>
<string>We require microphone access to connect</string>
3. Disable the Bitcode
The following SDKs need to have Bitcode disabled:
- zego_zim
- zego_zpns
- zego_express_engine
- step1. Open the
your_project > iOS > Runner.xcworkspace
file. - step2. Select your target project, and follow the notes on the following two images to disable the Bitcode respectively.
4. Disable Build Libraries for Distribution
Open the your_project > iOS > Runner.xcworkspace
file. Select your target project, and follow the notes on the following image to disable the Build Libraries for Distribution
.
5. Add Push Notifications configuration
Open the project with Xcode, and click the+ Capability
on the Signing & Capabilities
page.
Double-click on Push Notifications
to add this feature.
6. Add the Background Modes capability
Open the project with Xcode, and click the+ Capability
on the Signing & Capabilities
page again.
And double-click on Background Modes
in the pop-up window. This will allow you to see the Background Modes
configuration in the Signing & Capabilities
.
7. Check and Make sure the following features are enabled
8. Import the PushKit and CallKit libraries
9. Run & Test
Now you have finished all the steps!
You can simply click the Run or Debug to run and test your App on your device.
Please use real device testing, as the simulator does not support offline call invitation.
Related guide and resources
- Click here to get the complete sample code: Sample code
- Click here for detailed explanations of all APIs: API reference
- Troubleshooting call invitations