Enable casting to Chromecast devices (iOS v3)

The Google Cast framework enables a viewer to stream video and audio content to a compatible TV or sound system. By enabling the Google Cast framework in your app, a viewer can use a cast button to stream your content to a Chromecast-enabled device on a shared network connection.

🚧

• The JWP iOS SDK supports casting to the Default Media Receiver and to Styled Media Receivers.
• Custom receivers are not officially supported. However, if the video playback implements the same interface used in the Default Media Receiver, you may be able to initiate a casting session with a custom receiver.
• To specify a receiver, set a media receiver app ID to the chromeCastReceiverAppID property of the JWCastController.
• Avoid calling the cast() method inside the onConnected delegate callback method, since it takes a finite amount of time for processes related to the established connection to resolve. If unavoidable, delaying the cast() call can be effective (such as using a Dispatch queue, for example).

📘

• The JWP iOS SDK does not maintain support for the Google Cast iOS SDK's UI elements.
• For example, rather than using a GCKUICastButton, you will need to implement your own cast button that calls JWP iOS SDK methods.
• An example of the above can be found in our Best Practice App in both Objective-C and Swift.

Add the dependency

1. In a text editor, open Podfile.
2. If you are using CocoaPods to manage dependencies, add google-cast-sdk (guest mode support) to your Podfile, as shown in the following code example. Be sure to use a Google Cast version that is compatible with your version of the iOS SDK and the proper Podfile syntax.
   
   As of iOS 13, instead of adding the google-cast-sdk dependency, you can add the google-cast-sdk-no-bluetooth (no guest mode support) non-bluetooth dependency to your Podfile. However, we strongly recommend using google-cast-sdk.
   
   If you are manually managing dependencies for your project, follow these manual setup instructions.

# Uncomment the next line to define a global platform for your project
platform :ios, '11.0'

target 'MyAwesomeProject' do
    # Comment the next line if you're not using Swift and don't want to use dynamic frameworks
    use_frameworks!

    # Pods for MyAwesomeProject
    pod 'JWPlayer-SDK', '3.19.1'
    pod 'google-cast-sdk', '4.4.5'
end

# Uncomment the next line to define a global platform for your project
platform :ios, '11.0'

target 'MyAwesomeProject' do
    # Comment the next line if you're not using Swift and don't want to use dynamic frameworks
    use_frameworks!

    # Pods for MyAwesomeProject
    pod 'JWPlayer-SDK', '3.19.1'
    pod 'google-cast-sdk-no-bluetooth', '4.4.5' 
end

Configure and enable casting

1. If you are using Xcode 10 and targeting iOS 12+, click the app target > Capabilities > Access WiFi Information. Click the toggle to ON to enable Access Wifi Information.
2. (Guest mode only) In the Info.plist for your app, add NSBluetoothAlwaysUsageDescription to create a Bluetooth access request. If you are using the google-cast-sdk-no-bluetooth dependency, you can skip this step.
3. In your app, create a JWCastController object and set its delegate. The delegate must adhere to the JWCastingDelegate protocol and implement its delegate methods.

- (void)setUpCastController
{
    self.castController = [[JWCastController alloc] initWithPlayer:self.player];
    self.castController.chromeCastReceiverAppID = kGCKDefaultMediaReceiverApplicationID;
    self.castController.delegate = self;
}

func setUpCastController() {
    castController = JWCastController(player: player)
    castController?.chromeCastReceiverAppID = kGCKDefaultMediaReceiverApplicationID
    castController?.delegate = self
}

4. Call the scanForDevices method to scan for devices: [self.castController scanForDevices];. When devices become available, the JWCastingDelegate method, onCastingDevicesAvailable:, is called and returns an array of JWCastingDevices.

-(void)onCastingDevicesAvailable:(NSArray *)devices
{
    self.availableDevices = devices;
}

func onCastingDevicesAvailable(_ devices: [JWCastingDevice]!) 
{
    availableDevices = devices
}

5. Call the connectToDevice: method to connect to a device. When a connection is established, the JWCastingDelegate method, onConnectedToCastingDevice:, is called. This signals the ability to cast the video that is reproduced by the JWPlayerController.

-(void)onUserSelectedDevice:(NSInteger)index
{
    JWCastingDevice *chosenDevice = availableDevices[index];
    [self.castController connectToDevice:chosenDevice];
}

func onUserSelectedDevice(_ index: Int!) 
{
    let chosenDevice = availableDevices[index]
    castController?.connect(to: chosenDevice)
}

6. Call the cast method on your JWCastController.

-(void)onConnectedToCastingDevice:(JWCastingDevice *)device
{
    [self.castController cast];
}

func onConnected(to device: JWCastingDevice?) {
    castController?.cast()
}

The JWPlayerController API controls the playback of the video being cast, and the JWPlayerDelegate will provide you with the playback callbacks while casting.

🚧

Note that calling cast will interrupt the current casting to play your asset. Take care to avoid making unnecessary and/or duplicate calls, such as by tracking the casting state:

if (!self.isCasting) {
       self.castController.cast();
}

📘

The JWP iOS Best Practice Apps repository has an example casting implementation. Additionally, you can learn more about the Google Cast User Experience guidelines.

FAQs

Are there changes in iOS 13 that may impact my app?

Overview

With the release of iOS 13, we want to let you know about an important change. This change is not related to JW Player's SDK specifically, but we do want to make sure all of our customers aware of any third-party updates.

Apple has introduced stricter permissions requirements in iOS 13 that enforce a tighter control for Bluetooth access.

In order to prevent failed casting sessions and application crashes, we encourage all customers to make a small change to their iOS applications. This change does not require development changes or SDK updates. But, it does require resubmitting your app to the App Store.

After making the following change to your app, your app users will be required to provide Bluetooth access permissions. If a user declines to give permission to Bluetooth access, the casting button will disappear and casting functionality is disabled. Playback on the device is unchanged.

Implement the change

Use the following steps to implement this change:

1. In Xcode, open Info.plist for your app.
2. Create a Key named NSBluetoothAlwaysUsageDescription. When added, this appears as Privacy - Bluetooth Always Usage Description.
3. From the Type options, select String.
4. Set a message noting that Bluetooth is needed to enable Google Cast as the Value.

You can also update the source code of Info.plist:

info.plist

<key>NSBluetoothAlwaysUsageDescription</key>
    <string>Bluetooth is needed to enable Google Cast.</string>