CoPilot Navigation

iOS CPIK Libraries

Contents

This guide provides details on how to get started with iOS CPIK libraries. We will cover how to import the project, how to license and get started as well as code snippets from Map Downloads, Licensing and adding stops to CoPilot.

Introduction

The library package included within the iOS CPIK libraries build will include the following:

  1. CoPilot Navigation Library
  2. Sample application that can be installed on an iOS device
  3. Source code for the sample application

Note: The CoPilot navigation library requires iOS SDK 8 or later

Distribution

Included in the CPIK libraries distribution is the library and the source code for our sample app to demonstrate how it can be used. We do not provide a prebuilt .ipa because of iOS certificate requirements, and instead the sample app project can be built using your own profiles.

App Store deployments

If you are planning on distributing your iOS CPIK libraries application via the App Store and are using multiple SKUs please ensure all of your applications meet the guidelines set out by Apple.

Required Setup

Frameworks

  • AddressBook
  • AddressBookUI
  • AssetsLibrary
  • AudioToolbox
  • AVFoundation
  • CFNetwork
  • Contacts
  • ContactsUI
  • CoreAudio
  • CoreGraphics
  • CoreLocation
  • CoreTelephony
  • ExternalAccessory
  • Foundation
  • MediaPlayer
  • MessageUI
  • OpenGLES
  • QuartzCore
  • Security
  • StoreKit
  • SystemConfiguration
  • UIKit
  • WebKit

Note: AVFoundation is weakly linked, which means in “Build Phase” of your target, AVFoundation.framework can be added as “Optional” instead of “Required”

Note: Contacts framework is only needed in Xcode 10.

Libraries

  • libc++
  • libsqlite3
  • libz

Resources

copilot_resources.bundle

Project Settings

  • Supported Architectures - armv7, arm64
  • Supported iOS SDK - iOS 8.0 and Later
  • Supported iOS Deployment Target - iOS 8.0 and Later
  • Objective-C Automatic Reference Counting - Yes

How to import CPIK libraries Sample application

Sample applications are included within the iOS CPIK libraries .zip. They provide a demonstration of how iOS CPIK libraries could be implemented.

It is very straightforward to open the XCode Sample application project. The following are the main components required for opening the XCode project:

  1. Mac Machine
  2. XCode

In order to build the sample application project, one needs to place CPIK libraries Framework and resources at the following location. CPIK libraries Framework (CoPilotIntegrationKit.Framework) and Resources (copilot_resources.bundle) can be found in the CPIK libraries bundle.

cpik_samples/samples/CPIKSampleApp/CPIKSampleApp/framework/CoPilotIntegrationKit.Framework cpik_samples/samples/CPIKSampleApp/CPIKSampleApp/resources/copilot_resources.bundle

Project Set Up

Demonstrated under Xcode 10

The following steps show how to integrate the CPIK libraries into an existing project. The project referenced throughout this document is the CPIKSampleApp and is included in the copilot_integration_kit/samples/CPIKSampleApp folder.

Step 1: Add framework / library dependencies

CPIK libraries has a number of iOS frameworks and libraries that it depends on and if they are not added to the linker phase of your project it will result in unresolved symbol errors when you try to build your application. All of the items listed in Frameworks and Libraries under the Required Setup section must be added to your application’s Link Binary With Libraries build phase.

From the Project Settings, select the Build Phases tab for your target and add all of the frameworks and libraries listed above in the Link Binary With Libraries section.

Step 2: Adding the CPIK libraries framework

The CPIK libraries framework can be found in the copilot_integration_kit/framework folder. Add it to your project by clicking the Add Other button on the Choose frameworks and libraries to add dialog from the previous step.

Browse to the location of the copilot_integration_kit\framework folder and select CoPilotIntegrationKit.framework. Click the Open button to add the framework to your project.

Step 3: Add Required Resources

The copilot_resources.bundle file located in the copilot_integration_kit/resources folder contains the resource files required by CoPilot.

These files must be added to the root folder of your application. If the resource bundle is missing, the application will crash when CoPilot is started. (In CPIKSampleApp project, we put copilot_resources.bundle under the group “Supporting Files”.)

Add the resource bundle to your application by selecting Add Files to, for example, CPIKSampleApp from the File menu and navigating to the copilot_integration_kit/resources folder. Select the copilot_resources.bundle file and make sure that your application is checked in the Add to targets list.

Step 4: Verify Build Settings

The following values must be set in either the project or target Build Settings:

Supported Architectures: armv7, arm64 CPIK libraries currently supports the armv7 and arm64 architectures. If your application is built for either the armv6 or armv7s architectures you will see missing architecture errors when trying to link against the CPIK libraries framework.

