Integrate Cast v3 into your iOS App

This developer guide describes how to add Google Cast support to your iOS sender app using Google Cast SDK v3.

The mobile device or laptop is the sender which controls the playback, and the Google Cast device is the receiver which displays the content on the TV.

The sender framework refers to the Cast framework bundle, which consists of the class library binary and associated header files and resources. The sender app or Cast app refers to an app running on the sender. The receiver app refers to the HTML application running on the receiver.

Google Cast uses the delegation pattern to inform the sender app of events and to move between various states of the Cast app life cycle.

App flow

The following steps describe the typical high-level execution flow for a sender iOS app:

  • The Cast framework automatically starts device discovery based on the view controller lifecycle.
  • When the user clicks on the Cast button, the framework presents the Cast dialog with the list of discovered Cast devices.
  • When the user selects a Cast device, the framework attempts to launch the receiver app on the Cast device.
  • The framework invokes callbacks in the sender app to confirm that the receiver app was launched.
  • The framework creates a communication channel between the sender and receiver apps.
  • The framework uses the communication channel to load and control media playback on the receiver.
  • The framework synchronizes the media playback state between sender and receiver: when the user makes sender UI actions, the framework passes those media control requests to the receiver, and when the receiver sends media status updates, the framework updates the state of the sender UI.
  • When the user clicks on the Cast button to disconnect from the Cast device, the framework will disconnect the sender app from the receiver.

To troubleshoot your sender, you need to enable logging.

For a comprehensive list of all classes, methods and events in the Google Cast iOS framework, see the Google Cast iOS API Reference. The following sections cover the steps for integrating Cast into your iOS app.

Call methods from main thread

All SDK methods must be called from the main thread.

Initialize the Cast Context

The Cast framework has a global singleton object, the CastContext, which coordinates all of the framework's activities. This object must be initialized early in the application's lifecycle, typically in the -[application:didFinishLaunchingWithOptions:] method of the app delegate, so that automatic session resumption on sender app restart can trigger properly.

A GCKCastOptions object must be supplied when initializing the CastContext. This class contains options that affect the behavior of the framework. The most important of these is the receiver application ID, which is used to filter discovery results and to launch the receiver app when a Cast session is started.

The -[application:didFinishLaunchingWithOptions:] method is also a good place to set up a logging delegate to receive the logging messages from the framework. These can be useful for debugging and troubleshooting.

@interface AppDelegate () <GCKLoggerDelegate>
@end

@implementation AppDelegate

static NSString *const kReceiverAppID = @"AABBCCDD";
static const BOOL kDebugLoggingEnabled = YES;

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  GCKCastOptions *options =
    [[GCKCastOptions alloc] initWithReceiverApplicationID:kReceiverAppID];
  [GCKCastContext setSharedInstanceWithOptions:options];

  [GCKLogger sharedInstance].delegate = self;
  ...
}

...

#pragma mark - GCKLoggerDelegate

- (void)logMessage:(NSString *)message fromFunction:(NSString *)function {
  if (kDebugLoggingEnabled) {
    NSLog(@"%@  %@", function, message);
  }
}

@end

The Cast UX Widgets

The Cast framework provides these widgets that comply with the Cast Design Checklist:

  • Introductory Overlay: The GCKCastContext class has a method, presentCastInstructionsViewControllerOnce, which can be used to spotlight the Cast button the first time a Cast receiver is available. The sender app can customize the text, position of the title text and the Dismiss button.

  • Cast Button: The cast button is visible when a receiver is discovered that supports your app. When the user first clicks on the cast button, a cast dialog is displayed which lists the discovered devices. When the user clicks on the cast button while the device is connected, it displays the current media metadata (such as title, name of the recording studio and a thumbnail image) or allows the user to disconnect from the cast device.

  • Mini Controller: When the user is casting content and has navigated away from the current content page or expanded controller to another screen in the sender app, the mini controller is displayed at the bottom of the screen to allow the user to see the currently casting media metadata and to control the playback.

  • Expanded Controller: When the user is casting content, if they click on the media notification or mini controller, the expanded controller launches, which displays the currently playing media metadata and provides several buttons to control the media playback.

The following guide includes descriptions of how to add these widgets to your app.

Add a Cast Button

