Getting Started with iOS
In this tutorial we provide instructions for getting started with the iOS SDK – HMKit. The SDK consists of four different libraries that enable your application to work with vehicle data: AutoAPI, HMCryptoKit, HMUtilities and HMKit.
Introduction and Setup
Requirements
All libraries are written in Swift 5.1 and require iOS 10 or above.
Integration
There are several ways to integrate the Swift libraries.
As frameworks:
Least recommended
Each lib's Xcode project can be built as a .framework and the resulting package (file) dragged to your own Xcode project. This only creates the framework for a device or a simulator, which could be lipo-d together to develop your application and run it on both a device and a simulator. The simulator slices need to be removed before being able to upload to AppStoreConnect.
As XCFrameworks:
Recommended when SPM usage is not possible
Each lib has a script XCFrameworkBuilder.sh in Scripts/ folder. When running this from the root dir, the .xcframwork package (file) will be built. This contains both device and simulator binaries that should be dragged to your own Xcode project. Then Xcode selects automatically which binary to use, thus enabling development on both a device and a simulator. No futher action is needed to upload to AppStoreConnect.
Through Swift Package Manager:
Recommended
Easiest would be to use the build-in SPM in Xcode 11+ and add the following dependencies to your project or Package.swift: AutoAPI, HMCryptoKit, HMUtilities, HMKit.
This has the benefits of not having to deal with manually copying/dragging files (packages can be updated from Xcode) nor worring about AppStoreConnect upload.
Create an App
In the Develop tab you will find your apps. In the app details page you are going to set the permissions it requires, manage devices and link virtual vehicles from your garage to test. At first you will find a Sandbox app which you can work on, but let's see how to create a new app.
- Go to the Develop tab, click the big plus (+) button and select Device App. Enter a name and continue.
- In the left section, select the permissions that your app needs under the "Permissions" tab. For the purporses of this tutorial, you will need to toggle the "Show all permissions" button, expand the "Door locks" capability, and select "Positions" and "Lock unlock doors" before pressing "save".
Note: Each permission must now manually be added to each new app. - You can edit your app name and image from the menu icon next to the app name.
Create a Vehicle
In the carmaker workspaces you will be able to create vehicles or other items to link with your app and to test with the emulators.
- Go to a carmaker workspace, click the big plus (+) button and select one vehicle to start. Enter a name and continue.
- You will find the vehicle capabilities listed to the left.
- If you click on the "Launch emulator" button you will see how it looks like. Next we will need to link an app with the vehicle.
Initialise the SDK
For a straight forward example of how to initialise the SDK, download the iOS Scaffold sample app from GitHub.
- Once you have downloaded the SDK or sample app, go to the Apps tab, and select the app you created in the previous steps.
- Choose "Device certificates" from the left section and enter a name for the device.
- Click on the device you just created and copy the snippet.
- Insert the snippet into into the Xcode project to initialize the SDK.
Link Vehicle and Authorise Device
Now you just need to link the vehicle with the app in order to work with it in the emulator. Follow the next steps:
- Go back to your app details page in the Apps tab and click on the "Create link" button on the right side.
- Choose the vehicle you just created and link it to your app. The vehicle will be added to linked vehicles list but you will see an alert icon between the app and the vehicle. That means that there is yet no device that has been authorised to interact with the vehicle.
- Click on the alert icon and you will see an Access Token snippet that is unique to this link. Copy it.
Insert the snippet into your Xcode project and run the app on your device. - Click on the vehicle to launch the emulator. This time you can start using your app to interact with the vehicle's APIs.
Production mode
In order to get an Access Token for a production app, use the OAuth2 consent flow functionality.
The code snippet in your Xcode project should look something like this:
try HMTelematics.downloadAccessCertificate(accessToken: "QLDiUUuVZzkTsh...VTVkDi5nO8T") { result in
// Handle the result
}
Send a Telematics Command
Once the emulator is open, fire away a Telematics command. For example to unlock the doors of the vehicle. Note that you will get a "Vehicle Asleep" error returned if the emulator is closed.
If you see that the app lacks permissions, you will need to revisit step two of the "Create an App" section of this document and select the appropriate permissions for your telematics command.
Read more about Telematics
Auto API
Check out the iOS code reference for Auto API for further details on how to use vehicle commands.
let bytes = AADoors.lockUnlockDoors(insideLocksState: .locked)
try HMTelematics.sendCommand(bytes, serial: vehicleSerial) { result in
// Handle the result
}