Getting Started with the iOS SDK

The BomgarSession() framework provides an API, allowing you to connect to a B Series Appliance and start a support session inside any native iOS application. You can start a session using either a session key entered by the user or using a predefined issue code name created by one of your B Series Appliance's administrators.

Previous versions of the BomgarSession() framework required an embedded framework called ThinProtocolEmbedded.framework. This is not longer required. If you previously included a reference to this framework per the instructions in a previous version, you can delete it.

The best way to integrate the SDK into your application depends on your development needs, mainly on whether or not you need to use the simulator. This is due in part to the fact that Apple does not allow an app to be submitted to the app store if the app contains a framework that includes code for the x86_64 architecture, and this architecture is required to run code in the iOS simulator.

The following sections walk you through integrating the BeyondTrust SDK into your project for development either using only physical devices or using both physical devices and the simulator.

 

The configuration for supporting only physical devices is much simpler to use. If you do not need to support development in the simulator, BeyondTrust highly recommends supporting only physical devices.

Development for Physical Devices

iOS SDK Physical Device

  1. When you expand the archive that contains BomgarSession().framework, locate the BomgarSession() folder, which contains two sub-folders, Debug and Device. Each folder contains a separate build of BomgarSession().framework. Since you will need to configure only the project for running physical devices, focus on the build in the Device folder. Drag the BomgarSession().framework file from the Device folder into your Xcode project.

     

  2. In the project navigator, go to Your Project > Your Target > Build Phases.
  3. If not already there, add a Copy Files step at the end.

 

iOS SDK Physical Device

  1. Set the destination to Frameworks and drag BomgarSession().framework from the project navigator into the file list. You should see something similar to the screenshot.

  2. Alternatively, you can drag BomgarSession().framework to the General > Embedded Binaries. Xcode should link the framework and add a copy files task to your Build Phases. If you use this method, under Build Phases, you should still have a similar configuration for your target.

 

iOS SDK

  1. When building your app, if your project does not contain any Swift code, you must tell Xcode to include the Swift libraries. To do this, click on Build Settings for your target.

     

If your project contains Swift code, you can skip step 7.

  1. Under Build Options, you should see a key called Always Embed Swift Standard Libraries. To narrow the list, search for Always Embed.
  2. Set this value to Yes. You are now ready to import BomgarSession() and to connect your app to your B Series Appliance.

Development for Both Physical Devices and Simulators

Summary of process

When building against a physical device or when creating a release, link against the Device/bomgarSession().framework. When building for the simulator, link against Debug/bomgarSession().framework. This is accomplished by using an xcconfig file and a custom build script to embed and sign the framework. The following instructions assume you do not currently have any xcconfig files assigned to your configurations.

If you are already using xcconfig files, simply copy the settings from the resource file into your configuration or enter #include "BomgarSession().xcconfig" at the top of your config file. If this configuration style does not work for you, there are other options you can use. For example, you can create separate targets for the simulator and device builds and link the correct framework version to each target, following the steps in the previous section.

The demo apps, provided in the SDK Demo bundle, use this configuration. You can view those projects for reference.

  1. When you expand the archive that contains BomgarSession().framework, locate the BomgarSession() folder, which contains two sub-folders, Debug and Device. Each of these folders contains a separate build of BomgarSession().framework, and both builds are needed. Drag the BomgarSession() folder into the same folder as your Xcode project.

The configuration files being used are written with the assumption that this folder structure is in this specific location.

  1. There is a ConfigurationResources archive that contains two files. You need two of them for this configuration, BomgarSession().xcconfig and copy_BomgarSession().sh. Copy these two files into your app’s project structure.

Although it is not strictly required, these instructions assume the files were copied into the same directory as your Xcode project.

iOS SDK > Physical and Simulator

  1. Drag BomgarSession().xcconfig into your Xcode project. The folder structure should look similar to the screenshot.

 

iOS SDK > Physical and Simulator

  1. Your Xcode project structure should look similar to the screenshot.
  2. Now you must tell Xcode about the xcconfig file just added to the project. In the Project Navigator, go to Your Project > Your Project > Info.
  3. Under Configurations, expand the Debug section, and you should see your project with all of its targets nested below it.
  4. On the right, click the dropdown for the project itself and select BomgarSession() from the list.

 

iOS SDK > Physical and Simulator

  1. Repeat this same process for the Release configuration. Your project should look similar to the screenshot.
  2. In the Project Navigator, go to Your Project > Your Target > Build Phases.
  3. At the end of the list, add a Run Script phase.
  4. The Shell field should default to /bin/sh. In this script box, place the path to the copy_BomgarSession().sh script as the only line.

 

iOS SDK > Physical and Simulator

  1. Since the script was placed in our directory, you should see the script box contain "${PROJECT_DIR}/copy_BomgarSession().sh". Your build phases should look similar the following.

The build phase is renamed to Embed BomgarSession() for clarity.

You are now ready to import BomgarSession() and to connect your app to your B Series Appliance.

 

Other Customization Options

In addition to the assets used to configure your project, the ConfigurationResources bundle also contains a Localized.strings file. This file contains all of the user-facing strings used by the SDK. If you need to localize your app into a language other than English, you can include this file as a resource in your app and localize it in Xcode, as needed.

Troubleshoot the iOS SDK Implementation

  • If you were using a previous version of BomgarSession(), you may have imported <BomgarSession()/SystemInfo.h> into your project. This is no longer needed and must be removed to compile the current version of BomgarSession().

Troubleshooting iOS SDK

  • If you see an @rpath error when launching your app on a device, make sure the runtime search paths include @executable_path/Frameworks. Here is a screenshot of the error as well as the proper values in the Build Settings.
  • If you see memory errors coming from the framework itself (i.e. EXC_BAD_ACCESS), make sure arm64 is in your Valid Architectures list.

Install Documentation from Docset Archive File

To read through more documentation about the iOS SDK, follow these steps.

  1. Extract the archive.
  2. Drag the .docset file to ~/Library/Developer/Shared/Documentation/DocSets/.
  3. Restart Xcode.
  4. The BeyondTrust docset should now show up in Xcode Organizer's Documentation tab.