Enable casting to Chromecast devices (iOS v3)
Learn how to enable casting with the iOS SDK.
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 theonConnected
delegate callback method, since it takes a finite amount of time for processes related to the established connection to resolve. If unavoidable, delaying thecast()
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
- In a text editor, open Podfile.
- 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 thegoogle-cast-sdk
dependency, you can add thegoogle-cast-sdk-no-bluetooth
(no guest mode support) non-bluetooth dependency to your Podfile. However, we strongly recommend usinggoogle-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
- 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.
- (Guest mode only) In the Info.plist for your app, add
NSBluetoothAlwaysUsageDescription
to create a Bluetooth access request. If you are using thegoogle-cast-sdk-no-bluetooth
dependency, you can skip this step. - 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
}
- Call the
scanForDevices
method to scan for devices:[self.castController scanForDevices];
. When devices become available, theJWCastingDelegate
method,onCastingDevicesAvailable:
, is called and returns an array ofJWCastingDevices
.
-(void)onCastingDevicesAvailable:(NSArray *)devices
{
self.availableDevices = devices;
}
func onCastingDevicesAvailable(_ devices: [JWCastingDevice]!)
{
availableDevices = devices
}
- Call the
connectToDevice:
method to connect to a device. When a connection is established, theJWCastingDelegate
method,onConnectedToCastingDevice:
, is called. This signals the ability to cast the video that is reproduced by theJWPlayerController
.
-(void)onUserSelectedDevice:(NSInteger)index
{
JWCastingDevice *chosenDevice = availableDevices[index];
[self.castController connectToDevice:chosenDevice];
}
func onUserSelectedDevice(_ index: Int!)
{
let chosenDevice = availableDevices[index]
castController?.connect(to: chosenDevice)
}
- Call the
cast
method on yourJWCastController
.
-(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
Which features not supported when casting with an iOS SDK player?
The following features are not supported during a casting session with an iOS SDK player:
- Google IMA ads
- FreeWheel ads
- Multiple-audio tracks or AudioTrack switching
- 608 captions
- DVR and live streaming capabilities
Also, note that Google does not support FairPlay DRM.
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
![ios-13-info-plist-update-bluetooth.png 1328](https://files.readme.io/fb72d46-ios-13-info-plist-update-bluetooth.png)
Bluetooth access request in Info.plist
Use the following steps to implement this change:
- In Xcode, open Info.plist for your app.
- Create a Key named NSBluetoothAlwaysUsageDescription. When added, this appears as Privacy - Bluetooth Always Usage Description.
- From the Type options, select String.
- 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:
<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth is needed to enable Google Cast.</string>
Updated over 1 year ago