@bandyer/cordova-plugin-bandyer NPM

Bandyer Logo

Kaleyra Video Cordova Plugin

Requirements

npm i xml2js // needed for android 
cordova plugin add cordova-plugin-enable-multidex // plugin needed for android 64k max limit of methods
cordova plugin add cordova-plugin-androidx // needed for android

How to install the plugin:

Open the terminal in your Cordova-App folder and run the following commands

cordova plugin add @bandyer/cordova-plugin-bandyer

Advanced installation options

Starting from the 0.8.0 version, the iOS plugin supports the broadcast screen sharing feature of the native Kaleyra Video SDK. In order to enable the broadcast screen sharing tool in your cordova app you must add the plugin providing some settings. For more information please take a look at Bandyer Broadcast Extension Cordova Plugin documentation.

How to link local plugin:

Link the local plugin to the project

cordova plugin add @bandyer/cordova-plugin-bandyer --searchPath ${path-to-local-plugin}  --link

How to remove the plugin:

cordova plugin remove @bandyer/cordova-plugin-bandyer

Update the Cordova platforms

Every time you update the plugin remove the platforms 'android' and/or 'ios' and re add them to ensure that all modified plugins are copied to build folders remove platforms 'android' and/or 'ios' and re add them to ensure that all modified plugins are copied to build folders

cd {to your app root folder}
# Add --nosave if you don't want to update your package.json file when executing the commands below
cordova platforms remove android ios
cordova platforms add android ios

How to run the cordova app

iOS - device

cordova run ios

iOS - simulator

To run on the iOS simulator it's required to copy the following file .mp4 in your app assets. https://static.bandyer.com/corporate/iOS/assets/bandyer_iOS_simulator_video_sample.mp4. You may run the following command at the root of your app, which will download and put the file in the assets folder

cd {to your app root folder}
mkdir www/assets & curl -o www/assets/bandyer_iOS_simulator_video_sample.mp4 https://static.bandyer.com/corporate/iOS/assets/bandyer_iOS_si
mulator_video_sample.mp4

Once downloaded you will need to declare the file your config.xml

<platform name="ios">
	<resource-file src="www/assets/bandyer_iOS_simulator_video_sample.mp4" target="bandyer_iOS_simulator_video_sample.mp4" />
</platform>

Android

cordova run android

How to use the plugin in your Cordova app

You can refer to the Bandyer plugin in your cordova app via

BandyerPlugin

Plugin setup

The first thing you need to do is to configure the plugin specifying your keys and your options.

Configure params

var bandyerPlugin = BandyerPlugin.configure({
    environment: BandyerPlugin.environments.sandbox(), // production()
    appID: 'mAppId_xxx', // your mobile appId
    region: BandyerPlugin.regions.europe(), // india(), us()
    logEnabled: true, // enable the logger
    tools: { // by default no tools will be set
        chat: {
            audioCallOption: {
                type: BandyerPlugin.audioCallTypes.AUDIO, // AUDIO_UPGRADABLE
                recordingType: BandyerPlugin.recordingTypes.NONE, // MANUAL , AUTOMATIC
            },
            videoCallOption: {
                recordingType: BandyerPlugin.recordingTypes.NONE, // MANUAL , AUTOMATIC
            }
        },
        fileShare: true,
        whiteboard: true,
        screenShare: {
            inApp: true, // screenshare only the app 
            wholeDevice: true // screenshare the whole device
        },
        feedback: true
    },
    
    // optional you can set one or more of the following capabilities, by default callkit is enabled
    iosConfig: {
        voipHandlingStrategy: BandyerPlugin.voipHandlingStrategies.AUTOMATIC, // implement to be able to receive voips
        callkit: {
            enabled: true, // enable callkit on iOS 10+
            appIconName: "logo_transparent", // optional but recommended
            ringtoneSoundName: "custom_ringtone.mp3" // optional
        },
        fakeCapturerFileName: 'sample' // set this property to be able to execute on an ios simulator
    }
});

Plugin listen for errors/events

To listen for events and/or errors register Check the documentation here for a complete list.

Example:

bandyerPlugin.on(BandyerPlugin.events.callModuleStatusChanged, function (status) {});

Listening for VoIP push token

In order to get your device push token, you must listen for the BandyerPlugin.events.iOSVoipPushTokenUpdated event registering a callback as follows:

bandyerPlugin.on(BandyerPlugin.events.iOSVoipPushTokenUpdated, function (token) {
				// register the VoIP push token on your server
        });

The token provided in the callback is the string representation of your device token. Here's an example of a device token: dec105f879924349fd2fa9aa8bb8b70431d5f41d57bfa8e31a5d80a629774fd9

Plugin connect

To connect the plugin to the bandyer system you will need to provide a Session object. The session needs a userID and a function returning a promise with the access token for that user

