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.

Note

If your project needs Firebase integration or customization of features like ringtone and UI, complete the basic integration first and then refer to Customize the call and Enhance the call 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 (iOS Background/Killed)

Integration Guide for Common Components

Prerequisites

Go to ZEGOCLOUD Admin Console to create a UIKit project.
Get the AppID and AppSign of the project.

If you don't know how to create a project and obtain an app ID, please refer to this guide.

Add dependencies.

Run the following code in your project root directory, to install @zegocloud/zego-uikit-prebuilt-call-rn.

yarn

npm

yarn add @zegocloud/zego-uikit-prebuilt-call-rn

Copied!

npm install @zegocloud/zego-uikit-prebuilt-call-rn

Copied!

Warning

If you are using Expo, please note that we only support Expo bare workflow. (We have only done basic testing on expo. If possible, it is recommended to integrate call kit with a standard react native project.)
call invitation feature is not compatible with "expo-notifications" and cannot be used together. If you are using "expo-notifications", it is recommended to remove this dependency or migrate to "@react-native-firebase/messaging".

Add other dependencies.

Run the following command to install other dependencies for making sure the @zegocloud/zego-uikit-prebuilt-call-rn can work properly.

yarn

npm

yarn add @zegocloud/zego-uikit-rn react-delegate-component @react-navigation/native @react-navigation/native-stack react-native-screens react-native-safe-area-context react-native-sound react-native-encrypted-storage zego-express-engine-reactnative@3.14.5 zego-zim-react-native@2.16.0 zego-zpns-react-native@2.6.6 zego-callkit-react-native@1.0.6 react-native-keep-awake@4.0.0 react-native-device-info

Copied!

npm install @zegocloud/zego-uikit-rn react-delegate-component @react-navigation/native @react-navigation/native-stack react-native-screens react-native-safe-area-context react-native-sound react-native-encrypted-storage zego-express-engine-reactnative@3.14.5 zego-zim-react-native@2.16.0 zego-zpns-react-native@2.6.6 zego-callkit-react-native@1.0.6 react-native-keep-awake@4.0.0 react-native-device-info

Copied!

When your React Native version is below 0.60, please follow these steps

Check here if you encounter the issue "undefined is not an object (evaluating 'RNSound.IsAndroid')"

To let users transition between multiple screens, you will need to install a navigation library. In React Native, there are several different types of navigation libraries you can use to create a navigation structure. For now, we use the React navigation.

Place the ZegoCallInvitationDialog component on the top level of the NavigationContainer.

Untitled

<ZegoCallInvitationDialog />

Copied!

Add two routes (ZegoUIKitPrebuiltCallWaitingScreen and ZegoUIKitPrebuiltCallInCallScreen) to your stack navigator.

Untitled

<Stack.Screen
    options={{ headerShown: false }}
    // DO NOT change the name 
    name="ZegoUIKitPrebuiltCallWaitingScreen"
    component={ZegoUIKitPrebuiltCallWaitingScreen}
/>
<Stack.Screen
    options={{ headerShown: false }}
    // DO NOT change the name
    name="ZegoUIKitPrebuiltCallInCallScreen"
    component={ZegoUIKitPrebuiltCallInCallScreen}
/>

Copied!

Initialize the call invitation service

Call the useSystemCallingUI method in the index.js file.

index.js

import {AppRegistry} from 'react-native';
import App from './App';
import {name as appName} from './app.json';

// Add these lines \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
import ZegoUIKitPrebuiltCallService from '@zegocloud/zego-uikit-prebuilt-call-rn'
import * as ZIM from 'zego-zim-react-native';
import * as ZPNs from 'zego-zpns-react-native';

ZegoUIKitPrebuiltCallService.useSystemCallingUI([ZIM, ZPNs]);
// Add these lines /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

AppRegistry.registerComponent(appName, () => App);

Copied!

Call the ZegoUIKitPrebuiltCallService.init method.

Note

We recommend calling this method immediately after the user logs into your app.

After the user logs in, it is necessary to Initialize the ZegoUIKitPrebuiltCallInvitationService to ensure that it is initialized only once, avoiding errors caused by repeated initialization.
When the user logs out, it is important to perform Deinitialize to clear the previous login records, preventing any impact on the next login.

Untitled

import ZegoUIKitPrebuiltCallService from '@zegocloud/zego-uikit-prebuilt-call-rn'
import * as ZIM from 'zego-zim-react-native';
import * as ZPNs from 'zego-zpns-react-native';

const onUserLogin = async (userID, userName, props) => {
  return ZegoUIKitPrebuiltCallService.init(
    yourAppID, // You can get it from ZEGOCLOUD's console
    yourAppSign, // You can get it from ZEGOCLOUD's console
    userID, // It can be any valid characters, but we recommend using a phone number.
    userName,
    [ZIM, ZPNs],
    {
        ringtoneConfig: {
            incomingCallFileName: 'zego_incoming.mp3',
            outgoingCallFileName: 'zego_outgoing.mp3',
        },
        androidNotificationConfig: {
            channelID: "ZegoUIKit",
            channelName: "ZegoUIKit",
        },
    });
}

