Vecore Development Kit

# iOS

# Latest version

The latest version of the iOS SDK is version

-
. Please see the changelog for details.

# Introduction

The iOS SDK can be used to connect and control all Vecore platform based vehicles. When this SDK was designed, simplicity was a major pillar and has been integrated throughout the SDK. The SDK can only be used by issuing a token that works with in combination with your app identifier. Please contact development@vecore.nl to issue your token.

# Installation

# Using CocoaPods

CocoaPods (opens new window) is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate the VecoreSDK into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'VecoreSDK'

# Manual installation

A manual installation using the VecoreSDKFramework.framework file is also possible and can be downloaded below. Please note: Set the embedded SDK to either Embed & Sign or Embed & Do not sign for the SDK to load.

Download the latest ios SDK (v-)

# Usage

Since the SDK makes use of a singleton (sharedInstance), the SDK will be initialized on the first request. You do not need to worry about initializing the SDK yourself.

Note

All snippets below are written in Swift 5, but for each Swift function, there's an Objective-C variant available.

# Importing the SDK

Please use the following import statement.

import VecoreSDKFramework

# Debugging

# Enable debug mode logging

Sometimes you'd want to take a peek under the hood. This is done by setting the "debug handler" as follows:

VecoreSDK.sharedInstance.setDebugHandler { (logMessage) in
    print("SDK: \(logMessage)")
}

The SDK will now verbose log it's inner workings.

# Switching the debug environment

The SDK connects to the production environment by default. When connecting to vehicles that are defined in the debugging environment, switching the SDK to this same environment is necessary.

VecoreSDK.sharedInstance.setDebugEnvironmentEnabled(true)

# Authorizing

The SDK needs to be authorized using a token before other SDK functions are enabled. This is done using the authorize command below.

VecoreSDK.sharedInstance.authorize(token: "YOUR_TOKEN_HERE")

When interested in a response, a closure with one boolean parameter can be passed to the block as follows:

VecoreSDK.sharedInstance.authorize(token: "YOUR_TOKEN_HERE") { authorized in
    print("Authorized \(authorized)")
}

# Preloading reservation data

While it is not required, it is advised to preload reservation information so the reservation / key can be used much more swiftly or in offline scenarios. This is done using the preloadReservation command below.

  • privateManageKey: The String containing the private manage key of the reservation.
VecoreSDK.sharedInstance.preloadReservation(privateManageKey: "123abc456def789ghi987ihg654fed4321")

When interested in a response, a closure with one boolean parameter can be passed to the block as follows:

VecoreSDK.sharedInstance.preloadReservation(privateManageKey: "123abc456def789ghi987ihg654fed4321") { preloadSuccess in
    print("We \(preloadSuccess ? "successfully preloaded" : "could not load") the reservation")
}

# Connecting

# Connecting to a specific vehicle

In order to connect to a specific vehicle, call connect with the following parameters:

  • privateManageKey: The String containing the private manage key of the reservation.

This manage key is used to identify the reservation and vehicle. After passing this parameter the SDK will automatically search and connect to this vehicle.

VecoreSDK.sharedInstance.connect(privateManageKey: "123abc456def789ghi987ihg654fed4321") { (vehicleID: Int, connectionStatus: VecoreConnectionStatus) in
    if connectionStatus.statusCode == .Unavailable {
        print("Could not start search for vehicle with ID \(vehicleID).")
        return
    }

    self.isConnected = (connectionStatus.statusCode == .Connected)
}

Note

The connection will not be terminated automatically when calling connect and a connection is currently active.

Please manually call disconnect before starting another search. A VecoreConnectionStatus object with statusCode == .Unavailable will be returned through the connectionStatus closure. Also, the statusCodeDetail property will contain the value .ReservationAlreadyConnected.

# VecoreConnectionStatus

This object contains the current connection status information. The status object exposes the following three properties:

public var statusCode: VecoreConnectionStatusCode
public var statusCodeDetail: VecoreStatusCodeDetail
public var message: String
# statusCode

The property statusCode contains one of the VecoreConnectionStatusCode values:

Value Description
Unavailable The connection is unavailable due to hardware or another connection is currently active.
Disconnected There is no active connection.
Searching The device is busy searching the vehicle identified by privateManageKey.
Connecting The device is currently connecting to the vehicle identified by privateManageKey.
Authenticating The device is succesfully connected and is now authenticating.
Connected The device is connected and is ready to receive data and to send commands.
# statusCodeDetail

The property statusCodeDetail contains one of the VecoreStatusCodeDetail values:

Value Description
Unknown An unknown error occured.
SDKUnauthorized The SDK is unauthorized. Authorize using authorize().
ReservationNotFound The reservation was not found.
ReservationAlreadyConnected The SDK is already connected to a certain vehicle. Please disconnect first.
ReservationVehicleConnectionTypeNotFound The connection type for this reservation / vehicle combination was not found. Please report.
# message

The message property describes the status code, and the reason why an error occured. For example: "This reservation was not found in the system".

# Requesting a connection status update

After calling connect, the requestConnectionStatusUpdate function can be used to request an update. This update is sent to the statusHandler previously passed in the connect function.

VecoreSDK.sharedInstance.requestConnectionStatusUpdate()

# Disconnecting

# Disconnecting from a specific vehicle

When in need to discard the connection, for example when discarding the keys screen in your app, the connection can be closed as follows:

// Using a vehicle ID
VecoreSDK.sharedInstance.disconnect(vehicleID: 123)

// Using a manage key
VecoreSDK.sharedInstance.disconnect(privateManageKey: "123abc456def789ghi987ihg654fed4321")

Note

The connection will not be terminated automatically when calling connect while a connection is currently active - Please manually call disconnect before starting another search.

# Sending commands

After a connection has been established, certain commands can be sent to operate the vehicle. The parameter command can be one of the following:

# VecoreVehicleCommand

Value Description
Lock Locks the vehicle
Unlock Unlocks the vehicle

Sending the command is done using the sendVehicleCommand function.

VecoreSDK.sharedInstance.sendVehicleCommand(.Unlock)

# SDK Demo project

There is an XCode Demo project available to play with the SDK's basic functions.

Note

You will need a manage key of an active reservation in order to successfully authenticate with a vehicle. This manage key is obtained through fetching a reservation via the API.

# Demo application

# Demo application - Connected with vehicle

This demo application will output it's status in the label above the button. The button will change form once the vehicle is found and successfully connected.

Download the latest iOS SDK Demo project

# Changelog

Changes to the iOS SDK are described below. Contact Vecore to issue API / SDK keys or for any other inquiry. Please navigate to the Vecore website (opens new window) for contact details.