Skip to content

CPIK Set Up Guide

This guide provides details on how to get started with iOS CPIK. 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 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 higher

Distribution

Included in the CPIK 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 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 (CoPilot 10.14.0.547 and Higher)

Note

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

  2. 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 Higher
  • Supported iOS Deployment Target - iOS 8.0 and Higher
  • Objective-C Automatic Reference Counting - Yes

How to import CPIK Sample application

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

It is very straightforward to open the XCode Sample application project. Following are the main component require for opening the XCode project

  1. Mac Machine
  2. XCode

In order to build the sample application project, one need to place CPIK Framework and resources at following location. CPIK Framework names as CoPilotIntegrationKit.Framework and Resources named as copilot_resources.bundle which can be found from CPIK bundle and need to put at following location. However CPIK build does contain and one don't need to put.

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 CoPilot Integration Kit 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 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 framework

The CPIK 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 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 framework.

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

Supported iOS SDK: iOS 8.0 and higher
CPIK supports iOS SDK 8.0+

Supported iOS Deployment Target: iOS 8.0 and higher
CPIK is only backwards compatible with iOS devices from iOS 8.0 and newer.

Initializing CPIK and Inserting the CoPilot view

The following steps show the code changes required to initialize the CPIK framework and display the CoPilot navigation app by inserting it's UIView into your application's view stack. The CPIK 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 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 header file

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

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

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 API methods cannot be called until CoPilot has finished starting up. Any call to the CPIK 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;
}

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 witness 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 Xcodes 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.

Understanding and Analyzing Application Crash Reports

Getting iOS crash logs


Last update: June 11, 2020