Enable casting to Chromecast devices (iOS)

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.

• To specify a receiver and start scanning for devices, pass a media receiver app ID to the withAppId argument of the startScanningForDevices method of the JWCastController.

Requirement

🚧

The JWP iOS SDK's cast integration requires that you link your app to the dynamic build of the Google Cast SDK. Since Google only distributes its static libraries via CocoaPods, there is no CocoaPods integration option — only the manual download approach described above is possible.

Set up permissions

1. If you are using Xcode 12 and targeting iOS 12+, enable Access Wifi Information.

   📘

   1. Click the app target > Capabilities > Access WiFi Information.
      2. 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. Read Are there changes in iOS 13 that may impact my app? in the FAQs section below.

   📘

   If you are using the google-cast-sdk-no-bluetooth dependency, you can skip this step.

3. (iOS 14) In the info.plist, add the following two keys:
   • NSBonjourServices with _googlecast._tcp and _<your-app-id>._googlecast._tcp inside the array
   • NSLocalNetworkUsageDescription
     
     
   Info.plist

   <key>NSBonjourServices</key>
   <array>
     <string>_googlecast._tcp</string>
     <string>_ABCD1234._googlecast._tcp</string>
   </array>
   <key>NSLocalNetworkUsageDescription</key>
   <string>${PRODUCT_NAME} uses the local network to discover Cast-enabled devices on your WiFi
   network.</string>
   

Configure and enable casting

With JWPlayerViewController

Initialize the CastContext as described in Google's article, Integrate Cast Into Your iOS App.

After initializing a CastContext, casting is handled automatically by JWPlayerViewController. A casting button will appear on the player, and you can respond to casting-related callbacks by overriding the JWCastingDelegate methods on JWPlayerViewController.

💡

If you are trying to cast outside of JWPlayerViewController, JWPlayerViewController might interfere with your implementation because the Google Cast SDK uses as singleton. To prevent JWPlayerViewController from handling casting, set handleCastingInternally to false.

class CustomPlayerViewController: JWPlayerViewController {

    override var handleCastingInternally: Bool {
        return false
    }
}

Without JWPlayerViewController

1. Initialize the CastContext as described in Google's article, Integrate Cast Into Your iOS App.

2. In your app, create a JWCastController object and set its delegate. The delegate must adhere to the JWCastDelegate protocol and implement its delegate methods.

   SwiftObjective-C

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

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

3. Call startDiscovery() to scan for devices.

   SwiftObjective-C

   func beginScanning() {
       castController.startDiscovery()
   }
   

   - (void) beginScanning
   {
       [self.castController startDiscovery];
   }
   

   Once available devices are discovered, the event is reported to the JWCastDelegate method, devicesAvailable:. This method supplies a list of available devices within range as an array of JWCastingDevice.

   SwiftObjective-C

   func castController(_ controller: JWCastController, devicesAvailable devices: [JWCastingDevice]) 
   {
       availableDevices = devices
   }
   

   -	(void)castController:(JWCastController *)controller devicesAvailable: (NSArray<JWCastingDevice *> *)devices
   {
       self.availableDevices = devices;
   }
   

4. Call the connectToDevice: method to connect to a device.

   When a connection is established, the JWCastingDelegate method, connectedTo:, is called. This signals the ability to cast the video that is reproduced by the JWPlayer instance.

   SwiftObjective-C

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

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

5. Call cast() on the JWCastController instance.

   SwiftObjective-C

   func castController(_ controller: JWCastController, connectedTo device: JWCastingDevice) {
       self.castController.cast()
   }
   

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

The JWP API controls the playback of the video being casted. The JWPlayerDelegate provides the playback callbacks while casting.

Send custom data to a custom receiver

Custom data can be sent to your custom receiver alongside the media item. For example, you can play DRM-protected content by sending the Widevine license URL or add a call to action by sending the user’s account info.

You can send custom data through the userInfo property of the playlist item.

❗️

Do not use the reserved key sources in the JSON. The Delivery API uses this key to pass the sources of DRM media items protected by Studio DRM.

PlaylistItem.Builder playlistItemBuilder = new PlaylistItem.Builder();

playlistItemBuilder
  .file(videoURL)
  .title(title)
  .description(description)
  .userInfo(new JSONObject().put("licenseUrl", "https://drm-license-url"));

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 JWP'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:

XML

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