bandyerPlugin.connect({
    userID: "usr_xxx",
    accessTokenProvider: (userId) => new Promise((success, error) => {
        // get token for user_xxx and invoke success or error depending on the result
        success("jwt_xxx");
    }),
});

Start a call

To make a call you need to specify some params.

Start call params

bandyerPlugin.startCall({
    callees: ['usr_yyy','usr_zzz'], //  an array of user ids of the users you want to call
    callType: BandyerPlugin.callTypes.AUDIO_VIDEO, // **[BandyerPlugin.callTypes.AUDIO | BandyerPlugin.callTypes.AUDIO_UPGRADABLE | BandyerPlugin.callTypes.AUDIO_VIDEO]** the type of the call you want to start
    recordingType: BandyerPlugin.recordingTypes.NONE // MANUAL , AUTOMATIC
});

Start a chat

To make a chat you need to specify some params.

Start chat params

bandyerPlugin.startChat('usr_yyy');// the user_id of the user you want to create a chat with

Set user details

This method will allow you to set your user details DB from which the sdk will read when needed to show the information.

Be sure to have this always up to date, otherwise if an incoming call is received and the user is missing in this set the user ids will be printed on the UI.

bandyerPlugin.addUsersDetails([
    {userID: "usr_yyy", firstName: "User1Name", lastName: "User1Surname"},
    {userID: "usr_zzz", firstName: "User2Name", lastName: "User2Surname"},
]);

Remove all user details

This method will allow you to remove all the user info from the local app DB.

bandyerPlugin.removeUsersDetails();

Set user details format

This method will allow you to specify how you want your user details to be displayed.

Be aware that you can specify only keywords which exist in the UserDetails type.

For example: if you wish to show only the firstName while your dataset contains also the lastName you may change it here.

bandyerPlugin.setUserDetailsFormat({
    default: "${firstName} ${lastName}",
    androidNotification: "${firstName} ${lastName}" // optional if you wish to personalize the details in the notification.
});

Remove all the cached info in preferences and DBs

bandyerPlugin.clearUserCache();

Android change display mode

This method is useful for use-cases where you need to show a prompt and don't want it to be invalidated by the call going into pip. For example: if you wish to show fingerprint dialog you should first put the current call in background, execute the fingerprint validation and then put back the call in foreground.

bandyerPlugin.setDisplayModeForCurrentCall(CallDisplayMode.FOREGROUND); // CallDisplayMode.FOREGROUND | CallDisplayMode.FOREGROUND_PICTURE_IN_PICTURE | CallDisplayMode.BACKGROUND

Verify user

To verify a user for the current call.

bandyerPlugin.verifyCurrentCall(true);

iOS Notifications

The plugin supports on_call_incoming notification. You will need to set the voipHandlingStrategy and subscribe to iOSVoipPushTokenUpdated event to receive the voip token to use on your backend to notify the plugin.

Android Notifications

The plugin supports only on_call_incoming and on_message_sent notification types

You may add the following configuration under platform android in your config.xml. This will add our default notification handling which requires payload and user_token keys to be defined.

<config-file parent="/manifest/application" target="app/src/main/AndroidManifest.xml">
    <service android:name="com.bandyer.cordova.plugin.notifications.BandyerNotificationService" android:enabled="true" android:exported="false" android:permission="android.permission.BIND_JOB_SERVICE">
        <intent-filter>
            <action android:name="com.bandyer.NotificationEvent" />
            <!--//////// PATH to the object containing the payload, and user_token /////////-->
            <data android:path="message.kaleyra" />
        </intent-filter>
    </service>
</config-file>

Example of acceptable payload

{
  "google.delivered_priority":"high",
  "content-available":"1",
  "google.sent_time":1663347601917,
  "google.ttl":60,
  "google.original_priority":"high",
  "from":"320",
  "title":"",
  "google.message_id":"0:1123%ac212d7bf9fd7ecd",
  "message":"{\"kaleyra\":{\"payload\":{\"event\":\"on_call_incoming\",\"room_id\":\"room_b36f162\",\"data\":{\"initiator\":\"user1\",\"users\":[{\"user\":{\"userAlias\":\"user2\"},\"status\":\"invited\"},{\"user\":{\"userAlias\":\"user1\"},\"status\":\"invited\"}],\"roomAlias\":\"room_b37a64c6f162\",\"options\":{\"duration\":0,\"record\":true,\"recordingType\":\"manual\",\"recording\":\"manual\",\"creationDate\":\"2022-09-16T17:00:01.457Z\",\"callType\":\"audio_upgradable\",\"live\":true}}},\"user_token\":\"eyJhtokenksadfjoiasdjfoaidjfsoasidjfoi\"}}",
  "google.c.sender.id":"320"
}