Overview

CleverTap enables in-app calls via its Signed Call Flutter SDK, which means you can make and receive calls from any of your Flutter applications if the device has an internet connection and the Signed Call Flutter SDK is already integrated. This document provides information about the following:

• Signed Call Flutter SDK integration
• Manage Signed Calls from your Flutter application

To know more about the Signed Call feature, refer to Signed Call.

Prerequisites

The prerequisites vary depending on the type of your Flutter application platform.

For Android Platform

The following are the requirements for the Signed Call Flutter SDK for Android platform:

• SDK version 21 and above
• Java version 8 and above
• Application permissions for the following:
  • Microphone (Required)
  • Read Phone State (Optional)

For iOS Platform

The Signed Call iOS framework is built using Swift-5 in Xcode v14 To support CallKit, the target iOS version for deployment must be greater than or equal to iOS 10.

📘

Emulator Support

Emulator and Simulator support is available for voice calls, but voice transmission will not work.

Integrate Signed Call Flutter SDK

This process can be broadly divided into the following four major steps:

1. Install Signed Call Flutter Plugin
2. Set up Signed Call Native SDKs
3. Initialize and Authenticate Signed Call Flutter SDK
4. Manage Permissions

Install Signed Call Flutter Plugin

To install Signed Flutter SDK to your project:

1. Add the following dependency to the pubspec.yaml file of your project:

dependencies:
    clevertap_signedcall_flutter: 0.0.1

2. Run the flutter pub get command in the terminal to install the dependency.
3. Add the following to your Dart code:

import 'package:clevertap_signedcall_flutter/plugin/clevertap_signedcall_flutter.dart';

Set Up Signed Call Native SDKs

This process varies depending on the type of your Flutter application platform.

For Android Platform

To install and setup the Signed Call Android SDK:

1. Include mavenCentral in your project-level build.gradle file as follows:

allprojects {
    repositories {
        mavenCentral()
    }
}

2. Add the following code to the dependencies element of the build.gradle file of your application module:

implementation "com.clevertap.android:clevertap-signedcall-sdk:0.0.1"

3. Add the following libraries to build.gradle file of your application module:

//To integrate Signed Call Android SDK
implementation "com.clevertap.android:clevertap-signedcall-sdk:0.0.1"

//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'

4. The Signed Call Android SDK uses CleverTap Android SDK for analytics. The Signed Call Android SDK requires an active CleverTap instance as a parameter during the SDK initialization. To integrate the CleverTap Android SDK, refer to the CleverTap Android SDK Integration.

📘

Minimum Supported Version

The Signed Call Android SDK integrates with CleverTap SDK v4.6.4 or higher.

For iOS Platform

To install and set up the Signed Call iOS SDK:

1. Add the pod spec repo as a source and add the post_install script to your Podfile as shown below:

# Uncomment this line to define a global platform for your project
platform :ios, '10.0'

source 'https://github.com/CleverTap/podspecs.git'
source 'https://github.com/CocoaPods/Specs.git'

# CocoaPods analytics sends network stats synchronously affecting flutter build latency.
#ENV['COCOAPODS_DISABLE_STATS'] = 'true'

project 'Runner', {
  'Debug' => :debug,
  'Profile' => :release,
  'Release' => :release,
}

def flutter_root
  generated_xcode_build_settings_path = File.expand_path(File.join('..', 'Flutter', 'Generated.xcconfig'), __FILE__)
  unless File.exist?(generated_xcode_build_settings_path)
    raise "#{generated_xcode_build_settings_path} must exist. If you're running pod install manually, make sure flutter pub get is executed first"
  end

  File.foreach(generated_xcode_build_settings_path) do |line|
    matches = line.match(/FLUTTER_ROOT\=(.*)/)
    return matches[1].strip if matches
  end
  raise "FLUTTER_ROOT not found in #{generated_xcode_build_settings_path}. Try deleting Generated.xcconfig, then run flutter pub get"
end

require File.expand_path(File.join('packages', 'flutter_tools', 'bin', 'podhelper'), flutter_root)