The framework provides a Cast button component as a UIButton subclass. It can be added to the app's title bar by wrapping it in a UIBarButtonItem. A typical UIViewController subclass can install a Cast button as follows:

CGRect frame = CGRectMake(0, 0, 24, 24);
GCKUICastButton *castButton = [[GCKUICastButton alloc] initWithFrame:frame];
castButton.tintColor = [UIColor whiteColor];
UIBarButtonItem *item = [[UIBarButtonItem alloc] initWithCustomView:castButton];
self.navigationItem.rightBarButtonItem = item;

By default, tapping the button will open the Cast dialog that is provided by the framework.

GCKUICastButton can also be added directly to the storyboard.

Configure device discovery

In the framework, device discovery happens automatically. There is no need to explicitly start or stop the discovery process.

Discovery in the framework is managed by the class GCKDiscoveryManager, which is a property of the GCKCastContext. The framework provides a default Cast dialog component for device selection and control. The device list is ordered lexicographically by device friendly name.

How Session Management Works

The Cast framework introduces the concept of a Cast session, the establishment of which combines the steps of connecting to a device, launching (or joining) a receiver app, connecting to that app, and initializing a media control channel, if appropriate.

Sessions are managed by the class GCKSessionManager, which is a property of the GCKCastContext. Individual sessions are represented by subclasses of the class GCKSession: for example, GCKCastSession represents sessions with Cast devices. You can access the currently active Cast session (if any), as the currentCastSession property of GCKSessionManager.

The GCKSessionManagerListener interface can be used to monitor session events, such as session creation, suspension, resumption, and termination. The framework automatically suspends sessions when the sender app is going into the background and attempts to resume them when the app returns to the foreground (or is relaunched after an abnormal/abrupt app termination while a session was active).

If the Cast dialog is being used, then sessions are created and torn down automatically in response to user gestures. Otherwise, the app can start and end sessions explicitly via methods on GCKSessionManager.

If the app needs to do special processing in response to session lifecycle events, it can register one or more GCKSessionManagerListener instances with the GCKSessionManager. GCKSessionManagerListener is a protocol which defines callbacks for such events as session start, session end, and so on.

Automatic Reconnection

The Cast framework adds reconnection logic to automatically handle reconnection in many subtle corner cases, such as:

  • Recover from a temporary loss of WiFi
  • Recover from device sleep
  • Recover from backgrounding the app
  • Recover if the app crashed

How Media Control Works

If a Cast session is established with a receiver app that supports the media namespace, an instance of GCKRemoteMediaClient will be created automatically by the framework; it can be accessed as the remoteMediaClient property of the GCKCastSession instance.

All methods on GCKRemoteMediaClient which issue requests to the receiver will return a GCKRequest object which can be used to track that request. A GCKRequestDelegate can be assigned to this object to receive notifications about the eventual result of the operation.

It is expected that the instance of GCKRemoteMediaClient may be shared by multiple parts of the app, and indeed some internal components of the framework such as the Cast dialog and mini media controls do share the instance. To that end, GCKRemoteMediaClient supports the registration of multiple GCKRemoteMediaClientListeners, unlike GCKMediaControlChannel, which only supported a single delegate.

Set Media Metadata

The GCKMediaMetadata class represents information about a media item you want to cast. The following example creates a new GCKMediaMetadata instance of a movie and sets the title, subtitle, recording studio's name, and two images.

GCKMediaMetadata *metadata =
  [[GCKMediaMetadata alloc] initWithMetadataType:GCKMediaMetadataTypeMovie];
[metadata setString:self.mediaInfo.title forKey:kGCKMetadataKeyTitle];
[metadata setString:self.mediaInfo.subtitle forKey:kMediaKeyDescription];
[metadata setString:self.mediaInfo.studio forKey:kGCKMetadataKeyStudio];

[metadata addImage:[[GCKImage alloc] initWithURL:self.mediaInfo.imageURL
                                           width:480
                                          height:720]];
[metadata addImage:[[GCKImage alloc] initWithURL:self.mediaInfo.url
                                           width:480
                                          height:720]];

See the Image Selection and Caching section on the use of images with media metadata.

Load media

To load a media item, create a GCKMediaInformation instance using the media's metadata. Then get the current GCKCastSession and use its GCKRemoteMediaClient to load the media on the receiver app. You can then use GCKRemoteMediaClient for controlling a media player app running on the receiver, such as for play, pause and stop.

GCKMediaInformation *mediaInfo = [[GCKMediaInformation alloc]
  initWithContentID:[self.mediaInfo.url absoluteString]
         streamType:GCKMediaStreamTypeBuffered
        contentType:@"video/mp4"
           metadata:metadata
     streamDuration:self.mediaInfo.duration
        mediaTracks:nil
     textTrackStyle:nil
         customData:nil];

GCKCastSession *session =
  [GCKCastContext sharedInstance].sessionManager.currentCastSession;
if (session) {
[session.remoteMediaClient loadMedia:[self buildMediaInformation]
                                autoplay:YES];
}

Also see the section on using media tracks.

4K Video Format

To determine what video format your media is, use the property GCKMediaStatus.videoInfo to get the current instance of GCKVideoInfo. This instance contains the type of HDR TV format and the height and width in pixels. Variants of 4K format are indicated in the hdrType property by enum values GCKVideoInfoHDRType.

Add Mini Controllers

According to the Cast Design Checklist, a sender app should provide a persistent control known as the mini controller that should appear when the user navigates away from the current content page. The mini controller provides instant access and a visible reminder for the current Cast session.

The Cast framework provides a control bar, GCKUIMiniMediaControlsViewController, which can be added to the scenes in which you want to show the mini controller.

There are two ways to add the mini controller to a sender app:

  • Let the Cast framework manage the layout of the mini controller by wrapping your existing view controller with its own view controller.
  • Manage the layout of the mini controller widget yourself by adding it to your existing view controller by providing a subview in the storyboard.

The first way is to use the GCKUICastContainerViewController which wraps another view controller and adds a GCKUIMiniMediaControlsViewController at the bottom. This approach is limited in that you cannot customize the animation and cannot configure the behavior of the container view controller.

This first way is typically done in the -[application:didFinishLaunchingWithOptions:] method of the app delegate:

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...
UIStoryboard *appStoryboard =
      [UIStoryboard storyboardWithName:@"Main" bundle:nil];
  UINavigationController *navigationController =
      [appStoryboard instantiateViewControllerWithIdentifier:@"MainNavigation"];
  GCKUICastContainerViewController *castContainerVC;
  castContainerVC = [[GCKCastContext sharedInstance]
      createCastContainerControllerForViewController:navigationController];
  castContainerVC.miniMediaControlsItemEnabled = YES;
  self.window = [[UIWindow alloc] initWithFrame:UIScreen.mainScreen.bounds];
  self.window.rootViewController = castContainerVC;
  [self.window makeKeyAndVisible];
...
}

Add these methods to control the visibility of the mini controller:

- (void)setCastControlBarsEnabled:(BOOL)notificationsEnabled {
  GCKUICastContainerViewController *castContainerVC;
  castContainerVC =
      (GCKUICastContainerViewController *)self.window.rootViewController;
  castContainerVC.miniMediaControlsItemEnabled = notificationsEnabled;
}

- (BOOL)castControlBarsEnabled {
  GCKUICastContainerViewController *castContainerVC;
  castContainerVC =
      (GCKUICastContainerViewController *)self.window.rootViewController;
  return castContainerVC.miniMediaControlsItemEnabled;
}

The second way is to add the mini controller directly to your existing view controller by using createMiniMediaControlsViewController to create a GCKUIMiniMediaControlsViewController instance and then adding it to the container view controller as a subview :

- (void)viewDidLoad {
  [super viewDidLoad];
  GCKCastContext *castContext = [GCKCastContext sharedInstance];
  _miniMediaControlsViewController =
      [castContext createMiniMediaControlsViewController];
  _miniMediaControlsViewController.delegate = self;

  [self addChildViewController:_miniMediaControlsViewController];
  _miniMediaControlsViewController.view.frame = _miniMediaControlsContainerView.bounds;
  [_miniMediaControlsContainerView addSubview:_miniMediaControlsViewController.view];
  [_miniMediaControlsViewController didMoveToParentViewController:self];

  [self updateControlBarsVisibility];
}

The GCKUIMiniMediaControlsViewControllerDelegate tells the host view controller when the mini controller should be visible:

- (void)updateControlBarsVisibility {
  if (self.miniMediaControlsViewEnabled &&
      _miniMediaControlsViewController.active) {
    _miniMediaControlsHeightConstraint.constant =
        _miniMediaControlsViewController.minHeight;
  } else {
    _miniMediaControlsHeightConstraint.constant = 0;
  }
  [UIView animateWithDuration:kCastControlBarsAnimationDuration
                   animations:^{
                     [self.view layoutIfNeeded];
                   }];
}

- (void)miniMediaControlsViewController:(GCKUIMiniMediaControlsViewController *)
                                            miniMediaControlsViewController
                           shouldAppear:(BOOL)shouldAppear {
  [self updateControlBarsVisibility];
}

When your sender app is playing a video or audio live stream, the SDK automatically displays a play/stop button in place of the play/pause button in the mini controller.

See Style the Widgets for how your sender app can configure the appearance of the widgets across your app.

Add Expanded Controller

The Google Cast Design Checklist requires a sender app to provide an expanded controller for the media being cast. The expanded controller is a full screen version of the mini controller.

The expanded controller is a full screen view which offers full control of the remote media playback. This view should allow a casting app to manage every manageable aspect of a cast session, with the exception of receiver volume control and session lifecycle (connect/stop casting). It also provides all the status information about the media session (artwork, title, subtitle, and so forth).

The functionality of this view is implemented by the GCKUIExpandedMediaControlsViewController class.

The first thing you have to do is enable the default expanded controller in the cast context. Modify AppDelegate.m to enable the default expanded controller:

#import <GoogleCast/GoogleCast.h>

@interface AppDelegate ()<GCKLoggerDelegate> {
...
}

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...

  [GCKCastContext sharedInstance].useDefaultExpandedMediaControls = YES;
...
}

Add the following code to MediaViewController to load the expanded controller when the user starts to cast a video:

- (void)playSelectedItemRemotely {
...
  self.navigationItem.backBarButtonItem =
      [[UIBarButtonItem alloc] initWithTitle:@""
                                       style:UIBarButtonItemStylePlain
                                      target:nil
                                      action:nil];
  if (appDelegate.castControlBarsEnabled) {
    appDelegate.castControlBarsEnabled = NO;
  }
  [[GCKCastContext sharedInstance] presentDefaultExpandedMediaControls];
}

The expanded controller will also be launched automatically when the user taps the mini controller.

When your sender app is playing a video or audio live stream, the SDK automatically displays a play/stop button in place of the play/pause button in the expanded controller.

See Style the Widgets for how your sender app can configure the appearance of the widgets across your app.

Handle Errors

It is very important for sender apps to handle all error callbacks and decide the best response for each stage of the Cast life cycle. The app can display error dialogs to the user or it can decide to end the Cast session.

Logging

GCKLogger is a singleton used for logging by the framework. Use the GCKLoggerDelegate to customize how you handle log messages.

Using the GCKLogger class, the SDK produces logging output in the form of debug messages, errors, and warnings. These log messages aid debugging and are useful for troubleshooting and identifying problems. By default, the log output is suppressed, but by assigning a GCKLoggerDelegate, the sender app can receive these messages from the SDK and log them to the system console.

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...
  [[GCKLogger sharedInstance] setDelegate:self];
...
}

#pragma mark - GCKLoggerDelegate

- (void)logMessage:(NSString *)message fromFunction:(NSString *)function {
  NSLog(@"%@  %@", function, message);
}

To enable debug and verbose messages as well, add this line to the code after calling the setDelegate function (shown previously):

[GCKLogger sharedInstance].minimumLevel = GCKLoggerLevelVerbose;

You can also filter the log messages produced by GCKLogger. Set the minimum logging level per class, for example:

[logFilter setLoggingLevel:GCKLoggerLevelVerbose
  forClasses:@[
  @"GCKUICastButton",
  @"GCKUIImageCache",
  @"NSMutableDictionary"
]];

The class names can be either literal names or glob patterns, for example, GCKUI\* and GCK\*Session.

Next Step

To add more Cast v3 features to your iOS sender app, visit Add Advanced Features.