Setup Guide for iOS SDK Libraries

Contents

Note: The SDK Libraries React Native framework and the sample app use React Native version 0.60.5.

React Native is a cross-platform framework that allows you to build native mobile applications with JavaScript. As a result, you can develop iOS and Android applications that share most of the same code.

With our CoPilot React Native module, you can integrate turn-by-turn, voice-guided navigation into your application by calling our SDK Libraries APIs.

The goal of this guide is to get you set up to build an iOS application.

What You’ll Need #

  • Xcode 9.4 or above.
  • Node 8.3 or above (installing Node will automatically install npm as well)
  • React Native CLI
  • Homebrew
  • CocoaPods

Environment Setup #

Step 1: Install Xcode #

Xcode is available from the App Store. You will also need to install the Xcode Command Line Tools.

  • Open Xcode, then choose Preferences from the Xcode menu.
  • Go to the Locations panel and install the tools by selecting the most recent version in the Command Line Tools dropdown.

Step 2: Install Homebrew #

Step 3: Install Node #

Run the following command in Terminal: brew install node

Step 4: Install React Native CLI #

Run the following command in Terminal: npm install -g react-native-cli

Step 5: Install Cocoapods #

Run the following command in Terminal: $ brew install cocoapods

Integrating SDK Libraries React Native Framework Into an Existing Application #

In this section, we assume the application that the SDK Libraries React Native (RN) framework is going to be integrated into has all RN environments set up already. That is, all relative RN libraries have been installed and linked properly in the application project.

  1. Link application with CoPilotIntegrationKit.framework. You can grab this framework from the delivered package: The path is com.alk.CPIKReactNativeSampleApp\Library and Resource\ios\framework

  2. Link application with CPIKReactNative.framework. You can grab this framework from the delivered package: The path is com.alk.CPIKReactNativeSampleApp\Library and Resource\ios\framework

  3. Add SDK Libraries resources bundle to application support files. You can grab this framework from the delivered package: The path is com.alk.CPIKReactNativeSampleApp\Library and Resource\ios\resources

You can now use SDK Libraries React Native APIs.

Integrating Into a Non-React Native Application #

In this section, we will guide how to integrate SDK Libraries RN framework into a new project from scratch.

  1. Follow all steps mentioned in the Environment Setup section above.

  2. Create a React Native project structure:

    • Create application root folder, let’s say “RNCpikSampleApp”.
    • Create “ios” folder under “RNCpikSampleApp” directory and move your application project into this folder.
  3. Install required react and react native dependencies:

    • Create package.json under your application root folder (“RNCpikSampleApp”, for example). Below is an example package.json file that we’re using in our SDK Libraries React Native sample app:
    {
      "name": "RNCpikSampleApp",
      "version": "0.0.1",
      "private": true,
      "scripts": {
        "start": "node node_modules/react-native/local-cli/cli.js start",
        "test": "jest"
      },
      "dependencies": {
        "react": "16.6.3",
        "react-native": "0.58.3",
        "react-native-actionsheet": "^2.4.2",
        "react-native-dialog-input": "^1.0.7",
        "react-native-gesture-handler": "^1.0.15",
        "react-navigation": "^3.1.4",
        "create-react-context": "^0.2.3"
      },
      "devDependencies": {
        "babel-core": "7.0.0-bridge.0",
        "babel-jest": "24.1.0",
        "jest": "24.1.0",
        "metro-react-native-babel-preset": "0.51.1",
        "react-test-renderer": "16.6.3"
      },
      "jest": {
        "preset": "react-native"
      }
    }
    
    • Run command npm install to install those dependencies. You will see a directory node_modules has been created under application root folder. This folder contains all react dependencies.
  4. Link installed react native dependencies:

    • We will demonstrate how to use CocoaPods to manage the RN dependencies. However, you can use the “react-native link” command or manually link as well.
    • Create a Pod file in the directory where your Xcode project is located (“RNCpikSampleApp\ios”, for example) and configure it based on what RN dependencies you need. Below is an example Pod file in our sample app:
    platform :ios, '9.0'
    target 'CPIKReactNative' do
    pod 'React', :path => '../../react_native/RNCpikSampleApp/node_modules/react-native', :subspecs => [
      'Core',
      'CxxBridge',
      'DevSupport',
      'RCTText',
      'RCTNetwork',
      'RCTWebSocket',
      'RCTAnimation',
    ]
    pod 'yoga', :path => '../../react_native/RNCpikSampleApp/node_modules/react-native/ReactCommon/yoga'
    pod 'DoubleConversion', :podspec => '../../react_native/RNCpikSampleApp/node_modules/react-native/third-party-podspecs/DoubleConversion.podspec'
    pod 'glog', :podspec => '../../react_native/RNCpikSampleApp/node_modules/react-native/third-party-podspecs/glog.podspec'
    pod 'Folly', :podspec => '../../react_native/RNCpikSampleApp/node_modules/react-native/third-party-podspecs/Folly.podspec'
    end
    
    • Run the command: pod install
    • An Xcode workspace file will be generated and its name is the same as your existing Xcode project. All RN linkings have been automatically done. From now on, you should only use the Xcode workspace.
  5. Link application with CoPilotIntegrationKit.framework:

    • You can grab this framework from the delivered package: com.alk.CPIKReactNativeSampleApp\Library and Resource\ios\framework
  6. Link application with CPIKReactNative.framework:

    • You can grab this framework from the delivered package: com.alk.CPIKReactNativeSampleApp\Library and Resource\ios\framework
  7. Add SDK Libraries resources bundle to application support files:

    • You can grab this framework from the delivered package: com.alk.CPIKReactNativeSampleApp\Library and Resource\ios\framework