flutter_ios_podfile_setup

target 'Runner' do
  use_frameworks!
  use_modular_headers!
  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    # Required by SignedCall
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
      '$(inherited)',
      
      ## dart: PermissionGroup.microphone
      'PERMISSION_MICROPHONE=1',
      ]
      
    end
  end
end

2. Update your Podfile, and run pod install --repo-update in your terminal.
   To know more, refer to Pod setup.

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

📘

Minimum Supported Version

The Signed Call iOS SDK integrates with CleverTap SDK v4.1.6 or higher.

Set Up Xcode Project

To set up your Xcode project, refer to Set Up Xcode Project.

Set Up an Outgoing Tone

To set up an outgoing tone, refer to Set Up and Outgoing Tone.

Configure Quick Launch Button on the CallKit Screen

To configure the quick launch button on the CallKit screen, refer to Configure Quick Launch Button.

📘

Icon Image File Specifications

The icon image must be a square image with a side length of 40 points. The alpha channel of the image creates a white mask image used in the native CallKit screen UI for the button, which helps switch between the native CallKit 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:

1. Open your AppDelegate file and import both, CleverTap and Signed Call SDKs as shown below:

import CleverTapSDK
import SignedCallSDK

2. Call the registerVoIP function to generate a VoIP token and set pushRegistryDelegate in your AppDelegate file.

override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        GeneratedPluginRegistrant.register(with: self)
        CleverTap.setDebugLevel(CleverTapLogLevel.off.rawValue)
        CleverTap.autoIntegrate()
        SignedCall.cleverTapInstance = CleverTap.sharedInstance()
        guard let rootView = self.window?.rootViewController else {
            return true
        }
        SignedCall.registerVoIP(withRootView: rootView)
        
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

The registerVoIP function expects the following parameters:

Initialize and Authenticate Signed Call Flutter SDK

Initialize the Signed Call Flutter SDK on every application launch using the following ClevertapSignedCallFlutter class instance:

void _signedCallInitHandler(
      SignedCallError? signedCallInitError) async {
  if (signedCallInitError == null) {
      print("Signed Call SDK Initialized!");
    } else {
      final errorCode = signedCallInitError.errorCode;
      final errorMessage = signedCallInitError.errorMessage;
      final errorDescription = signedCallInitError.errorDescription;
      print("SignedCall initialization failed: \n"
          "error-code - $errorCode \n"
          "error-message - $errorMessage \n"
          "error-description - $errorDescription");
    }
  }

//To initialize the Signed Call Flutter SDK
CleverTapSignedCallFlutter.shared.init(
      initProperties: initProperties, initHandler: _signedCallInitHandler);

initProperties

The initProperties is a Map object with the following properties:

📘

CUID Validation Rules

The following are the validation rules for cuid:

• Must range between 5 and 50 characters.
• Must start with either alphabet or number.
• The name is case-sensitive, and only '_' is allowed as a special character.
• The cuid parameter cannot be of type number-number, that is, 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:

