.. _Android ConnectionService integration:

=====================================
Android ConnectionService integration
=====================================

This article explains the steps required to integrate libSoftphone with Android ConnectionService API in SelfManaged mode.
Refer to `Official Android Documentation <https://developer.android.com/guide/topics/connectivity/telecom/selfManaged>`_ for more information on ConnectionService API.


Step 1: Implement ConnectionService
-----------------------------------

LibSoftphone takes care of all the heavy lifting around `ConnectionService  <https://developer.android.com/reference/android/telecom/ConnectionService>`_  implementation for you.
However, the host app needs provide a Service derived from ``cz.acrobits.libsoftphone.telecom.ConnectionService`` that ensures that libSoftphone is initialized whenever ``ConnectionService::onCreate()`` is invoked.

Implement your simple ConnectionService as follows:

      .. code-block:: java
        :linenos:
    
        public class MyConnectionService extends cz.acrobits.libsoftphone.telecom.ConnectionService
        {
            @Override
            public void onCreate()
            {
                super.onCreate();
                // start() method should ensure that libSoftphone is initialized and running
                DemoPhoneApplication.start();
            }
        }


Step 2: Add ConnectionService implementation to manifest
-------------------------------------------------------------

Add your ConnectionService implementation to manifest:

      .. code-block:: xml
        :linenos:
    
        <service android:name=".MyConnectionService"
            android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE"
            android:exported="true">
            <intent-filter>
                <action android:name="android.telecom.ConnectionService" />
            </intent-filter>
        </service>


Step 3: Add permissions to manifest
------------------------------------

You'll need to add the following permissions into your app's manifest:

      .. code-block:: xml
        :linenos:
    
         <uses-permission android:name="android.permission.MANAGE_OWN_CALLS"/>
         <uses-permission android:name="android.permission.READ_PHONE_STATE"/>

Step 4: Request Phone permissions at runtime
------------------------------------------------

Request the Phone permission before using the Telecom API:

      .. code-block:: java
        :linenos:
    
        String[] permissions;
        if(Build.VERSION.SDK_INT >= 31)
            permissions = new String[]{Manifest.permission.READ_PHONE_STATE, Manifest.permission.READ_PHONE_NUMBERS};
        else
            permissions = new String[]{Manifest.permission.READ_PHONE_STATE};

        ActivityCompat.requestPermissions(this, permissions, PHONE_PERMISSION_REQUEST_CODE);


Step 5: Register your PhoneAccount
-------------------------------

Register your app's Telecom API `PhoneAccount  <https://developer.android.com/reference/android/telecom/PhoneAccount>`_ on app start:

      .. code-block:: java
        :linenos:
    
        Context context = AndroidUtil.getApplicationContext();
        // create some account icon, e.g. from app icon
        Icon icon = Icon.createWithResource(context, R.mipmap.icon);
        String accountName = "MyConnectionServiceAccount";
        ComponentName serviceComponent = new ComponentName(context, MyConnectionService.class);
        TelecomUtil.registerCallingAccount(serviceComponent, true);

Step 6: Make sure Self Managed Call Integration is enabled
----------------------------------------------------------

The value of the ``callIntegrationMode`` preference key needs to be set to ``bestEffort``.
The ``bestEffort`` mode will attempt to use the Self Managed ConnectionService when possible:

* On APIs below 28, it will not use ConnectionService at all due to compatibility reasons.
* On APIs 28+, it will it will attempt to establish a ConnectionService; and in case of failure:
  * If an outgoing call fails to establish a ConnectionService, it will still go through without ConnectionService integration.
  * If an incoming call fails to establish a ConnectionService, it will be automatically rejected.