Signed Call React Native SDK
Learn how to integrate Signed Call React Native SDK in your application to avail the Signed Call feature.
Overview
CleverTap enables in-app calls via its Signed Call React Native SDK, which means you can make and receive calls in any React Native application if the device has an internet connection and Signed Call React Native SDK. This document provides information about the following:
- Signed Call React Native SDK integration
- Manage Signed Calls from your React Native application
For more information about the feature, refer to Signed Call.
Prerequisites
The prerequisites for the Signed Call React Native SDK integration vary depending on the platforms as follows:
Android
- SDK version 21 and above
- Java version 8 and above
- Application permissions for the following:
- Microphone (Required)
- Notification (Required for Android 13 and above)
- Read Phone State (Optional)
iOS
- The Signed Call iOS framework uses Swift-5 in Xcode v14 to support
CallKit
. The target iOS version for deployment must be v10.0 and above. - Application permissions for the following:
- Microphone (Required)
- Camera (Required)
Emulator Support
Emulator and Simulator support is available for voice calls, but voice transmission will not work.
Integration
The following are the four major steps for integrating Signed Call React Native SDK:
- Integrate Signed Call React Native SDK.
- Set up Signed Call Native SDKs.
- Initialize and Authenticate Signed Call React Native SDK.
- Manage Permissions.
Integrate Signed Call React Native SDK
To integrate the Signed Call React Native SDK, add the CleverTap React Native SDK/Package to your project using Yarn or NPM as shown below:
yarn add @clevertap/clevertap-signed-call-react-native
npm install @clevertap/clevertap-signed-call-react-native
Set Up Signed Call Native SDKs
This process varies depending on the type of React Native application platform.
Android
To set up and integrate the Signed Call Android SDK:
- Include
mavenCentral
in your project-levelbuild.gradle
file as follows:
allprojects {
repositories {
mavenCentral()
}
}
- Add the following code to the dependencies element of the
build.gradle
file of your application module:
//To integrate Signed Call Android SDK,
//use either v0.0.1 which targets android 12 or v0.0.2 which targets android 13.
implementation "com.clevertap.android:clevertap-signedcall-sdk:X.X.X"
//To enable the socket-based signaling channel
implementation('io.socket:socket.io-client:2.1.0') {
exclude group: 'org.json', module: 'json'
}
//To load the image assets on the call screens
implementation 'com.github.bumptech.glide:glide:4.12.0'
//To process the incoming call push for the receiver
implementation 'androidx.work:work-runtime:2.7.1'
//To build a responsive UI for the call screens
implementation 'androidx.constraintlayout:constraintlayout:2.1.3'
- The Signed Call Android SDK uses FCM dependency to get the FCM token of the device required for the successful SDK initialization. This FCM token is then used by Signed Call to enable calls via FCM Based Call Routing Channel.
Perform the following steps to add the FCM dependency to your application:- Refer to the Firebase Integration Guide to add Firebase to your project if you have not already added it.
- Add the following code to the application module's dependency element:
implementation 'com.google.firebase:firebase-messaging:21.0.0'
FCM Version
The minimum supported version of FCM must be v21.0.0 or higher to integrate with your Android platform.
Compatibility
Refer the following table to check the compatible SDK versions corresponding to the versions of Signed Call React Native SDK:
Signed Call React Native SDK Version Compatible Signed Call Android SDK Version Compatible CleverTap Android SDK Version 0.0.1 0.0.1 4.6.4 to 4.7.0 0.0.2 0.0.2 4.7.0 and higher
iOS
To set up and integrate the Signed Call iOS SDK:
- Add the pod spec repo as a source and add the
source
,pre_install
andpost_install
script to your Podfile as shown below:
#Add source before App target
source 'https://github.com/CleverTap/podspecs.git'
source 'https://github.com/CocoaPods/Specs.git'
#Add these pods in your App target
target 'YOUR_TARGET_NAME' do
use_frameworks!
pod 'clevertap-signed-call-react-native', :path => '../..'
pod 'CleverTap-iOS-SDK', '4.2.0', modular_headers: true
pod 'CleverTap-SignedCall-SDK'
pod 'Permission-Microphone', :path => '../node_modules/react-native-permissions/ios/Microphone/Permission-Microphone.podspec'
pod 'Permission-Camera', :path => '../node_modules/react-native-permissions/ios/Camera/Permission-Camera.podspec'
end
#pre_install script as we are using `use_frameworks!`
pre_install do |installer|
Pod::Installer::Xcode::TargetValidator.send(:define_method, :verify_no_static_framework_transitive_dependencies) {}
installer.pod_targets.each do |pod|
if pod.name.eql?('RNPermissions') || pod.name.start_with?('Permission-')
def pod.build_type;
Pod::BuildType.static_library
end
end
end
end
#post_install script
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
installer.target_installation_results.pod_target_installation_results.each do |pod_name, target_installation_result|
target_installation_result.native_target.build_configurations.each do |config|
# For third party modules who have React-bridging dependency to search correct headers
config.build_settings['HEADER_SEARCH_PATHS'] ||= '$(inherited) '
config.build_settings['HEADER_SEARCH_PATHS'] << '"$(PODS_ROOT)/Headers/Private/React-bridging/react/bridging" '
config.build_settings['HEADER_SEARCH_PATHS'] << '"$(PODS_CONFIGURATION_BUILD_DIR)/React-bridging/react_bridging.framework/Headers" '
end
end
react_native_post_install(installer)
__apply_Xcode_12_5_M1_post_install_workaround(installer)
end
- Update your Podfile, and run
pod install --repo-update
in your terminal. For more information, refer to Pod Setup - The Signed Call iOS SDK uses CleverTap SDK for analytics. The Signed Call iOS SDK requires an active CleverTap instance as a parameter during the SDK initialization.
Compatibility
The Signed Call iOS SDK integrates with CleverTap SDK v4.1.6 or higher.
- To set up your Xcode project, refer to Set Up Xcode Project.
- To set up an outgoing tone, refer to Set Up and Outgoing Tone.
- To configure the quick launch button on the
CallKit
screen, refer to Configure Quick Launch Button.
Icon Image File Specifications
The icon must be square with a side length of 40 points. The image's alpha channel creates a white mask image used in the native
CallKit
screen UI for the button, which helps switch between the nativeCallKit
screen and the application's calling screen.
Integrate the Signed Call iOS SDK
Integrate the Signed Call iOS SDK and CleverTap iOS SDK as follow:
- Open your
AppDelegate
file and import both, CleverTap and Signed Call SDKs as shown below:
@import CleverTapSDK;
@import SignedCallSDK;
import CleverTapSDK
import SignedCallSDK
Note
You must use
@import
instead of#import
in the AppDelegate Objective-C class when usinguse_modular_headers!
in the podfile.
- Call the
registerVoIP
function to generate a VoIP token and setpushRegistryDelegate
in yourAppDelegate
file.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//React Native setup code
//...
CleverTap.setDebugLevel(CleverTapLogLevel.off.rawValue)
CleverTap.autoIntegrate()
SignedCall.cleverTapInstance = CleverTap.sharedInstance()
[SignedCall registerVoIPWithRootView:self.window.rootViewController appName:@"Sample App"];
//...
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
//React Native setup code
//...
CleverTap.setDebugLevel(CleverTapLogLevel.off.rawValue)
CleverTap.autoIntegrate()
SignedCall.isLoggingEnabled = true
SignedCall.cleverTapInstance = CleverTap.sharedInstance()
guard let rootView = self.window?.rootViewController else {
return true
}
SignedCall.registerVoIP(withRootView: rootView)
//...
}
The registerVoIP
function expects the following parameters:
Parameter | Description | Type | Notes |
---|---|---|---|
rootView | The view controller on which the call screen displays. | UIViewController | Required |
appName | The application name you want to display on the CallKit incoming screen. | String | Optional |
Initialize and Authenticate Signed Call React Native SDK
To initialize Signed Call React Native SDK in your JavaScript or TypeScript code, call the init
method on the SignedCall
reference as shown below:
Method Declaration
static initialize(initProperties: object): Promise<SignedCallResponse>
This method returns a Promise object. Use then() method to get the results.
Usage
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
SignedCall.initialize(initProperties)
.then((response: SignedCallResponse) => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
const error = response.error;
const errorCode = error?.errorCode;
const errorMessage = error?.errorMessage;
const errorDescription = error?.errorDescription;
console.log(
'Signed Call initialization failed: \n' +
'error-code: ' + errorCode + '\n' +
'error-message: ' + errorMessage + '\n' +
'error-description: ' + errorDescription
);
}
})
.catch((e: any) => {
console.error(e);
});
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
SignedCall.initialize(initProperties)
.then(response => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
const error = response.error;
const errorCode = error?.errorCode;
const errorMessage = error?.errorMessage;
const errorDescription = error?.errorDescription;
console.log(
'Signed Call initialization failed: \n' +
'error-code: ' + errorCode + '\n' +
'error-message: ' + errorMessage + '\n' +
'error-description: ' + errorDescription
);
}
})
.catch(e => {
console.error(e);
});
The initProperties
is a Map object with the following properties:
Properties | Description | Type | Comments |
---|---|---|---|
accountId | The unique identity of the client's account. It is available from the CleverTap dashboard. | String | Required |
apiKey | The unique identity of the client's account. It is available from the CleverTap dashboard. | String | Required |
cuid | The unique identity of the user. | String | Required |
overrideDefaultBranding | It overrides the call screen’s branding set from the dashboard. To know more, refer to its usage. | Object | Optional The default branding is the one you set from the dashboard. |
production | It enables the VoIP push based on the build type of the iOS application. To know more, refer to its usage. | Boolean | Required (iOS) |
allowPersistSocketConnection | It controls the persistence of the socket connection that SDK uses to initiate or receive the calls. To know more, refer to its usage. | Boolean | Required (Android) |
promptPushPrimer | It enables the Push Primer to support Android 13 changes for the Runtime Notification Permission. For more information, refer to Android 13 Changes. | Object | Optional (Android) |
promptReceiverReadPhoneStatePermission | When the receiver answers the call, it prompts the receiver with Read Phone State permission. The SDK uses Read Phone State permission to enable busy handling for PSTN calls. For more information, refer to Read Phone State. | Boolean | Optional (Android) The default value is false. |
missedCallActions | It configures the action buttons for the missed call notification. For more information, refer to missedCallActions. | Object | Optional (Android) No action buttons are displayed on a missed call notification without this parameter. A maximum of three action buttons can be configured for the missed call notification, where each entry in the map object represents an action button. |
CUID Validation Rules
The following are the validation rules for
cuid
:
- Range between 5 and 50 characters.
- Start with either alphabet or a number.
- The name is case-sensitive, and only '_' is allowed as a special character.
- Cannot be of type number-number, i.e. a number followed by a special character, which is again followed by another number. For example, org_25 is allowed, but 91_8899555 is not permitted.
- Must be unique for every user.
- Must be unique for every device to allow multiple logins for the user from different devices. In such cases, the user will have multiple
cuid
's.
The syntax for initProperties
is as follows:
import { Platform } from 'react-native';
let initProperties: { [k: string]: any } = {
accountId: <string / required>,
apiKey: <string / required>,
cuid: <string / required>,
}
if (Platform.OS === 'android') {
initProperties.allowPersistSocketConnection = <boolean / required>;
initProperties.promptReceiverReadPhoneStatePermission = <boolean / optional>;
initProperties.missedCallActions = <object / optional>;
}
if (Platform.OS === 'ios') {
initProperties.production = <boolean / required>;
}
import { Platform } from 'react-native';
let initProperties = {
accountId: <string / required>,
apiKey: <string / required>,
cuid: <string / required>,
}
if (Platform.OS === 'android') {
initProperties.allowPersistSocketConnection = <boolean / required>;
initProperties.promptReceiverReadPhoneStatePermission = <boolean / optional>;
initProperties.missedCallActions = <object / optional>;
}
if (Platform.OS === 'ios') {
initProperties.production = <boolean / required>;
}
overrideDefaultBranding (All Platforms)
CleverTap dashboard provides a branding tool to alter the look and feel of the call screens. If you have multiple applications to integrate with the Signed Call SDK, all those applications will share the same branding you have set from the CleverTap dashboard. By overriding the dashboard's call screen branding, you can have different branding for each application.
Use an optional overrideDefaultBranding
parameter of the object
type inside the initProperties
to override the dashboard branding for call screens.
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
let callScreenBranding = {
bgColor: '<hex color code>', //The background color of the call screens
fontColor: '<hex color code>', //The color of the text displayed on the call screens
logoUrl: '<https url>', //The image URL that renders on the call screens.
buttonTheme: 'light' or "dark", //The theme of the control buttons shown on the ongoing call screen(i.e. Mute, Speaker and Bluetooth)
};
let initProperties = {
....
overrideDefaultBranding: callScreenBranding,
....
};
SignedCall.initialize(initProperties)
.then((response: SignedCallResponse) => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
console.log('Signed Call initialization failed: ', response.error);
}
})
.catch((e: any) => {
console.error(e);
});
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
let callScreenBranding = {
bgColor: '<hex color code>', //The background color of the call screens
fontColor: '<hex color code>', //The color of the text displayed on the call screens
logoUrl: '<https url>', //The image URL that renders on the call screens.
buttonTheme: 'light' or "dark", //The theme of the control buttons shown on the ongoing call screen(i.e. Mute, Speaker and Bluetooth)
};
let initProperties = {
....
overrideDefaultBranding: callScreenBranding,
....
};
SignedCall.initialize(initProperties)
.then(response => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
console.log('Signed Call initialization failed: ', response.error);
}
})
.catch(e => {
console.error(e);
});
production (iOS Platform)
The Signed Call React Native SDK uses the production
field in iOS to set up the production or development environment for VoIP push support.
production
is used for testing VoIP push after deploying the app on TestFlight or the App Store.development
is used for testing VoIP push during the development phase on a simulator or device.
Note
The
production
must betrue
if you build/deploy an application for production andfalse
if you build/deploy an application for development. The default value isfalse
.
allowPersistSocketConnection (Android Platform)
The socket connection plays a crucial role in processing the call request to initiate a call and receive calls on the socket channel. Android OS imposes several battery restrictions that lead to issues in maintaining a persistent socket connection. To overcome this issue, Signed Call React Native SDK expects allowPersistSocketConnection
flag, a required boolean
type parameter passed inside the initProperties
.
The following is the Signed Call React Native SDK behavior for Android platform:
Value | Socket Connection | Signed Call React Native SDK |
---|---|---|
true | Persistent | For Android platform, the Signed Call React Native SDK uses a background service to keep the socket connection persistent in the foreground and background states of the application. |
false | Non-persistent | The Signed Call React Native SDK does not use the background service for the socket connection; hence the socket connection may be inconsistent under battery restriction scenarios. |
Recommended Settings for Android 11 and Above
For Android 11 and above, if the socket connection is persistent, the application might show a system-generated notification to the user that the application is draining the device's battery. We recommend setting the value as false and keeping the socket connection non-persistent for transactional businesses.
Android 13 Changes
All applications having Android 13 and above must request Runtime Notification Permission from the user before sending the notifications.
For android platform, Signed Call React Native SDK utilizes both local and remote notifications during VoIP calls. Therefore, notification permission is required from the user to initialize the Signed Call Flutter SDK.
Signed Call React Native SDK v0.0.2 Supports Android 13
If you want to increase the target API of your application to 33 or higher, you must upgrade the following:
- Signed Call React Native SDK to version 0.0.2 or higher
- CleverTap React Native SDK to version 1.0.0 or higher
Push Primer for Push Notification Permission
The Push Primer is a local In-App notification that educates users about the context of the notifications before requesting the notification permission.
To initialize the Signed Call React Native SDK for Android 13 and above, you can enable the Push Primer using any of the following:
Enable Push Primer via CleverTap React Native SDK
CleverTap React Native SDK v1.0.0 and above supports Push Primer. For more information, refer to CleverTap React Native Push Primer.
Enable Push Primer via Signed Call React Native SDK
The Signed Call React Native SDK enables you to display Push Primer using an optional promptPushPrimer
parameter of Object type inside the initProperties
. It ensures that the initialization happens after the notification permission is granted using Push Primer.
To configure the Push Primer:
- Create a Push Primer configuration using the In-App campaign's Half-Interstitial or Alert template.
//Creates push primer config using Half-Interstitial template
const pushPrimerConfig = {
inAppType: 'half-interstitial',
titleText: 'Get Notified',
messageText:'Please enable notifications on your device to use Push Notifications.',
followDeviceOrientation: true,
positiveBtnText: 'Allow',
negativeBtnText: 'Cancel',
backgroundColor: '#FFFFFF',
btnBorderColor: '#0000FF',
titleTextColor: '#0000FF',
messageTextColor: '#000000',
btnTextColor: '#FFFFFF',
btnBackgroundColor: '#0000FF',
btnBorderRadius: '2',
fallbackToSettings: true, //Setting this parameter to true will open an in-App to redirect you to Mobile's OS settings page.
};
//Creates push primer config using Alert template
const pushPrimerConfig = {
inAppType: 'alert',
titleText: 'Get Notified',
messageText: 'Enable Notification permission',
followDeviceOrientation: true,
positiveBtnText: 'Allow',
negativeBtnText: 'Cancel',
fallbackToSettings: true, //Setting this parameter to true will open an in-App to redirect you to Mobile's OS settings page.
};
//Creates push primer config using Half-Interstitial template
const pushPrimerConfig = {
inAppType: 'half-interstitial',
titleText: 'Get Notified',
messageText:'Please enable notifications on your device to use Push Notifications.',
followDeviceOrientation: true,
positiveBtnText: 'Allow',
negativeBtnText: 'Cancel',
backgroundColor: '#FFFFFF',
btnBorderColor: '#0000FF',
titleTextColor: '#0000FF',
messageTextColor: '#000000',
btnTextColor: '#FFFFFF',
btnBackgroundColor: '#0000FF',
btnBorderRadius: '2',
fallbackToSettings: true, //Setting this parameter to true will open an in-App to redirect you to Mobile's OS settings page.
};
//Creates push primer config using Alert template
const pushPrimerConfig = {
inAppType: 'alert',
titleText: 'Get Notified',
messageText: 'Enable Notification permission',
followDeviceOrientation: true,
positiveBtnText: 'Allow',
negativeBtnText: 'Cancel',
fallbackToSettings: true, //Setting this parameter to true will open an in-App to redirect you to Mobile's OS settings page.
};
- Pass the Push Primer configuration inside the
promptPushPrimer
parameter of theinitProperties
. It displays the Push Primer during the SDK initialization.
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
let initProperties = {
....
promptPushPrimer: pushPrimerConfig,
....
};
SignedCall.initialize(initProperties)
.then((response: SignedCallResponse) => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
console.log('Signed Call initialization failed: ', response.error);
}
})
.catch((e: any) => {
console.error(e);
});
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
let initProperties = {
....
promptPushPrimer: pushPrimerConfig,
....
};
SignedCall.initialize(initProperties)
.then(response => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
console.log('Signed Call initialization failed: ', response.error);
}
})
.catch(e => {
console.error(e);
});
Note
- The above configuration enables the Push Primer only if the device and application both target Android 13 (API level 33) or higher.
- During the SDK initialization, Signed Call React Native SDK registers a listener to obtain the result of the push notification permission request. After registration, this listener continues monitoring the permission result, even if the Push Primer prompt is displayed from the CleverTap Flutter SDK.
- If the notification permission is denied, the Signed Call React Native SDK returns an exception within the promise object that is associated to the
SignedCall.initialize(..)
method.
Manage Permission
Following are the permissions required for the Signed Call React Native SDK integration:
Microphone (All Platforms)
This is a required permission. The Signed Call React Native SDK requires microphone permission to exchange voices during the call. At the receiver's end, the Signed Call React Native SDK asks for microphone permission and handles it accordingly when the receiver answers the call. If the receiver denies microphone permission twice, the Signed Call React Native SDK declines the call. We recommend you add the required handling to request the microphone permission before initiating a call.
Camera (iOS Platform)
This is a required permission. The Signed Call React Native SDK requires camera permission entry in theinfo.plist
to meet CallKit
policies to initiate and receive VOIP calls. We recommend you add the NSCameraUsageDescription
key in info.plist
.
Read Phone State (Android Platform)
This is optional permission. The Signed Call React Native SDK uses this permission to enable busy handling for Public Switched Telephone Network (PSTN) calls. This permission determines if the receiver is available or engaged on a PSTN call. We recommend you add the required handling to request the Read Phone State permission before initiating a call.
Use the promptReceiverReadPhoneStatePermission
parameter of the boolean
type inside the initProperties
as shown below to allow the Signed Call React Native SDK to prompt the read phone state permission at the receiver's end when the receiver answers the call.
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
let initProperties = {
....
promptReceiverReadPhoneStatePermission: true/false,
....
};
SignedCall.initialize(initProperties)
.then((response: SignedCallResponse) => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
console.log('Signed Call initialization failed: ', response.error);
}
})
.catch((e: any) => {
console.error(e);
});
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
let initProperties = {
....
promptReceiverReadPhoneStatePermission: true/false,
....
};
SignedCall.initialize(initProperties)
.then(response => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
console.log('Signed Call initialization failed: ', response.error);
}
})
.catch(e => {
console.error(e);
});
Logout the Signed Call React Native SDK
When the Signed Call React Native SDK initializes, it maintains the init configuration in a local session. Use the logout()
method to invalidate the active session and disable the Signed Call functionality (make and receive a call). To enable it again, repeat the steps listed under Initialize Signed Call React Native SDK.
SignedCall.logout();
SignedCall.logout();
Make the Signed Call
To make a Signed Call in your JavaScript or TypeScript code, use the call
method on the SignedCall reference as shown below:
Method Declaration
static call(
receiverCuid: string,
callContext: string,
callProperties?: object | undefined
): Promise<SignedCallResponse>
This method returns a Promise object. Use then() method to get the results.
Usage
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
//following callProperties object is an optional parameter
let callProperties = {
initiator_image: '<https url / optional>',
receiver_image: '<https url / optional>',
};
SignedCall.call(receiverCuid, callContext, callProperties)
.then((response: SignedCallResponse) => {
if (response.isSuccessful) {
console.log('Signed call is placed successfully', response);
} else {
const error = response.error;
const errorCode = error?.errorCode;
const errorMessage = error?.errorMessage;
const errorDescription = error?.errorDescription;
console.log(
'Signed Call initialization failed: \n' +
'error-code: ' + errorCode + '\n' +
'error-message: ' + errorMessage + '\n' +
'error-description: ' + errorDescription
);
}
})
.catch((e: any) => {
console.error(e);
});
import {
SignedCall,
SignedCallResponse,
} from '@clevertap/clevertap-signed-call-react-native';
//following callProperties object is an optional parameter
let callProperties = {
initiator_image: '<https url / optional>',
receiver_image: '<https url / optional>',
};
SignedCall.call(receiverCuid, callContext)
.then(response => {
if (response.isSuccessful) {
console.log('Signed call is placed successfully', response);
} else {
const error = response.error;
const errorCode = error?.errorCode;
const errorMessage = error?.errorMessage;
const errorDescription = error?.errorDescription;
console.log(
'Signed Call initialization failed: \n' +
'error-code: ' + errorCode + '\n' +
'error-message: ' + errorMessage + '\n' +
'error-description: ' + errorDescription
);
}
})
.catch(e => {
console.error(e);
});
The parameters to make a Signed Call are as follows:
Parameter | Description | Type | Comments |
---|---|---|---|
receiverCuid | It is the receiver's cuid. | String | Required |
contextCall | It specifies the context of the call. For example, Delivery Partner is calling, the Driver is calling, Agent is calling, and so on. The parameter must include alphanumeric characters, and its length must not exceed 64 characters. | String | Required |
callOptions | It is an object with the following properties: 1. receiver_image (string): URL that displays the receiver's image to the initiator of the call (optional).2. initiator_image (string): URL that displays the initiator's image to the receiver of the call (optional). | Object | Optional |
Setup to Receive a Signed Call
Signed Call uses the following routing channels to receive Signed Calls at the receiver's end:
Socket Channel (All Platforms)
It is a primary routing channel. Signed Call React Native SDK requires a successful initialization to receive a call on the socket channel.
FCM Channel (Android Platform)
It is a secondary or fallback routing channel used when the receiver is not connected to the primary routing channel (Socket).
To enable the FCM channel, follow the steps below:
- Add your FCM Server Key to the Signed Call section of the CleverTap dashboard. Ignore it if you have already added it.
- Allow CleverTap Android SDK to process the FCM push of VoIP call by adding the following entries to your
AndroidManifest.xml
file.
<application>
....
....
<service android:name="com.clevertap.android.sdk.pushnotification.fcm.FcmMessageListenerService"
android:exported="true">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
....
</application>
- Add the following code to your Application class:
CleverTapAPI.setSignedCallNotificationHandler(new SignedCallNotificationHandler());
CleverTapAPI.setSignedCallNotificationHandler(SignedCallNotificationHandler())
The setup is now complete to receive calls via the FCM channel.
Important
The Missed Call Implementation is mandatory to receive calls via FCM channel for Signed Call React Native SDK v0.0.2 and below.
APNs Channel (iOS Platform)
It is a secondary or fallback routing channel for the iOS platform, used when the receiver is not connected to the primary routing channel (Socket).
To enable the APNs channel to start receiving VoIP notifications, set up the APNs in the Signed Call section of the CleverTap dashboard.
Close Socket Connection (All Platforms)
The Signed Call React Native SDK uses the socket connection to signal VoIP calls from the initiator to the receiver. After successful SDK initialization, the socket connection to initiate or receive VoIP calls opens.
If the socket is left open for a longer period, the application might drain the device's battery. In the case of Android, the application might also show a system-generated notification to the user that the application is draining the device's battery. Therefore, we recommend disconnecting the socket after all expected/pending transactions are over.
To close the socket connection, use the following method as per your business use case:
SignedCall.disconnectSignallingSocket();
SignedCall.disconnectSignallingSocket();
The following is the Signed Call React Native SDK behavior after the SDK calls the disconnectSignallingSocket()
method:
Functionality | Signed Call React Native SDK Behavior |
---|---|
Initiate a call | Users cannot initiate calls. If they attempt a VoIP call request, Signed Call React Native SDK returns an exception within the promise object that is associated to the SignedCall.call(..) method. It is essential to reinitialize the Signed Call SDK if a use case arises where a call needs to be initiated.For example, if a user happens to place an order in the application and you want to give the option to initiate a VoIP call, the Signed Call React Native SDK needs to be reinitialized. |
Receive a call | Users can still receive calls as Signed Call uses FCM (for Andorid) and APNs (for iOS) as a fallback channel to receive the calls. |
Handle Call Hangup (All Platforms)
The call hangup functionality is user-driven, and ending the call depends on the user. For example, if one of the users in a call clicks the call hangup button from the ongoing call screen, the Signed Call React Native SDK internally manages the call hangup functionality to end the call.
In the case of a metered call, when a business wants to end the call after a specific duration, you must maintain a timer in the application and use the following method to terminate the call when the timer ends:
SignedCall.hangup();
SignedCall.hangup();
Observe Changes in a Call State (All Platforms)
At the initiator’s end, the Signed Call React Native SDK sends the SignedCall.SignedCallOnCallStatusChanged
event with CallEvent
payload when the call state is changed.
Refer to the below code to understand the changes in a call state:
import {
SignedCall,
CallEvent,
} from '@clevertap/clevertap-signed-call-react-native';
//To start observing the changes in a call states.
SignedCall.addListener(
SignedCall.SignedCallOnCallStatusChanged,
(event: CallEvent) => {
console.log('SignedCallOnCallStatusChanged', event);
}
);
//To stop observing the changes in a call state.
SignedCall.removeListener(SignedCall.SignedCallOnCallStatusChanged);
import {
SignedCall,
CallEvent,
} from '@clevertap/clevertap-signed-call-react-native';
//To start observing the changes in a call states.
SignedCall.addListener(
SignedCall.SignedCallOnCallStatusChanged,
event => {
console.log('SignedCallOnCallStatusChanged', event);
}
);
//To stop observing the changes in a call state.
SignedCall.removeListener(SignedCall.SignedCallOnCallStatusChanged);
Register the above listener either before the VoIP Call is initiated or when the application is initialized in the constructor of your App.js
.
Missed Call Solution (Android Platform)
If the receiver misses a call, the Signed Call React Native SDK shows a missed call notification to the receiver. The Signed Call React Native SDK uses action buttons on the missed call notification to display a Call to Action (CTA).
To configure the CTA on the missed call notification, add the following code:
- Create a Map object for
missedCallActions
parameter with a maximum of three entries.
let missedCallActionsMap = {
'<Unique Identifier 1>': '<label on action-button 1>',
'<Unique Identifier 2>': '<label on action-button 2>',
'<Unique Identifier 3>': '<label on action-button 3>',
};
let initProperties = {
....
missedCallActions: missedCallActionsMap,
....
};
SignedCall.initialize(initProperties)
.then((response: SignedCallResponse) => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
console.log('Signed Call initialization failed: ', response.error);
}
})
.catch((e: any) => {
console.error(e);
});
let missedCallActionsMap = {
'<Unique Identifier 1>': '<label on action-button 1>',
'<Unique Identifier 2>': '<label on action-button 2>',
'<Unique Identifier 3>': '<label on action-button 3>',
};
let initProperties = {
....
missedCallActions: missedCallActionsMap,
....
};
SignedCall.initialize(initProperties)
.then(response => {
if (response.isSuccessful) {
console.log('Signed Call SDK initialized: ', response);
} else {
console.log('Signed Call initialization failed: ', response.error);
}
})
.catch(e => {
console.error(e);
});
- Add the following code to subscribe to the event stream of the
MissedCallActionClickResult
to listen to the CTA click events on missed call notifications:
import {
SignedCall,
MissedCallActionClickResult,
} from '@clevertap/clevertap-signed-call-react-native';
SignedCall.addListener(
SignedCall.SignedCallOnMissedCallActionClicked,
(event: MissedCallActionClickResult) => {
console.log('SignedCallOnMissedCallActionClicked', event);
Alert.alert(
'Missed Call Notification!',
event.action.actionLabel + ' is clicked'
);
}
);
import {
SignedCall,
MissedCallActionClickResult,
} from '@clevertap/clevertap-signed-call-react-native';
//To start observing the CTA click on a missed call notification.
SignedCall.addListener(
SignedCall.SignedCallOnMissedCallActionClicked,
event => {
console.log('SignedCallOnMissedCallActionClicked', event);
}
);
//To stop observing the CTA click on a missed call notification.
SignedCall.removeListener(SignedCall.SignedCallOnMissedCallActionClicked);
Register this listener either when the Signed Call SDK is initialized or when the application is initialized in the constructor of your App.js
.
Note
This event listener of
SignedCall.SignedCallOnMissedCallActionClicked
does not receive updates in the killed state. CleverTap plans to support this in the upcoming releases.
Debugging (All Platforms)
Signed Call React Native SDK logs are, by default, set to the LogLevel.info
level. We recommend you set the log level to LogLevel.verbose
mode to log warnings or other important messages during development. If you want to disable the Signed Call React Native SDK logs for the production environment, you can set the debug level to LogLevel.off
.
SignedCall.setDebugLevel(LogLevel.info); //default level, shows minimal SDK integration related logging
SignedCall.setDebugLevel(LogLevel.debug); //shows debug output
SignedCall.setDebugLevel(LogLevel.verbose); //shows verbose output
SignedCall.setDebugLevel(LogLevel.off); //disables all debugging
SignedCall.setDebugLevel(LogLevel.info); //default level, shows minimal SDK integration related logging
SignedCall.setDebugLevel(LogLevel.debug); //shows debug output
SignedCall.setDebugLevel(LogLevel.verbose); //shows verbose output
SignedCall.setDebugLevel(LogLevel.off); //disables all debugging
The log window displays the logs from the Signed Call SDKs. After setting the debug level, search for the following tags:
Platform | TAG |
---|---|
Android | [CT]:[SignedCall] |
iOS | [Signed Call] |
React Native | [CT]:[SignedCall]:[RN] |
Sample Project of Signed Call React Native SDK Implementation:
For an example project of integrating Signed Call React Native SDK in your React Native application, refer to Signed Call React Native Example Project.
Note
Ensure you have added valid Signed Call and CleverTap Account credentials for the calling to work.
Error Handling (All Platforms)
The Signed Call React Native SDK provides error reporting and handling.
The SignedCall.initialize(..)
and SignedCall.call(..)
methods are associated with promise
objects that receive a SignedCallResponse
object. This object contains any initialization or call errors that may occur.
- For the initialization and call errors, you may receive for the Android platform, refer to Android Error Handling.
- For the initialization and call errors, you may receive for the iOS platform, refer to iOS Error Handling.
FAQs
Q. Is Signed Call accountId
and apiKey
the same as CleverTap's accountId
and token
?
accountId
and apiKey
the same as CleverTap's accountId
and token
?A. No. Signed Call accountId
and apiKey
differ from CleverTap's accountId
and token
. You can find these details under your dashboard's Signed Call Settings.
Q. Why the iOS dependencies of Signed Call are not downloaded even after running the pod install?
A. As Signed Call iOS SDK uses submodules performing pod repo update
, it would help download and include the required dependencies.
Q. Does the Signed Call React Native SDK support in-app calls over Bluetooth?
A. Yes. The Signed Call React Native SDK has built-in Bluetooth support. However, it requires a runtime BLUETOOTH_CONNECT permission for Android 12 and onwards.
Q. What channels are used for call routing by Signed Call React Native SDK?
A. Signed Call React Native SDK uses an active socket connection as soon as the SDK is initialized. The socket connection is a primary routing channel to receive the calls, whereas the FCM in Android platform and APNs in the iOS platform are the fallback channels in case the receiver is not connected to the socket channel. This socket connection processes the call requests raised to make a call. To know more, refer to the Best practices for initializing Signed Call SDKs.
Updated 3 days ago