Player Backgrounding Reference (iOS)

By default, iOS pauses audio and video playback when an application transitions to the background. However, media playback applications often need to continue playing content even when in the background. iOS offers several options to adjust this functionality to align with the specific needs of an application.

This reference explains the methods for controlling player behaviors, such as ad playback, audio output, and media playback, while an application runs in the background on iOS. Correctly implementing these configurations ensures an uninterrupted media playback experience for users.

Backgrounding Configurations

Configure audio playback

🚧
Enable background capabilities must be enabled to permit background audio playback.

The foundation for background audio playback on iOS is the AVAudioSession. All apps interact with audio through an AVAudioSession instance, which manages the app's audio behaviors and policies.

By default, the audio session pauses audio when the app is backgrounded, or the screen is locked. To override this behavior, you must set an appropriate AVAudioSession category for your use case.

The following example shows how to configure an audio session.

When using the .playback category, the app audio continues even when the device is silenced or locked. The mode helps iOS to optimize performance and is not required for background audio playback.

import AVFoundation

func setAudioSessionCategory(
    to         category: AVAudioSession.Category,
    withMode   mode    : AVAudioSession.Mode?           = nil,
    andOptions options : AVAudioSession.CategoryOptions = [.allowAirPlay, .allowBluetooth])
{
    do {
        let audioSession = AVAudioSession.sharedInstance()
        if let mode {
            // Set category and mode if mode is specified
            try audioSession.setCategory(category, mode: mode, options: options)
        } else {
            // Set only category if mode is not specified
            try audioSession.setCategory(category, options: options)
        }
        try audioSession.setActive(true)
    } catch {
        print("Error setting AVAudioSession category and mode: \(error.localizedDescription)")
    }
}

// Example usage:
setAudioSessionCategory(to: .playback) // For playback scenarios
setAudioSessionCategory(to: .ambient)  // For ambient sound scenarios

// If you want to specify a mode as well:
setAudioSessionCategory(to: .playback, withMode: .moviePlayback) // Example of setting both category and mode

#import <AVFoundation/AVFoundation.h>

@interface AudioSessionHelper : NSObject

+ (void)setAudioSessionCategory:(AVAudioSessionCategory)category;
+ (void)setAudioSessionCategory:(AVAudioSessionCategory)category withMode:(AVAudioSessionMode)mode;
+ (void)setAudioSessionCategory:(AVAudioSessionCategory)category withMode:(AVAudioSessionMode)mode andOptions:(AVAudioSessionCategoryOptions)options;

@end

@implementation AudioSessionHelper

+ (void)setAudioSessionCategory:(AVAudioSessionCategory)category {
    [self setAudioSessionCategory:category withMode:nil andOptions:AVAudioSessionCategoryOptionAllowAirPlay | AVAudioSessionCategoryOptionAllowBluetooth];
}

+ (void)setAudioSessionCategory:(AVAudioSessionCategory)category withMode:(AVAudioSessionMode)mode {
    [self setAudioSessionCategory:category withMode:mode andOptions:AVAudioSessionCategoryOptionAllowAirPlay | AVAudioSessionCategoryOptionAllowBluetooth];
}

+ (void)setAudioSessionCategory:(AVAudioSessionCategory)category withMode:(AVAudioSessionMode)mode andOptions:(AVAudioSessionCategoryOptions)options {
    AVAudioSession *audioSession = [AVAudioSession sharedInstance];
    NSError *error = nil;
    
    if (mode) {
        [audioSession setCategory:category mode:mode options:options error:&error];
    } else {
        [audioSession setCategory:category options:options error:&error];
    }
    
    if (!error) {
        [audioSession setActive:YES error:&error];
    }
    
    if (error) {
        NSLog(@"Error setting AVAudioSession category and mode: %@", error.localizedDescription);
    }
}

@end

Enable background capabilities

In addition to configuring the audio session, you must explicitly enable the capability in your app's project settings to play background audio. Apple requires developers to manually grant permissions for features like background audio, AirPlay, and Picture in Picture, as they can impact user experience, device resource allocation, and security.

📘
Follow Apple's instructions to enable these capabilities.

Configure ad playback

By default, iOS pauses ad playback when the app is backgrounded. You can configure the JWAdvertisingConfig.adSettings to override this behavior if necessary.

The following example shows how to configure the ad settings to allow background playback using .allowsBackgroundPlayback(true). This configuration is then applied to the overall advertising configuration used to set up the player.

let adSettingsBuilder = JWAdSettingsBuilder()
adSettingsBuilder.allowsBackgroundPlayback(true)
let adSettings = adSettingsBuilder.build()

let adConfigBuilder = JWAdsAdvertisingConfigBuilder()
adConfigBuilder.adSettings(adSettings)

try {
 let adConfig = try adConfigBuilder.build()
 // setup player config with this ad config.
} catch {
 /// handle errors elegantly
}

JWAdSettingsBuilder *adSettingsBuilder = [[JWAdSettingsBuilder alloc] init];
[adSettingsBuilder allowsBackgroundPlayback:true];
    
JWAdSettings *adSettings = [adSettingsBuilder build];

JWError *error;
JWAdsAdvertisingConfigBuilder *builder = [[JWAdsAdvertisingConfigBuilder alloc] init];
[builder adSettings:adSettings];
JWAdvertisingConfig *adConfig = [builder buildAndReturnError:&error];

Handle media playback

With the appropriate audio session, background capabilities, and ad configurations set, media playback will continue when your app is backgrounded. To override this default behavior, you can call pause or stop in the applicationDidEnterBackground(_:) method of your AppDelegate.

💡
Apple’s UIApplicationDelegate reference provides more information on responding to app lifecycle events.

FAQ

What steps should be taken to troubleshoot background playback issues in an app?

You can use the following approaches to troubleshooting background playback issues:

Verify the background capabilities. Double-check that you have enabled the required background capabilities (Audio, AirPlay, Picture in Picture) for your app target in Xcode.
Check the audio playback configuration. Ensure you have set the appropriate AVAudioSession category and mode as shown in the Configure audio playback section, and that you are setting it early in your app's lifecycle.
Handle audio interruptions. Implement proper handling of audio interruptions (such as incoming calls) to resume playback after the interruption ends.
Test on a physical device. While simulators provide some background support, it's recommended to thoroughly test your background playback implementation on a physical iOS device.