manur / ionic-plugin-callkit

Ionic/Cordova plugin for CallKit

ionic-plugin-callkit

Ionic/Cordova plugin for CallKit.

On Android it mimics CallKit calls, but the callscreen itself should be displayed by the Ionic/Cordova app. On Android the main activity must be called as "MainActivity". You can check this in your AndroidManifest.xml file, the first activity tag under application tag should have android:name="MainActivity" attribute.

On iOS use resources/Ringtone.caf as ringtone (optional, uses system default ringtone if not found) automatically looped On Android res/raw/ringtone.mp3 or res/raw/ringtone.ogg is used (filename is lowercase, if not found then plays the default system ring), use ANDROID_LOOP metadata to loop the ogg ringtone

Install

cordova plugin add https://github.com/Taracque/ionic-plugin-callkit.git

How to use

Example (only one call tracked at a time, this code is just a hint, see Call Flow description below):

var callKitService = new CallKitService();
function CallKitService() {
  var callKit;
  var callUUID;

  /**
   * Determine wheter the plugin is available.
   *
   * @return {boolean} `true` if the plugin is available.
   */
  function hasCallKit() {
    return typeof CallKit !== "undefined" && callKit;
  }

  /**
   * Wrapper for functions which cannot be executed without the plugin.
   *
   * @param {Function} fn Function to be called only if plugin is available.
   *
   * @return {Function} A function running `fn` (with its arguments), if plugin is available.
   */
  function execWithPlugin(fn) {
    return function() {
      if (!hasCallKit()) {
        console.error('callkit plugin not available');
        return;
      }

      fn.apply(this, Array.prototype.slice.call(arguments));
    };
  }

  return {
    register: function(callChanged, audioSystem) {
      if (typeof CallKit !== "undefined") {
        callKit = new CallKit();
        callKit.register(callChanged, audioSystem);
      }
    },
    reportIncomingCall: execWithPlugin(function(name, params) {
      callKit.reportIncomingCall(name, params, function(uuid) {
        callUUID = uuid;
      });
    }),
    startCall: execWithPlugin(function(name, isVideo) {
      callKit.startCall(name, isVideo, function(uuid) {
        callUUID = uuid;
      });
    }),
    callConnected: execWithPlugin(function(uuid) {
      callKit.callConnected(callUUID);
    }),
    endCall: execWithPlugin(function(notify) {
        callKit.endCall(callUUID, notify);
    }),
    finishRing: execWithPlugin(function() {
        callKit.finishRing();
    })
  };
}

API

Plugin initialization:

callKitService.register( callChanged, audioSystem )

Initializes the plugin a register callback codes.

callChanged = function(obj) {
  < your code >
}

callback is called with an object, which contains the following properties:

• uuid - The UUID of the call
• handle - The handle of the call (the string what is displayed on the phone) String
• isOutgoing - is the call outgoing? Boolean
• isOnHold - is the is on hold? Boolean
• hasConnected - is it connected? Boolean
• hasEnded - is it eneded? Boolean
• hasStartedConnecting - is it started connecting (i.e. user pressed the accept button)? Boolean
• endDate - when the call is ended? String (ISO8601 format date time)
• connectDate - when the call is connected? String (ISO8601 format date time)
• connectingDate - when the call started to connect? String (ISO8601 format date time)
• duration - call duration Double

audioSystem = function(message) {
  < your code >
}

• message: String - can be startAudio, stopAudio, configureAudio

Use

callKitService.reportIncomingCall(name, params);

to activate the call screen.

• name: String - the caller name, which should displayed on the callscreen
• params: Object - with the following keys
  • video : set to true if this call can be a video call
  • group : set to true if call supports grouping (default: false)
  • ungroup : set to true if call supports ungrouping (default: false)
  • dtmf : set to true if call supports dtmf tones (default: false)
  • hold : set to true if call supports hold (default: false)

callKitService.startCall(name, isVideo);

to report an initiated outgoing call to the system

• name: String - the callee name, which should displayed in the call history.
• isVideo: boolean - set to true if this call can be a video call.

Use

callKitService.callConnected(uuid);

to report the system that the outgoing call is connected.

• uuid: String - Uniquie identifier of the call.

Use

callKitService.endCall(uuid, notify);

to let the system know, the call is ended.

• uuid: String - Uniquie identifier of the call. In case of incoming call, it is provided by the reportIncomingCall onSuccess callback.
• notify: Boolean - If true, sends a local notification to the system about the missed call.

On android the callscreen should be displayed by the app. Use

callKitService.finishRing(uuid, notify);

to stop the ringtone playing.

• uuid: String - Uniquie identifier of the call. In case of incoming call, it is provided by the reportIncomingCall onSuccess callback.

Call Flows:

Incoming:

1. call reportIncomingCall
2. callChanged gets called with hasStartedConnecting=true
3. use finishRing to finish the ring (only needed on android)
4. connect the call, and once connected user callConnected call
5. once the call is finished user endCall

Outgoing:

1. call startCall
2. initiate call
3. once the call is connected use callConnected
4. once the call is finished use endCall