sync with master

Author: Sylvain Boily

MIGRATION_v3_v4.md

@@ -0,0 +1,20 @@
+# Migration from CallKeep v3 to v4
+
+The `reportNewIncomingCall` method on iOS is now more consistent.
+
+Please update your `AppDelegate.m` file with this new signature:
+
+```objc
+[RNCallKeep reportNewIncomingCall: uuidString
+                           handle: handle
+                       handleType: handleType
+                         hasVideo: YES
+              localizedCallerName: localizedCallerName
+                  supportsHolding: YES
+                     supportsDTMF: YES
+                 supportsGrouping: YES
+               supportsUngrouping: YES
+                      fromPushKit: YES
+                          payload: nil
+            withCompletionHandler: nil];
+```

README.md

@@ -47,7 +47,14 @@ const options = {
     cancelButton: 'Cancel',
     okButton: 'ok',
     imageName: 'phone_account_icon',
-    additionalPermissions: [PermissionsAndroid.PERMISSIONS.example]
+    additionalPermissions: [PermissionsAndroid.PERMISSIONS.example],
+    // Required to get audio in background when using Android 11
+    foregroundService: {
+      channelId: 'com.company.my',
+      channelName: 'Foreground service for my app',
+      notificationTitle: 'My app is running on background',
+      notificationIcon: 'Path to the resource icon of the notification',
+    }, 
   }
 };
 
@@ -63,7 +70,7 @@ RNCallKeep.setup(options).then(accepted => {});
     - `ringtoneSound`: string (optional)
       If provided, it will be played when incoming calls received; the system will use the default ringtone if this is not provided
     - `includesCallsInRecents`: boolean (optional)
-      If provided, calls will be shown in the recent calls when true and not when false (ios 11 and above)
+      If provided, calls will be shown in the recent calls when true and not when false (ios 11 and above) (Default: true)
     - `maximumCallGroups`: string (optional)
       If provided, the maximum number of call groups supported by this application (Default: 3)
     - `maximumCallsPerCallGroup`: string (optional)
@@ -124,6 +131,30 @@ Eg: When your used log out (or the connection to your server is broken, etc..),
 RNCallKeep.setAvailable(true);
 ```
 
+### setForegroundServiceSettings
+_This feature is available only on Android._
+
+Configures the [Foreground Service](https://developer.android.com/about/versions/11/privacy/foreground-services) used for Android 11 to get microphone access on background.
+Similar to set the `foregroundService` key in the `setup()` method.
+
+```js
+RNCallKeep.setForegroundServiceSettings({
+    channelId: 'com.company.my',
+    channelName: 'Foreground service for my app',
+    notificationTitle: 'My app is running on background',
+    notificationIcon: 'Path to the resource icon of the notification',
+});
+```
+
+### canMakeMultipleCalls
+_This feature is available only on Android._
+
+Disable the "Add call" button in ConnectionService UI.
+
+```js
+RNCallKeep.canMakeMultipleCalls(false); // Enabled by default
+```
+
 - `active`: boolean
   - Tell whether the app is ready or not
 
@@ -156,13 +187,33 @@ RNCallKeep.isCallActive(uuid);
 - `uuid`: string
   - The `uuid` used for `startCall` or `displayIncomingCall`
 
+
+### getCalls
+
+_This feature is available only on IOS._
+
+Returns a Promise. The result will be an array with all current calls and their states.
+
+```js
+RNCallKeep.getCalls();
+
+response:
+[{
+  callUUID: "E26B14F7-2CDF-48D0-9925-532199AE7C48"
+  hasConnected: true
+  hasEnded: false
+  onHold: false
+  outgoing: false
+}]
+```
+
 ### displayIncomingCall
 
 Display system UI for incoming calls
 
-````js
+```js
 RNCallKeep.displayIncomingCall(uuid, handle, localizedCallerName);
-````
+```
 
 - `uuid`: string
   - An `uuid` that should be stored and re-used for `stopCall`.
@@ -177,9 +228,15 @@ RNCallKeep.displayIncomingCall(uuid, handle, localizedCallerName);
 - `hasVideo`: boolean (optional, iOS only)
   - `false` (default)
   - `true` (you know... when not false)
+- `options`: object (optional)
+  - `ios`: object
+    - `supportsHolding`: boolean (optional, default true)
+    - `supportsDTMF`: boolean (optional, default true)
+    - `supportsGrouping`: boolean (optional, default true)
+    - `supportsUngrouping`: boolean (optional, default true)
+  - `android`: object (currently no-op)
 
 ### answerIncomingCall
-_This feature is available only on Android._
 
 Use this to tell the sdk a user answered a call from the app UI.
 
@@ -232,6 +289,14 @@ RNCallKeep.updateDisplay(uuid, displayName, handle)
   - Name of the caller to be displayed on the native UI
 - `handle`: string
   - Phone number of the caller
+- `options`: object (optional)
+  - `ios`: object
+    - `hasVideo`: boolean (optional)
+    - `supportsHolding`: boolean (optional)
+    - `supportsDTMF`: boolean (optional)
+    - `supportsGrouping`: boolean (optional)
+    - `supportsUngrouping`: boolean (optional)
+  - `android`: object (currently no-op)
 
 ### endCall
 
@@ -388,6 +453,29 @@ const options = {
 RNCallKeep.hasDefaultPhoneAccount(options);
 ```
 