Supported Platforms: iOS
CPIK libraries only supports the iOS platform. There is currently no support for macOS.

Supported iOS SDK: iOS 8.0 and Later
CPIK libraries supports iOS SDK 8.0+

Supported iOS Deployment Target: iOS 8.0 and Later
CPIK libraries is only backward compatible with iOS devices from iOS 8.0 and newer.

Initializing CPIK libraries and Inserting the CoPilot view

The following steps show the code changes required to initialize the CPIK libraries framework and display the CoPilot navigation app by inserting it’s UIView into your application’s view stack. The CPIK libraries framework is accessed through a shared singleton object. The caller is not responsible for creating or managing the memory for this object. Memory will be allocated the first time the application accesses the object and will be released when the application exits. A pointer to the CPIK libraries framework object of type CoPilot* is obtained by calling the [CoPilot sharedManager] class method. The pointer returned by this method can be stored by the calling application, however memory management calls such as retain or release will have no effect on the object.

Step 1: Import the CPIK libraries header file

The file CoPilotIntegrationKit.h imports all header files necessary for working with CPIK libraries. This file should be imported in any files that will access the CPIK libraries framework. Here is an example from our sample application: 

#import <CoPilotIntegrationKit/CoPilotIntegrationKit.h>
#import "AppDelegate.h"
#import "RootViewController.h"
#import "SampleAppUtil.h"
#import "Toast.h"

Include CoPilotIntegrationKit.h in any source file which uses CPIK libraries API

Step 2: Setting the CoPilot delegate and starting CoPilot

The CoPilot application is started by making a call to the -(void)startNavApp instance method. When this method is called, CoPilot will begin loading resources, open the GPS device, and begin drawing to its UIView.

The start-up process for CoPilot is performed on a separate thread so this method will return immediately, however the CPIK libraries API methods cannot be called until CoPilot has finished starting up. Any call to the CPIK libraries functions before CoPilot has finished initializing will result in an exception.

When CoPilot has finished initializing, it will notify the calling application calling the delegate method onCPStartup:.

Here is an example from the sample app 

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  //store temporary pointer to share CoPilot object
  CoPilot* cp = [CoPilot sharedManager];

  //Set the CoPilot delegate
  cp.delegate = self;

  //start the CoPilot Navigation App
  [cp startNavApp];

  UISegmentedControl *tmpCtrl = [[UISegmentedControl alloc] initWithFrame:CGRectMake(0, 0, 320, 50)];
  self.laneAssistCtrl = tmpCtrl;
  return YES;
}

Setup CoPilot delegate and start CoPilot

And to receive the onCPStartup callback: 

-(void)onCPStartup
{
  if([SampleAppUtil is DelegateActive:@"onCPStartup"])
  {
    NSLog(@"Received Notification: on CPStartup");
    [self makeToast:[NSString stringWithFormat:@"CoPilot is Ready!"]];
  }
}

Step 3: Displaying CoPilot

The CoPilot class contains a UIViewController property named copilotViewController which represents the root view controller of the CoPilot navigation app. This view controller can be used in your application like any other typical UIViewController. It can be displayed on the screen using the [UIViewController presentViewController] method, the [[UINavigationController pushViewController:animated:] method, or any other methods that add a UIViewController to the view controller stack. 

- (IBAction)showCP:(id)sender
{
  UIViewController *cpVC = [CoPilot sharedManager].copilotViewController;
  if ([cpVC respondsToSelector:@selector(edgesForExtendedLayout)])
  {
    cpVC.edgesForExtendedLayout = UIRectEdgeNone;
  }
  [self.navigationController pushViewController:cpVC animated:YES];
}

Manipulating the copilotViewController’s view directly is strongly discouraged, because CoPilot needs to respond to certain events, such as UIInterfaceOrientation changes, and these events are handled at the view controller level.

What to do if you encounter an error within the application

When an application crashes, a crash report is created and stored on the device. Crash reports describe the conditions under which the application terminated, in most cases including a complete backtrace for each executing thread, and are typically very useful for debugging issues in the application. You should look at these crash reports to understand what crashes your application is having, and then try to fix them.

Crash reports with backtraces need to be symbolicated before they can be analyzed. Symbolication replaces memory addresses with human-readable function names and line numbers. If you get crash logs off a device through Xcode’s Devices window, then they will be symbolicated for you automatically after a few seconds. Otherwise you will need to symbolicate the .crash file yourself by importing it to the Xcode Devices window. See Symbolicating Crash Reports for details.

A Low Memory report differs from other crash reports in that there are no backtraces in this type of report. When a low memory crash happens, you must investigate your memory usage patterns and your responses to low memory warnings. This document points to you several memory management references that you might find useful.

Last updated July 2, 2024.
Contents