< Back to Package Overview
Backgrounding and battery considerations
Different mobile operating systems have different implementation of power management and background requirements on applications. There is a tradeoff between power consumption and the level of service a background application receives. Client SDK keeps a balance between power consumption and service availability requirements.
Power Management Implementation
Client SDK has implemented the following requirements:
- While there is an active call, the application put in the background has full access to the system's resources and continues to consume power itself.
- While there is no active call, Client SDK is able to receive network events, wake up and process network messages before going back to the sleep mode in the background.
- High performance Wifi lock is obtained while on a call (high performance lock is acquired outside the event loop class based on call activity events).
- While not on a call, normal Wifi lock is obtained in order to keep the antenna power up enough to receive network notifications.
- When a network message is received, the Android system wakes up the event loop thread of Client SDK.
- When the event loop wakes up, it acquires wake lock to keep the CPU up to process the message and do anything else that is required before going back to the sleep mode.
- Once wake lock is acquired, the event loop thread is not suspended until wake lock is released.
- The event loop thread processes incoming messages, activates timers, sends network messages, posts callbacks and does anything else that is needed for the operation. Once the processing is complete and the event loop thread is ready to sleep, it releases wake lock.
- The event loop takes advantage of the Android alarm mechanism to request the system to wake up the event loop upon expiry of a timer. For instance, if there is a SIP registration timer that is to be refreshed in 1134 seconds, the Android alarm is set for the system to wake up the event loop thread in 1134 seconds.
In summary:
- If media is streamed (e.g., on a call), high performance Wifi lock is acquired regardless of whether the application is in the background or foreground.
- While high performance lock is acquired, regular Wifi lock is not needed. When high performance lock is released, regular Wifi lock is acquired.
- If media is not streamed (e.g., not on a call) and has connection to the server, regular Wifi lock is used regardless of foreground or background. This is done in order to receive network messages. The wifi lock is held until the connection is closed. As long as the antenna is used, Wifi lock is not released.
- If the application is idle and attempting to connect to the server, during connection attempts Wifi lock is acquired. While waiting for connection retry, unless the timer is expired, the lock is released, but the Android alarm starts to wake up the event loop when it is time to retry connection to the server.
Detecting when application is in the background
Detecting application's background state is based on the state of MainActivity. MainActivity is the activity that hosts most of user interface. Such standard lifecycle methods as onResume() and onPause() are hooked up enabling to update the visibility state.
Service Specific Design Decisions
Different areas of Client SDK functionality were examined to determine whether a given functionality should work in full service mode, limited service mode or be disabled while the application is in the background. As stated at the beginning of this section, the decision is based on two criteria: power consumption management and the level of service that is appropriate while in the background.
Note that when the application is automatically put in the background, for example, due to incoming cellular call activity, the (VoIP) application cannot provide any media service. Any active call is automatically put on hold through SIP renegotiation. This is different from when the user puts the application in the background, for example, to bring up another application. The following decisions about how active calls are treated, are not applicable to cellular activity scenarios.
| Service type |
Level of service |
Notes |
| SIP registration |
Normal |
Registration is required in order to receive incoming network events.
Registrations are refreshed based on Android alarms. |
| SIP subscriptions |
Normal |
While in the background, the ccs-profile, reg, dialog, message waiting and feature status notifications can be received. Once received, the event loop thread wakes up to process the message. |
| Outgoing calls |
Normal |
While there is an active outgoing call or the call is in progress, the call is allowed to proceed while the application is put in the background. |
| Incoming calls |
Normal |
The event loop wakes up to process incoming SIP INVITE and reports the incoming call to the application thread for alerting. |
| Active p2p/conference call |
Normal |
Media streams stay alive. |
| Held p2p/conference call |
Signaling only |
Held call has no media. It remains held at signaling level while in the background. |
| Remotely held call |
Normal |
A remote hold operation may result in music on hold service. In this case, music on hold stream is played while in the background.
If there is no music on hold service provided by the network, the media stream remains removed, the call stays in the background with its signaling enabled.
When the remote party unholds the call, the incoming unhold request wakes up the application. Assuming there is no other active VoIP call, the media can be added to the application while in the background. |
| Presence subscription |
None |
When in the background, presence subscription is stopped for all contacts (except self-presence) in order to prevent presence notifications from waking up the application and consuming battery power. |
| Presence publish |
None |
Automatic presence publish (e.g., on the phone or idle) can be done while in the background. The trigger for this will be the changed call state. When the call state changes, presence publish is sent out. |
| PPM/HTTP-based services |
None |
Socket connection remains live until after pending requests are completed. The socket connection is then torn down, and no new request is allowed while in the background. |
Background and Suspend/Resume Interactions
Network disruption and restoration may occur while the application is in the foreground or background. Network connectivity monitoring reports all modules to receive information on when the network connection is lost or restored. Depending on the demands for different services and the background/foreground state of the application, there are various actions taken by Client SDK as documented below:
![Network Interruption and Restoration while in the foreground]()
![Application goes to background while in suspended mode]()
![Network Restored While in Background]()
![Network Suspended and Restored While in Background]()
![Transition to Suspended while in Background]()
Android 8.0 (API level 26+) limitation
API level 26 is introducing new limits on when applications can execute in the background.
Even if your application targets an API level lower than 26, users can enable most of these restrictions from the Settings screen.
To workaround it use a persistent foreground service while your application is logged in to be able to receive notifications and recover connections in the background.