const onUserLogout = async () => {
  return ZegoUIKitPrebuiltCallService.uninit()
}

Copied!

The parameters of the init method

Add a call invitation button

Configure the "ZegoSendCallInvitationButton" to enable making calls.

One-on-one

Group call

<ZegoSendCallInvitationButton
    invitees={[{userID: varUserID, userName: varUserName}]}
    isVideoCall={true}
    resourceID={"zego_call"} // Please fill in the resource ID name that has been configured in the ZEGOCLOUD's console here.
/>

Copied!

<ZegoSendCallInvitationButton
    invitees={invitees.map((inviteeID) => {
        return { userID: inviteeID, userName: 'user_' + inviteeID };
    })}
    isVideoCall={true}
    resourceID={"zego_call"} // Please fill in the resource ID name that has been configured in the ZEGOCLOUD's console here.
/>

Copied!

Props of ZegoSendCallInvitationButton

For more parameters, go to Custom prebuilt UI.

Complete sample code

Configure your project

Android

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.

After the above is completed, the resourceID property value of ZegoSendCallInvitationButton needs to be replaced with the resource ID you get.

One-on-one

Group call

<ZegoSendCallInvitationButton
    invitees={[{userID: varUserID, userName: varUserName'}]}
    isVideoCall={true}
    resourceID={"zego_call"} // Please fill in the resource ID name that has been configured in the ZEGOCLOUD's console here.
/>

Copied!

<ZegoSendCallInvitationButton
    invitees={invitees.map((inviteeID) => {
        return { userID: inviteeID, userName: 'user_' + inviteeID };
    })}
    isVideoCall={true}
    resourceID={"zego_call"} // Please fill in the resource ID name that has been configured in the ZEGOCLOUD's console here.
/>

Copied!

step3. In the Firebase console: Create an Android application and modify your code;

2. Guide your users to set app permissions

To guide your users to enable Appear on top permission:

Or you can refer to the following code to request system aler window permission after the initialization is completed.

Untitled

const onUserLogin = async (userID, userName, props) => {
  return ZegoUIKitPrebuiltCallService.init(
    yourAppID, // You can get it from ZEGOCLOUD's console
    yourAppSign, // You can get it from ZEGOCLOUD's console
    userID, // It can be any valid characters, but we recommend using a phone number.
    userName,
    [ZIM, ZPNs],
    {
        ringtoneConfig: {
            incomingCallFileName: 'zego_incoming.mp3',
            outgoingCallFileName: 'zego_outgoing.mp3',
        },
        androidNotificationConfig: {
            channelID: "ZegoUIKit",
            channelName: "ZegoUIKit",
        },
    }
  ).then(() => {
    // /////////////////////////
    ZegoUIKitPrebuiltCallService.requestSystemAlertWindow({
      message: 'We need your consent for the following permissions in order to use the offline call function properly',
      allow: 'Allow',
      deny: 'Deny',
    });
    // /////////////////////////
  });
}

Copied!

3. Prevent code obfuscation

Open the my_project/android/app/proguard-rules.pro file and add the following:

Untitled

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

Copied!

4. Add firebase-messaging dependency

Add this line to your project's my_project/android/app/build.gradle file as instructed.

Untitled

implementation 'com.google.firebase:firebase-messaging:21.1.0'

Copied!

5. 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:

Untitled

python3 zego_check_android_offline_notification.py

Copied!

You will see the following if everything goes well:

Untitled

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

Copied!

iOS

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

Open the my_project/ios/my_project/Info.plist file and add the following:

Untitled

<key>NSCameraUsageDescription</key>
<string>We need to use the camera</string>
<key>NSMicrophoneUsageDescription</key>
<string>We need to use the microphone</string>

Copied!

3. Add Push Notifications configuration

Open the project with Xcode, and click the+ Capability on the Signing & Capabilities page.

And double-click on Push Notifications to add this feature.

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

5. Check and Make sure the following features are enabled

6. Import the PushKit and CallKit libraries.

Run & Test

Note

If your device is not performing well or you found a UI stuttering, run in Release mode for a smoother experience.

Run on an iOS device:

yarn

npm

yarn ios

Copied!

npm run ios

Copied!

Run on an Android device:

yarn

npm

yarn android

Copied!

npm run android

Copied!

FAQ

1. How to configure offline push certificates two APPs

2. How to resolve the 'permission is null' error?

Custom prebuilt UI

Refer this doc to make further customization.

Resources

Sample code

Click here to get the complete sample code.

Quick start (with call invitation)

UI Implementation Effects

Integration Guide for Common Components

Prerequisites

Add dependencies.

Config React Navigation

Initialize the call invitation service

Add a call invitation button

Configure your project

Android

1. Firebase Console and ZEGO Console Configuration

2. Guide your users to set app permissions

3. Prevent code obfuscation

4. Add firebase-messaging dependency

5. Check whether the local config is set up properly.

iOS

1. Apple Developer Center and ZEGOCLOUD Console Configuration

2. Add app permissions

3. Add Push Notifications configuration

4. Add the Background Modes capability.

5. Check and Make sure the following features are enabled

6. Import the PushKit and CallKit libraries.

Run & Test

FAQ

Related guide

Resources