Skip Navigation

Integrate the
BlackBerry Dynamics Launcher
for
iOS

As of the
BlackBerry Dynamics SDK for iOS
version 13.0, the
BlackBerry Dynamics Launcher
is now integrated with the SDK. Previously, you had to integrate a separate
BlackBerry Dynamics Launcher Library
(version 12.1 and earlier) to add the Launcher to your BlackBerry Dynamics apps. The Launcher is enabled by default, but you do have the option to disable it.
Take note of the following details and required actions for this new integration of the
BlackBerry Dynamics Launcher
:
Item
Details
How the
BlackBerry Dynamics Launcher
interacts with the
BlackBerry Dynamics
app UI
  • The Launcher view controller is set as the root view controller of the application UIWindow, and the root view controller that the app actually sets becomes the 'baseViewController' of the Launcher view controller.
  • The Launcher view controller sets the Launcher button with a UIWindowLevel above the baseViewController so that it is always hovering above the app.
  • Modal presentations will obscure the Launcher button.
How to integrate the new implementation of the
BlackBerry Dynamics Launcher
  • When accessing the application UIWindow.rootViewController property, the app will get back GTLauncherViewController, and the application root view controller can be accessed with the baseViewController property. See "Example: Get baseViewController" below.
  • You must update apps to expect GTLauncherViewController instead of whatever type has been set as the root view controller. An unknown selector error is intercepted to log more helpful exception text that is visible in the console. See "Example: Unknown selector error" below.
  • For
    BlackBerry Dynamics
    apps that have not previously integrated the Launcher, you just create and set the desired root view controller. The SDK will create an instance of GTLauncherViewController, set the app root view controller as the base view controller contained in GTLauncherViewController, and start the Launcher services.
  • To more fully integrate with the Launcher, or to change its behavior, implement the GTLauncherViewControllerDelegate protocol, and set the delegate on the Launcher view controller. See "Example: Set Launcher Delegate" below.
  • To integrate app settings into the Launcher, implement a UITableViewController. Return this in the delegate method that is invoked when the user taps the settings icon in the Launcher. See "Example: Delegate method for settings UITableViewController" below.
How to disable the new integration of the
BlackBerry Dynamics Launcher
To disable the
BlackBerry Dynamics Launcher
, create a PList option (Boolean) named GDDisableAutomaticLauncherManagement and set the value to YES.
This flag will prevent the automatic initialization and management of the
BlackBerry Dynamics Launcher
.
The SDK will check whether it is managing the Launcher when a Launcher view controller instance is created. If the SDK expects that it is managing the Launcher but the application has created the instance outside of the SDK, this is not allowed, and an exception is generated. A
BlackBerry Dynamics
app must define the Plist option if it is going to create its own instance of the Launcher.
Customize the Launcher icon
You can use BEMS to set a custom Launcher icon. See Setting a customized icon for the BlackBerry Dynamics Launcher.

Example: Get baseViewController

var vc = self.window?.rootViewController if let gtlvc = vc as? GTLauncherViewController { vc = gtlvc.baseViewController }

Example: Unknown selector error

*** Terminating app due to uncaught exception 'NSInvalidArgumentException', reason: 'The `<selector name>` selector has been invoked on an instance of GTLauncherViewController, which appears to not be the target object which this application is expecting. Retrieve the baseViewController property from the returned object and invoke the `<selector name>` selector on that target instead. Please refer to the Dynamics SDK documentation on Launcher for more information.'

Example: Set Launcher Delegate

let delegate = ... // instance which implements GTLauncherViewControllerDelegate let launcher = GDiOS.sharedInstance().getManagedLauncherViewController() launcher.delegate = delegate

Example: Delegate method for settings UITableViewController

func applicationSettingsTableViewController(forLauncher controller: GTLauncherViewController) -> UITableViewController? { // Create and return a UITableViewController which handles application settings }