Project setup

VERSION 0.63.0

To use Maps SDK in your application you need to obtain a TomTom API key by following these instructions. Remember to keep your API key secure.

This guide describes how you can set up your iOS project to use the TomTom Maps SDK.

Before beginning, make sure you have Xcode 14 or 15 installed, created a new Xcode project, and set the deployment target to at least 14.0.

Adding dependencies

The Navigation SDK for iOS can be integrated into your project with CocoaPods or Swift Package Manager (SPM). To add dependencies, use the following instructions, depending on your preferred package manager:

Swift Package Manager

To incorporate each package into your project, follow these steps for the SDK packages:

Core: tomtom-sdk-spm-core

Here’s how to add each package to your project:

Click "File" > "Add Packages… / Add Package Dependencies…" in XCode.
In the "Enter Package URL" textbox, enter the URL for the respective package mentioned previously.
Set the "Dependency Rule" to "Exact Version."
Ensure that you’ve selected the appropriate project where you want to add this dependency and click "Add Package".
For test purposes, choose TomTomSDKMapDisplay from the Core product list.
Once the package is successfully resolved and added to your project, you can use this package by importing its modules into your Swift files:
```
import TomTomSDKMapDisplay
```

CocoaPods

Use the CocoaPods dependency manager and the cocoapods-art plugin to integrate the TomTom SDK into your project.

In this guide, we are using the cocoapods-art tool. We will install it as a Ruby gem. We are pinning the Ruby version with rbenv tool to manage Ruby gems.

Install rbenv using Homebrew with the following command:
```
brew install rbenv
```
Initialize rbenv. Run the following command and follow the instructions from the command’s output:
```
rbenv init
```
Load rbenv to Z shell:
```
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
```
The preview command assumes that Z shell is being used. If a different shell is used, you can find commands for the most common shells in rbenv documentation.
Get a list of the stable Ruby versions:
```
rbenv install --list
```
Install the Ruby version selected in the previous step. Run the following command replacing x.y.z with a selected version:
```
rbenv install x.y.z
```
This guide has been tested with Ruby version 3.0.0, therefore we recommend using this version.
Switch to your project’s directory. Set a previously installed Ruby version for your project:
```
rbenv local x.y.z
```
As a result, the .ruby-version file is created in your project’s directory. This file contains the Ruby version for your project.
Install the CocoaPods dependency manager. Run the following command from your project’s directory:
```
gem install cocoapods
```
Install the cocoapods-art plugin. Run the following command from your project’s directory:
```
gem install cocoapods-art
```
From now on, we assume that the CocoaPods dependency manager and the cocoapods-art plugin are accessible via the pod terminal command.

==# Configuring project dependencies

Clone tomtom-sdk-cocoapods pod specs repository to gain access to TomTom SDK frameworks by using the cocoapods-art plugin:
```
pod repo-art add tomtom-sdk-cocoapods "https://repositories.tomtom.com/artifactory/api/pods/cocoapods"
```
Generate a Podfile by running the following command in project directory:
```
pod init
```
Specify the platform and deployment target for the project. At the top of the Podfile add:
```
platform :ios, '14.0'
```
Specify the source of the TomTom SDK frameworks at top of the Podfile:
```
1plugin 'cocoapods-art', :sources => [
2  'tomtom-sdk-cocoapods'
3]
```
Add the module dependencies that you need in your application. Append the Podfile with the following lines:
```
1TOMTOM_SDK_VERSION = '0.63.0'
2
3target 'YourAppTarget' do
4  use_frameworks!
5  pod 'TomTomSDKMapDisplay', TOMTOM_SDK_VERSION
6  pod 'TomTomSDKRoutePlannerOnline', TOMTOM_SDK_VERSION
7  pod 'TomTomSDKRoutePlanner', TOMTOM_SDK_VERSION
8end
```
Update and install the dependencies by executing the following command in the project directory:
```
pod install --repo-update
```
Once the pod install command is successfully finished you should have the .xcworkspace file in the project directory. Open the .xcworkspace file to start working on the Xcode project.

Setup the API key on your project

Get your TomTom API key from the TomTom Developer Portal. To learn how, refer to the following guide: How to get a TomTom API key.
Create a Keys.swift file in your project and replace the API_KEY_PLACEHOLDER with your TomTom API Key:
```
1struct Keys {
2    static let tomtomApiKey = "API_KEY_PLACEHOLDER"
3}
```

Storing API keys directly in the codebase, as currently done, poses significant security risks and vulnerabilities; we strongly recommend adopting a more secure method for API key storage.

Learn more

Here are some suggestions for other things you can do: