How to Use forceKeepAlive

Technical guides
1

This article describes how to use NCEngine.forceKeepAlive when your iOS app keeps running in the background, such as during an audio or video call.

Default Behavior

By default, the SDK disconnects the IM connection after the app stays in the background for up to 2 minutes. This helps the app receive APNs push notifications in time after it is no longer active.

The exact disconnect timing depends on when iOS suspends or terminates the app process. Therefore, the actual timing may be affected by system lifecycle events such as UIApplicationWillTerminateNotification.

When to Enable forceKeepAlive

Enable forceKeepAlive only when your app is actively using a background keepalive capability. Set forceKeepAlive according to the actual lifecycle of that feature.

For example, your app may keep running in the background when it uses an audio or video call feature and enables the following Xcode capability:

  • Signing & Capabilities > Background Modes > Audio, AirPlay, and Picture in Picture

In this case:

  • Set forceKeepAlive to true when the keepalive feature starts.
  • Set forceKeepAlive to false when the keepalive feature ends.

forceKeepAlive does not make the app stay alive in the background by itself. If the app is not using an actual background keepalive feature, setting forceKeepAlive to true cannot keep the app alive and may delay timely receipt of APNs push notifications.

Do not keep forceKeepAlive enabled after the background keepalive feature ends. Otherwise, the SDK may keep the IM connection alive when the app should rely on APNs push notifications.

Swift

// When the audio or video call starts.
NCEngine.forceKeepAlive = true

// When the audio or video call ends.
NCEngine.forceKeepAlive = false

You can also set the initial value before SDK initialization:

let params = InitParams(appKey: "<#App Key#>")
params.forceKeepAlive = true
NCEngine.initialize(params)

Objective-C

// When the audio or video call starts.
NCEngine.forceKeepAlive = YES;

// When the audio or video call ends.
NCEngine.forceKeepAlive = NO;

You can also set the initial value before SDK initialization:

NCInitParams *params = [[NCInitParams alloc] initWithAppKey:@"<#App Key#>"];
params.forceKeepAlive = YES;
[NCEngine initializeWithParams:params];

Recommended Usage

Use forceKeepAlive as a runtime switch for a specific background keepalive scenario, not as a permanent SDK setting. Only set it to true while the app is actually kept alive by a feature such as an audio or video call.

For example:

  1. The user starts an audio or video call.
  2. The app enables the call-related background keepalive behavior.
  3. Set NCEngine.forceKeepAlive = true.
  4. The user ends the call.
  5. Set NCEngine.forceKeepAlive = false.

This keeps the IM connection behavior aligned with the app’s real background execution state.