///Common fields of Android & iOS
 final Map<String, dynamic> initProperties = {
        "accountId": <string / required>,
        "apiKey": <string / required>,
        "cuid": <string / required>,
        "overrideDefaultBranding": <map / optional>
 };

 ///Android only fields
 if (Platform.isAndroid) {
   initProperties["allowPersistSocketConnection"] = <bool / required>;
   initProperties["promptReceiverReadPhoneStatePermission"] = <bool / optional>;
   initProperties["missedCallActions"] = <map / optional>;
 }

 ///iOS only fields
 if (Platform.isIOS) {
    initProperties["production"] = <bool / 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 that 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 Map type inside the initProperties to override the dashboard branding for call screens.

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

var initProperties = {
  ....
  "overrideDefaultBranding": callScreenBranding,
  ....
};

CleverTapSignedCallFlutter.shared.init(
      initProperties: initProperties, initHandler: _signedCallInitHandler);

production (iOS Platform)

The Signed Call Flutter SDK uses the production field in iOS to set up the production or development environment for VoIP push support.

📘

Note

The production must be true if you build an application for production and false if you build an application for development. The default value is false.

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 Flutter SDK expects allowPersistSocketConnection flag, a required parameter of the bool type, passed inside the SignedCallInitConfiguration.Builder constructor.

The following is the Signed Call Flutter SDK behavior for Android platform:

📘

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.

Manage Permission

Following are the permissions and their management that the Signed Call Flutter SDK uses:

Microphone (All Platforms)

This is a required permission. The Signed Call Flutter SDK requires microphone permission to exchange voices during the call. At the receiver's end, the Signed Call Flutter SDK asks for microphone permission and handles it accordingly when the receiver answers the call. If the receiver denies microphone permission, the Signed Call Flutter SDK declines the call. We recommend you add the required handling to request the microphone permission before initiating a call.

Read Phone State (Android Platform)

This is optional permission. The Signed Call Flutter SDK uses this permission to enable busy handling for Public Switched Telephone Network (PSTN) calls. This permission determines if the receiver is available or busy 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 bool type inside the initProperties to allow the Signed Call Flutter SDK to prompt the read phone state permission at the receiver's end when the receiver answers the call.

var initProperties = {
  ....
  "promptReceiverReadPhoneStatePermission": <true/false>
  ....
};

CleverTapSignedCallFlutter.shared.init(
      initProperties: initProperties, initHandler: _signedCallInitHandler);

Logout the Signed Call Flutter SDK

When the Signed Call Flutter 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 from Initialize Signed Call Flutter SDK.

CleverTapSignedCallFlutter.shared.logout();

Make a Signed Call

Use the following code to make a Signed Call:

void _signedCallVoIPCallHandler(SignedCallError? signedCallVoIPError) {
    if (signedCallVoIPError == null) {
      print("VoIP call is placed successfully!");
    } else {
      final errorCode = signedCallVoIPError.errorCode;
      final errorMessage = signedCallVoIPError.errorMessage;
      final errorDescription = signedCallVoIPError.errorDescription;
      print("VoIP call is failed: \n"
          "error-code - $errorCode \n"
          "error-message - $errorMessage \n"
          "error-description - $errorDescription");
    }
  }
  
const callOptions = {
        "initiatorImage": "<https url / optional>",
        "receiverImage": "<https url / optional>"
      };
      
CleverTapSignedCallFlutter.shared.call(
          receiverCuid: receiverCuid,
          callContext: callContext,
          callOptions: callOptions,
          voIPCallHandler: _signedCallVoIPCallHandler);

The parameters to make a Signed Call are as follows:

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 Flutter 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 that is used when the receiver is not connected to the primary routing channel (Socket).

📘

FCM Version

The minimum supported version of FCM must be v21.0.0 or higher to integrate with your Android platform.

To enable the FCM channel, follow the steps below:

1. Add your FCM Server Key to the Signed Call section of the CleverTap dashboard. Ignore it if you have already added it.

2. Allow CleverTap Android SDK to process the FCM push of VoIP call by adding the following entries to your AndroidManifest.xml.

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

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

APNs Channel (iOS Platform)

It is a secondary or fallback routing channel for the iOS platform, which is 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.

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 Flutter 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:

CleverTapSignedCallFlutter.shared.hangUpCall();

Observe Changes in a Call State (All Platforms)

Add the following code to subscribe to the event stream of the CallEvent to listen the changes in a call state:

late StreamSubscription<CallEvent>? _callEventSubscription;

@override
void initState() {
    super.initState();
    _startObservingCallEvents();
}
  
///To Listen to the real-time stream of the various call-events
void _startObservingCallEvents() {
     _callEventSubscription = CleverTapSignedCallFlutter.shared.callEventListener
        .listen((event) {
      print("Received an event on CallEvent stream: ${event.toString()}");
      if (event == CallEvent.cancelled) {
        ///when the call is cancelled from the initiator's end
      } else if (event == CallEvent.declined) {
        ///when the call is declined from the receiver's end
      } else if (event == CallEvent.missed) {
        ///when the call is missed at the receiver's end
      } else if (event == CallEvent.answered) {
        ///When the call is picked up by the receiver
      } else if (event == CallEvent.callInProgress) {
        ///when the connection to the receiver is established
      } else if (event == CallEvent.ended) {
        ///when the call has been disconnected
      } else if (event == CallEvent.receiverBusyOnAnotherCall) {
        ///when the receiver is busy on another call
      }
    });
}

@override
void dispose() {
    super.dispose();
    _callEventSubscription?.cancel();
}

📘

Note

Make sure you include the following:

• Register the StreamSubscription<CallEvent> instance as soon as the Flutter application is initialized. Preferably in the initState() of your application widget.
• Cancel the StreamSubscription instance when the dispose() method is triggered for the application widget.

Missed Call Solution (Android Platform)

If the receiver misses a call, the Signed Call Flutter SDK shows a missed call notification to the receiver. The Signed Call Flutter 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:

1. Create a Map object for missedCallActions parameter with a maximum of three entries.

const 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>",
 };