You can now use SDK Libraries React Native APIs.

Build SDK Libraries React Native Sample App #

We provide our customers with a SDK Libraries RN sample app project in the delivered package. It’s located in: com.alk.CPIKReactNativeSampleApp\SampleApp\RNCpikSampleApp

In this section, we will guide you how to build the sample app.

  1. Follow all steps mentioned in the Environment Setup section above.
  2. Run the command npm install in com.alk.CPIKReactNativeSampleApp\SampleApp\RNCpikSampleApp
  3. Run the command pod install in com.alk.CPIKReactNativeSampleApp\SampleApp\RNCpikSampleApp\ios
  4. Open CPIKSampleApp.xcworkspace
  5. If you want to build with Release, you can just build and run.
  6. If you want to build with Debug, you need to open the following file:
    • Open com.alk.CPIKReactNativeSampleApp\SampleApp\RNCpikSampleApp\ios\CPIKSampleApp\AppDelegate.m
    • Input your IP address in line 23. If you’re deploying to an actual device, make sure your device connects to the same network as your Mac.
    • In RNCpikSampleApp directory, run command npm start in terminal.
    • Build and run.

Sample Code #

Start CoPilot #

import { NativeModules } from "react-native";

if (Platform.OS == "android") {
  const { CopilotStartupMgr } = NativeModules;
  CopilotStartupMgr.bindCoPilotService();
} else NativeModules.Copilot.startNavApp();

Exit CoPilot #

import {NativeModules} from 'react-native';
componentWillUnmount() {
       if (Platform.OS == 'android')
           CopilotStartupMgr.unbindCopilotService();
       else
           CopilotApplication.shutdownNavApp();
}

License Activation #

import { NativeModules } from "react-native";

const LicenseMgr = NativeModules.LicenseMgr;
var status = await LicenseMgr.activateLicense(
  XXXXX - XXXXX - XXXXX - XXXXX - XXXXX,
  null
);

Callback Registration #

Callback register and unregister should be done on componentDidMount and componentWillUnmount.

import {NativeModules} from 'react-native';
import { DeviceEventEmitter, NativeEventEmitter } from 'react-native';

const CopilotListener = NativeModules.CopilotListener;
const CopilotEventEmitter = Platform.OS == 'android' ? DeviceEventEmitter : new NativeEventEmitter(CopilotListener);

onCPStartup = () => {
      console.log('onCPStartup received');
}

onCPShutdown = () => {
      console.log('onCPShutdown received');
}

componentDidMount() {
   this.onCPStartuplistener =  CopilotEventEmitter.addListener('onCPStartup', this.onCPStartup);
   this.onCPShutdownlistener = CopilotEventEmitter.addListener('onCPShutdown', this.onCPShutdown);
}

componentWillUnmount() {
   this.onCPStartuplistener.remove();
   this.onCPShutdownlistener.remove();
}

Display CoPilot View #

Step 1: Expose native view component in CopilotView.js

import { requireNativeComponent } from "react-native";

module.exports = requireNativeComponent("CopilotView", null);

Step 2: Render the exported native view in your react component

import React, { Component } from "react";
import CopilotView from "./CopilotView.js";

class CopilotScreen extends React.Component {
  static navigationOptions = {
    title: "Copilot",
  };

  render() {
    return <CopilotView style={{ flex: 1 }} />;
  }
}

Get Configuration #

import { NativeModules } from "react-native";

const CopilotMgr = NativeModules.CopilotMgr;
const ConfigurationName = NativeModules.ConfigurationName;

var config = await CopilotMgr.getConfigurationSetting(
  ConfigurationName.GPS_FREQUENCY
);
console.log(config.value);

Set Configuration #

import { NativeModules } from "react-native";

const CopilotMgr = NativeModules.CopilotMgr;
const ConfigurationName = NativeModules.ConfigurationName;
const ConfigurationValue = NativeModules.ConfigurationValue;

var configSetting = {};
configSetting.name = ConfigurationName.CHEVRON_DISPLAY;
configSetting.value = ConfigurationValue.CHEVRON_DISPLAY_LAT_LON;
CopilotMgr.setConfigurationSetting(configSetting);
Last updated April 29, 2021.