+### checkPhoneAccountEnabled
+
+Checks if the user has set a default [phone account](https://developer.android.com/reference/android/telecom/PhoneAccount) and it's enabled.
+
+It's useful for custom permission prompts. It should be used in pair with `registerPhoneAccount`
+Similar to `hasDefaultPhoneAccount` but without trigering a prompt if the user doesn't have a phone account.
+
+_This feature is available only on Android._
+
+```js
+RNCallKeep.checkPhoneAccountEnabled();
+```
+
+### isConnectionServiceAvailable
+
+Check if the device support ConnectionService.
+
+_This feature is available only on Android._
+
+```js
+RNCallKeep.checkPhoneAccountEnabled();
+```
+
 ### backToForeground
 _This feature is available only on Android._
 
@@ -538,9 +626,14 @@ Called as soon as JS context initializes if there were some actions performed by
 
 Since iOS 13, you must display incoming call on receiving PushKit push notification. But if app was killed, it takes some time to create JS context. If user answers the call (or ends it) before JS context has been initialized, user actions will be passed as events array of this event. Similar situation can happen if user would like to start a call from Recents or similar iOS app, assuming that your app was in killed state.
 
+**NOTE: You still need to subscribe / handle the rest events as usuall. This is just a helper whcih cache and propagate early fired events if and only if for "the native events which DID fire BEFORE js bridge is initialed", it does NOT mean this will have events each time when the app reopened.**
+
 ```js
+// register `didLoadWithEvents` somewhere early in your app when it is ready to handle callkeep events.
+
 RNCallKeep.addEventListener('didLoadWithEvents', (events) => {
-  // see example usage in https://github.com/react-native-webrtc/react-native-callkeep/pull/169
+  // `events` is passed as an Array chronologically, handle or ignore events based on the app's logic
+  // see example usage in https://github.com/react-native-webrtc/react-native-callkeep/pull/169 or https://github.com/react-native-webrtc/react-native-callkeep/pull/205
 });
 ```
 
@@ -724,7 +817,7 @@ In some case your application can be unreachable :
 - when the user kill the application
 - when it's in background since a long time (eg: after ~5mn the os will kill all connections).
 
-To be able to wake up your application to display the incoming call, you can use [https://github.com/ianlin/react-native-voip-push-notification](react-native-voip-push-notification) on iOS or BackgroundMessaging from [react-native-firebase](https://rnfirebase.io/docs/v5.x.x/messaging/receiving-messages#4)-(Optional)(Android-only)-Listen-for-FCM-messages-in-the-background).
+To be able to wake up your application to display the incoming call, you can use [https://github.com/ianlin/react-native-voip-push-notification](react-native-voip-push-notification) on iOS or BackgroundMessaging from [react-native-firebase](https://rnfirebase.io/messaging/usage#receiving-messages)-(Optional)(Android-only)-Listen-for-FCM-messages-in-the-background).
 
 You have to send a push to your application, like with Firebase for Android and with a library supporting PushKit pushes for iOS.
 
@@ -743,10 +836,28 @@ Since iOS 13, you'll have to report the incoming calls that wakes up your applic
   // NSString *handle = @"caller number here";
   // NSDictionary *extra = [payload.dictionaryPayload valueForKeyPath:@"custom.path.to.data"]; /* use this to pass any special data (ie. from your notification) down to RN. Can also be `nil` */
 
-  [RNCallKeep reportNewIncomingCall:uuid handle:handle handleType:@"generic" hasVideo:false localizedCallerName:callerName fromPushKit: YES payload:extra withCompletionHandler:completion];
+  [RNCallKeep reportNewIncomingCall: uuid
+                             handle: handle
+                         handleType: @"generic"
+                           hasVideo: NO
+                localizedCallerName: callerName
+                    supportsHolding: YES
+                       supportsDTMF: YES
+                   supportsGrouping: YES
+                 supportsUngrouping: YES
+                        fromPushKit: YES
+                            payload: extra
+              withCompletionHandler: completion];
 }
 ```
 
+## Android 11
+
+Since Android 11, your application [requires to start a foregroundService](https://developer.android.com/about/versions/11/privacy/foreground-services) in order to access the microphone in background.
+You'll need to upgrade your `compileSdkVersion` to `30` to be able to use this feature.
+
+You have to set the `foregroundService` key in the [`setup()`](#setup) method and add a `foregroundServiceType` in the [`AndroidManifest` file](docs/android-installation.md#android-common-step-installation).
+
 ## Debug
 
 ### Android

android/src/main/AndroidManifest.xml

@@ -3,7 +3,7 @@
 
     <uses-permission android:name="android.permission.CALL_PHONE" />
     <uses-permission android:name="android.permission.CAMERA" />
-    <uses-permission android:name="READ_PHONE_STATE"
+    <uses-permission android:name="android.permission.READ_PHONE_STATE"
                      android:maxSdkVersion="29" />
-    <uses-permission android:name="READ_PHONE_NUMBERS" />
+    <uses-permission android:name="android.permission.READ_PHONE_NUMBERS" />
 </manifest>

android/src/main/java/io/wazo/callkeep/Constants.java

@@ -17,4 +17,7 @@ public class Constants {
     public static final String EXTRA_CALL_UUID = "EXTRA_CALL_UUID";
     public static final String EXTRA_CALLER_NAME = "EXTRA_CALLER_NAME";
     public static final String EXTRA_HAS_VIDEO = "EXTRA_HAS_VIDEO";
+    // Can't use telecom.EXTRA_DISABLE_ADD_CALL ...
+    public static final String EXTRA_DISABLE_ADD_CALL = "android.telecom.extra.DISABLE_ADD_CALL";
+    public static final int FOREGROUND_SERVICE_TYPE_MICROPHONE = 128;
 }