var initProperties = {
  ....
  "missedCallActions": missedCallActionsMap,
  ....
};

CleverTapSignedCallFlutter.shared.init(
      initProperties: initProperties, initHandler: _signedCallInitHandler);

2. Add the following code to subscribe to the event stream of the MissedCallActionClickResult to listen the CTA click events on missed call notifications:

late StreamSubscription<MissedCallActionClickResult>?
    _missedCallActionClickEventSubscription;

@override
void initState() {
    super.initState();
    _startObservingMissedCallActionClickEvent();
}
  
///Listens to the missed call action click events
void _startObservingMissedCallActionClickEvent() {
     _missedCallActionClickEventSubscription = CleverTapSignedCallFlutter.shared.missedCallActionClickListener
        .listen((clickResult) {
      print("Received an event on MissedCallActionClickResult stream channel: "
          "${clickResult.toString()}");
    });
}

@override
void dispose() {
    super.dispose();
    _missedCallActionClickEventSubscription?.cancel();
}

📘

Note

Make sure to follow these points:

• Register the StreamSubscription<MissedCallActionClickResult> instance as soon as the Flutter application is initialized. Preferably in the initState() of your application widget.
• Cancel the StreamSubscription instance when the dispose() method is triggered for the application widget.

📘

Note

The event stream of MissedCallActionClickResult does not receive updates in the killed state. CleverTap plans to support this in the upcoming releases.

Debugging (All Platforms)

Signed Call Flutter 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 Flutter SDK logs for the production environment, you can set the debug level to LogLevel.off.

CleverTapSignedCallFlutter.shared.setDebugLevel(LogLevel.info); ///default level, shows minimal SDK integration related logging

CleverTapSignedCallFlutter.shared.setDebugLevel(LogLevel.debug); ///shows debug output

CleverTapSignedCallFlutter.shared.setDebugLevel(LogLevel.verbose); ///shows verbose output

CleverTapSignedCallFlutter.shared.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:

📘

Note

To get the logs in the killed state, add platform-specific debugging.

• For Android, add SignedCallAPI.setDebugLevel(SignedCallAPI.LogLevel loglevel); in your Application class.
• For iOS, add SignedCall.isLoggingEnabled = true in your AppDelegate class.

Sample Project of Signed Call Flutter SDK Implementation:

For an example project of integrating Signed Call Flutter SDK in your Flutter application, refer to the Signed Call Flutter 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 Flutter SDK provides error reporting and handling. The initHandler passed inside the init(..) method reports all the initialization errors, whereas the voIPCallHandler of the call(..) method reports all the Call errors.

For Android Platform

Below is the list of the initialization and call errors that you may receive for Android platform:

For iOS Platform

Below is the list of the initialization and call errors that you may receive for iOS platform:

FAQs

Q. Is Signed Call 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 install required dependencies.

Q. Does the Signed Call Flutter SDK support in-app calls over Bluetooth?

A. Yes. The Signed Call Flutter 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 Flutter SDK?

A. Signed Call Flutter 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 channel 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.