Configuration Loading with a JSON Object Reference

You can use a JSON object to define several player configuration settings. Using a JSON object to define player configuration settings offers several benefits:

Maintenance: Allows making player changes without resubmitting the app to the App Store
Efficient Development: Facilitates defining player configuration settings through a single builder method
Caching: Permits caching player configurations in memory or on a web server

Load a JSON Configuration

Use the following steps to initialize a player with a JSON configuration:

Define a JSON object.

Format	Description
data Data	Enables caching a data blob downloaded from your own web service and allows the iOS SDK to deserialize the JSON This is a data blob that contains serialized JSON. Using this format removes the need for you to convert the Data to a JSONObject yourself.
json [String : Any]	Enables creating the JSON as a dictionary within the code

Format

Description

data Data

Enables caching a data blob downloaded from your own web service and allows the iOS SDK to deserialize the JSON

This is a data blob that contains serialized JSON. Using this format removes the need for you to convert the Data to a JSONObject yourself.

json [String : Any]

Enables creating the JSON as a dictionary within the code

Through JWPlayerConfigurationBuilder(), load a JSON configuration to configure the player.

// build your config
do {
 // This step could be done in your application as preloading,
 // and stored in memory.
 let url = URL(string:"url_of_your_config")!
 let jsonData = Data(contentsOf: url)

 // Create the config
 let config = try builder.configuration(data: jsonData).build()
 player.configurePlayer(with: config)
} catch {
    // Handle build errors
}

// build your config
do {
 let json: JSONObject = [
   "file": "yourvideo.mp4",
   "title": "video title"
 ]
 let config = try builder.configuration(json: json).build()
 player.configurePlayer(with: config)
} catch {
    // Handle build errors
}

iOS Specific Properties

The iOS SDK has support for the following properties.

(root)

Property	Description
allowsBackgroundPlayback Bool	Defines VAST ads playback behavior when the app is in the background Possible Values: `true`: VAST ads are heard and continue playing while the app is in the background. `false`: VAST ads stop playing while the app is in the background.
externalMetadata [JSONObject]	Defines external metadata to be triggered at a designated time See: externalMetadata object
externalPlaybackSettings JSONObject	Defines properties which change how external playback is affected with AirPlay devices See: externalPlaybackSettings object
locale String	ISO 639-1 locale associated with the caption track

externalMetadata

Property	Description
endTime* Double	End time of the cue, expressed as a number of seconds from the beginning of the content
identifier* String	Unique identifier used to represent the metadata cue
startTime* Double	Start time of the cue, expressed in seconds from the beginning of the content

externalPlaybackSettings

Format Description

Format	Description
playbackEnabled Bool	Indicates whether the player allows switching to external playback mode See also: allowsExternalPlayback
usesExternalPlaybackWhileExternalScreenIsActive Bool	Indicates whether the player should automatically switch to external playback mode while the external screen mode is active See also: usesExternalPlaybackWhileExternalScreenIsActive
videoGravity String	Indicates how the layer displays video content within its bounds Possible Values: `resize`: Stretches the video to fill the bounds of the layer `resizeAspect`: Preserves the aspect ratio of the video and fits it within bounds of the layer `resizeAspectFill`: Preserves the aspect ratio of the video and fills the bounds of the layer See also: videoGravity

playbackEnabled Bool

Indicates whether the player allows switching to external playback mode

Playlist items

You can customize how VoiceOver announces a playlist item's title and description by defining accessibility labels and hints. Labels control what VoiceOver reads, while hints provide optional additional context.

Keep hints brief and nonessential because viewers can disable them. If the visible description is empty, adding a custom description label does not make the description available to VoiceOver.

For example, if the visible description is 3m, use 3 minutes as the accessibility label to prevent VoiceOver from interpreting the description as three meters.

📘
When configuring a single item at the root, define these properties alongside file, title, and description.

{
  "playlist": [
    {
      "file": "https://example.com/video.mp4",
      "title": "Daily upd.",
      "description": "3m summary",
      "titleAccessibilityLabel": "Daily update",
      "titleAccessibilityHint": "Latest news",
      "descriptionAccessibilityLabel": "3 minute summary",
      "descriptionAccessibilityHint": "Summary length"
    }
  ]
}

Property	Description
descriptionAccessibilityHint String	VoiceOver hint that provides additional context for the description If omitted, empty, or whitespace-only, no custom hint is announced.
descriptionAccessibilityLabel String	Custom label that specifies what VoiceOver reads without changing the visible description If omitted, empty, or whitespace-only, the default accessibility label is used.
titleAccessibilityHint String	VoiceOver hint that provides additional context for the title If omitted, empty, or whitespace-only, no custom hint is announced.
titleAccessibilityLabel String	Custom label that specifies what VoiceOver reads without changing the visible title If omitted, empty, or whitespace-only, the default accessibility label is used.

💡
To configure these values in Swift, use the matching JWPlayerItemBuilder methods.

Captions

The iOS SDK supports all captions options.