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.

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 (iOS Background/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

1. Run the following code in your project root directory:

flutter pub add zego_uikit_prebuilt_call
flutter pub add zego_uikit_signaling_plugin

2. 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 to ZegoUIKitPrebuiltCallInvitationService.

  • 1.1.3 Register the navigatorKey to MaterialApp.(If you are using GoRouter, you need to register the navigatorKey to GoRouter.)

• 1.2 call the useSystemCallingUI method in the main.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.

  Warning

  1. 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.

  2.

  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();
  }
  

  1

  Copy

  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,
   resourceID: "zegouikit_call", //You need to use the resourceID that you created in the subsequent steps. Please continue reading this document.
   invitees: [
      ZegoUIKitUser(
         id: targetUserID,
         name: targetUserName,
      ),
      ...
      ZegoUIKitUser(
         id: targetUserID,
         name: targetUserName,
      )
   ],
)

Props of ZegoSendCallInvitationButton

​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 the your_project/android/app/build.gradle file.

  

• step2. Modify the minSdkVersion in the same file

  minSdkVersion 21
  

  1

  Copy

  1

  Copy

3. Set the Kotlin & Gradle versions

• step1. Modify the kotlin version to >= 1.8.0 and the gradle classpath version to 7.3.0 in the your_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'
      }
  }
  

  1

  Copy

• step2. Make the gradle version >= 7.0: In the your_project/android/gradle/wrapper/gradle-wrapper.properties file, modify the distributionUrl to https://services.gradle.org/distributions/gradle-7.4-all.zip.

  distributionUrl=https://services.gradle.org/distributions/gradle-7.4-all.zip
  

  1

  Copy

  1

  Copy

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 a proguard-rules.pro file with the following content as shown below:

  TIPS

  Please copy the following content directly instead of typing it manually

  -keep class **.zego.**  { *; }
  -keep class **.**.zego_zpns.** { *; }
  

  1

  Copy

• step2. Add the following config code to the release part of the your_project/android/app/build.gradle file.

  proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
  

  1

  Copy

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

​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.

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 the post_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
  

  1

  Copy
  

• step2. Open the your_project/ios/Runner/Info.plist file, and add the following to the dict 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

• 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.

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