Project setup

VERSION 0.28.2

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

The Navigation SDK for iOS is only available upon request. Contact us to get started.

  1. Before beginning, make sure you have Xcode installed, create a new Xcode project, and set the deployment target to at least 13.0.
  2. Open Xcode build setting for the project’s iOS application target. Configure the Excluded Architectures build setting to exclude arm64 architecture for Any iOS Simulator SDK as shown in the screenshot:
excluded architectures xcode build setting

Setting up CocoaPods

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

  1. Install rbenv using Homebrew:

    brew install rbenv
  2. Initialize rbenv. Run the following command and follow the instructions from the command’s output:

    rbenv init
  3. 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.

  4. Get a list of the stable Ruby versions:

    rbenv install --list
  5. 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.

  6. 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.

  7. Install the CocoaPods dependency manager. Run the following command from your project’s directory:

    gem install cocoapods
  8. 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.

Getting access

  1. Because the repository for Navigation SDK is private, you will need to contact us to get access.

  2. Once you have obtained access, go to and log in with your account. Expand the user menu in the top-right corner, and select "Edit profile" → "Generate an Identity Token". Copy the generated token and use it to specify your credentials in the ~/.netrc file. If the ~/.netrc file doesn’t exist, create one and add the following entries:

    • Replace the USERNAME_PLACEHOLDER with the login username or email you use for
    • Replace the IDENTITY_TOKEN_PLACEHOLDER with the generated identity token.
    • Add a new line to the end of the ~/.netrc file to avoid parsing errors.

Configuring project dependencies

  1. 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 ""
  2. Generate a Podfile by running the following command in project directory:
    pod init
  3. Specify the platform and deployment target for the project. At the top of the Podfile add:
platform :ios, '13.0'
  1. Specify the source of the TomTom SDK frameworks at top of the Podfile:
1plugin 'cocoapods-art', :sources => [
2 'tomtom-sdk-cocoapods'

+ . Verify that everything works as expected by adding the TomTomSDKNavigation module to your project’s Podfile.


3target 'YourAppTarget' do
4 use_frameworks!
5 pod 'TomTomSDKNavigation', TOMTOM_SDK_VERSION

+ Update and install the dependencies by executing the following command in the project directory:


pod install --repo-update
  1. 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.
  2. 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.
  3. Create a Keys.swift file in your project and replace the API_KEY_PLACEHOLDER with your TomTom API Key:
1struct Keys {
2 static let ttAPIKey = "API_KEY_PLACEHOLDER"

Now that you’ve completed the project setup, here is what you can do next.

Build a simple navigation application

Use all relevant Navigation SDK APIs and built-in UI components to build a navigation application:

Learn more

Here are some suggestions for other things you can do: