iOS Permissions Changes

With recent updates to iOS, the operating system will now enforce new restrictions and permissions that affect the Cast user experience. It will also affect how you build the Cast SDK into your app. For your app to maintain Cast functionality with the latest versions of iOS, you must make updates to handle these permissions changes.

iOS 14

We are asking all developers to update their iOS Cast sender apps to the Google Cast SDK v4.5.0, which provides support for iOS 14.

Beginning with iOS 14, applications that scan for devices on the local network will now prompt users with a one-time permissions dialog to find and connect to local network devices. The Cast platform uses the local network to discover and control Cast devices, so if the user denies permission, they will not be able to cast.

To improve the user experience, we are making some UX modifications to the SDK for those apps that are using the standard device picker. These UX modifications make it more obvious to users why local network access permissions are needed, as well as how to enable casting if local network device access has been disabled.

Apps built with versions of the Cast SDK using v4.4.8 or earlier will continue to work as long as they are built with Xcode 11.7 or earlier. If you are building for iOS 14 with Xcode 12 or above, we recommend you update to the Cast SDK v4.5.0 to ensure that your Cast app will continue to work properly.

The Cast SDK v4.5.0 can be downloaded with Cocoapods by following the Cocoapods setup or manually by following the manual setup. This release includes an initial set of UX improvements, as well as changes to the underlying discovery mechanism to allow apps that are built with Xcode 12 to find Cast devices on the network. A later release of the Cast SDK will incorporate additional UX improvements to refine when to display the Cast button, and provide users with guidance for reenabling local network access permissions if they previously declined.

Cast SDK changes

First-time casting

The first time a user attempts to Cast, a new local network access (LNA) interstitial dialog will appear explaining why local networking access is needed, followed by the iOS local network access permissions prompt. The mocks below illustrate the flow:

Updating your app on iOS 14

  1. Add the Cast iOS SDK 4.5.0 to your project

    If using Cocoapods, use pod update to add the v4.5.0 SDK to your project.

    Otherwise, pull in the SDK manually.

  2. Add NSBonjourServices to your Info.plist

    Specify NSBonjourServices in your Info.plist to allow local network discovery to succeed on iOS 14.

    You will need to add both _googlecast._tcp and _<your-app-id>._googlecast._tcp as services for device discovery to work properly.

    The appID is your receiverID, which is the same ID that is defined in your GCKDiscoveryCriteria.

    Update the following example NSBonjourServices definition and replace "ABCD1234" with your appID.

    <key>NSBonjourServices</key>
    <array>
      <string>_googlecast._tcp</string>
      <string>_ABCD1234._googlecast._tcp</string>
    <array>
  3. Add NSLocalNetworkUsageDescription to your Info.plist

    We strongly recommend that you customize the message shown in the Local Network prompt by adding an app-specific permission string in your app's Info.plist file for the NSLocalNetworkUsageDescription such as to describe Cast discovery and other discovery services, like DIAL.

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

    This message will appear as part of the iOS Local Network Access dialog as shown in the mock.

    Cast iOS14 LNA Dialog
  4. Re-release your app to the Apple App Store

    We recommend you also re-release your app on iOS 14 using v4.5.0 as soon as possible.

Customizations

  • Cast device discovery initiation

    By default, Cast device discovery is initiated the first time the user taps the Cast button (GCKUICastButton). If it's the first time the user has attempted to use the Cast app on the local network after upgrading to iOS 14, the new LNA interstitial will appear, followed by the iOS Local Network Access permissions dialog.

    A new flag is available to allow you to control when device discovery starts and the behavior of certain elements of the UX:

    startDiscoveryAfterFirstTapOnCastButton: BOOL(true/false)

    The default value is true. This flag is only applicable when the flag GCKCastOptions::disableDiscoveryAutostart is set to false.

    If set to true, Cast device discovery will start when a user taps on the GCKUICastButton for the first time. An informational message will be displayed to the user letting them know why local network permission is needed. Following that message, the iOS 14 LNA message will be displayed. Cast device discovery will start once the message is acknowledged.

    In subsequent App launches, GCKUICastButton will be shown only after discovery has been initiated.

    If set to false, device discovery will start based on the value of the flag GCKCastOptions::disableDiscoveryAutostart.

Testing on devices running iOS 14 beta

Although Xcode 12 is not required to test the v4.5.0 SDK on iOS 14 devices, you will be unable to build to an iOS 14 device directly using earlier Xcode versions.

To test your app on devices running iOS 14 using earlier Xcode versions you will need to archive your build and install the IPA to your devices.

Frequently asked questions

What happens if I don't re-release my Cast sender app with the Cast SDK v4.5.0 before iOS 14 is released?

Users will be prompted with a new iOS permissions dialog when the app launches for the first time. If a user does not consent to allowing the app to scan or connect to devices on the local network, the first time the app launches, the Cast icon will no longer be visible, and users may be confused as to why they cannot Cast with your app.

What happens if I re-release my Cast sender app with the Cast SDK v4.4.8 and Xcode 12?

Your app may not be able to discover Cast devices on the local network unless you have obtained a networking multicast entitlement from Apple. Note that Apple will not be granting multicast entitlements solely for the purpose of supporting Cast. If you plan to build with Xcode 12, you should release your app with Cast v4.5.0.

If I re-release my app with the new Cast SDK, what will my users running on iOS 13 or earlier experience?

They will continue to see the same user experience they had prior to re-release of your app. User-visible changes are limited to users running on iOS 14.

If I re-release my app with the new Cast SDK, and don't re-release it once iOS 14 is available, what will my users on iOS 14 experience?

They will see a Cast interstitial prior to the Apple Local Network Access dialog being presented. However, they will not see a customized message in the Apple Local Network Access dialog until you build and release with Xcode 12.

What will I need to do to update my app once the new version of the Cast SDK is released?

  • Update your app's Info.plist to include a local network usage description.
  • Add NSBonjourServices to your app's Info.plist and provide the Bonjour service names for Cast and your app ID.
  • Upgrade your sender app to use Cast SDK v4.5.0.
  • Re-release your app to the Apple app store.

Will I need to make any changes to my Web Receiver, Android TV Receiver, Chrome sender, or Android sender to support this?

No, no changes will be necessary.

iOS 13

With iOS 13, new permissions requirements were introduced which impact apps using the Google Cast SDK.

Starting with Google Cast SDK v4.4.3, an additional SDK is available without guest mode support that does not require Bluetooth® permission. This is available both on the developer site and on the new google-cast-sdk-no-bluetooth Cocoapod. As a reminder, the guest mode feature is the ability for the sender app to be able to detect cast devices within a certain physical proximity without being on the same network, using a PIN displayed on guest mode-enabled devices.

To prepare your app for iOS 13 you will need to decide if you:

Need to keep guest mode support

  • Must add the Privacy - Bluetooth Always Usage Description key.
  • Add a string to explain the Bluetooth® usage for your users to your Info.plist.

Need to remove guest mode support

  • Prevents your app from requiring Cast Bluetooth® requirements.
  • Integrate the latest version of the Google Cast SDK with no Bluetooth® support.
  • This is available both on the developer site and on the new google-cast-sdk-no-bluetooth Cocoapod.

Near future considerations

Some device discovery system-level APIs changed with iOS 13. The Google Cast SDK v4.4.3 was updated to work better with these new behaviors.

App breakdown

Here is a breakdown depending on the version of the iOS SDK you are currently using:

Apps built with the iOS 12 SDK or earlier

  • Action Recommended. Device discovery performance may decrease when running on iOS 13, but will still be functional. We highly recommend developers upgrade to Cast SDK v4.4.4 when available.
  • iOS 13 will prompt users to grant Bluetooth® permissions to the app.

Apps built with the iOS 13 SDK

  • Action Required: Update to Cast SDK 4.4.4 or the cast button may not appear if the user does not grant location permission. Upgrading to Cast SDK 4.4.4 is necessary to ensure a reliable casting experience on iOS 13.
  • Please refer to developer documentation for more information on how to integrate guest mode, or opt-out of guest mode with Google Cast SDK and no Bluetooth® support.