Getting Started

Using Mappedin SDK for iOS with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.

Mappedin SDK for iOS helps to deliver the rich indoor mapping experience of a venue, inside iOS apps.

The Mappedin SDK for iOS is a native interface to Mappedin JS. The SDK is a dependency built using Swift, and it automatically handles any authentication, network communication, fetching of map data, its display, and basic user interaction, such as panning, tapping, and zooming. The SDK allows a developer to build their own interactions. Additional layers can be rendered on top of the map.

info

Mappedin SDK for iOS is supported on iOS versions 13.0 and above.

Coding with AI

Mappedin SDK for iOS provides an llms-mappedin-ios.txt file that can be used to help with coding when using Large Language Models (LLMs).

Expand for instructions on how to use Mappedin provided llms.txt files with Cursor, Github Copilot, JetBrains AI Assistant and Windsurf.

How to use llms.txt files with LLMs:

Cursor

To use the llms.txt file with Cursor:

1. Download the llms.txt file for this guide.
2. Create a .cursor directory in your project root if it doesn't exist already.
3. Place the llms.txt file in the .cursor directory.
4. Start creating a new Cursor rule using Cursor's instructions.
5. Set the rule type to: Apply Intelligently.
6. Set the agent description to: Use this rule whenever a question is asked about Mappedin, Mappedin-JS, Mappedin SDK..
7. In the rule body, add the the llms.txt file as an mdc reference: [llms-mappedin-js.txt](mdc:.cursor/llms-mappedin-js.txt)
8. Optionally, if using Mappedin JS add an mde reference to the Mappedin JS TypeScript definitions: [@mappedin/mappedin-js TypeScript definitions](mdc:node_modules/@mappedin/mappedin-js/lib/esm/index.d.ts)
9. The full rull text should look like this:

   ---
   description: Use this rule whenever a question is asked about Mappedin, Mappedin-JS, Mappedin SDK.
   alwaysApply: false
   ---
   
   [llms-mappedin-js.txt](mdc:.cursor/llms-mappedin-js.txt)
   
   [@mappedin/mappedin-js TypeScript definitions](mdc:node_modules/@mappedin/mappedin-js/lib/esm/index.d.ts)
   

10. With this configuration, Cursor will automatically use the llms.txt whenever a question is asked about Mappedin, Mappedin-JS or Mappedin SDKs. When starting a new chat be sure to mention Mappedin to trigger the rule.
11. The llms.txt file includes:
    • Detailed explanations of concepts
    • Code examples and their context
    • Related documentation references
    • Source file locations for verification

This helps ensure that Cursor provides assistance that is consistent with Mappedin documentation and best practices, using the same structured information that's available on the Mappedin Developer Portal.

Github Copilot

To use the llms.txt file with GitHub Copilot Chat in VS Code:

1. Download the llms.txt file for this guide.
2. Create a .copilot directory in your project root if it doesn't exist already.
3. Place the llms.txt file in the .copilot directory.
4. When using Copilot Chat, you can reference the file by saying "Please use the context from the llms.txt file in the .copilot directory".
5. The llms.txt file includes:
   • Detailed explanations of concepts
   • Code examples and their context
   • Related documentation references
   • Source file locations for verification

This helps ensure that Copilot provides assistance that is consistent with documentation and best practices, using the same structured information that's available on the Mappedin Developer Portal.

JetBrains AI Assistant

To use the llms.txt file with JetBrains AI Assistant:

1. Download the llms.txt file for this guide.
2. Create a .idea/ai directory in your project root if it doesn't exist already.
3. Place the llms.txt file in the .idea/ai directory.
4. When using the AI Assistant, you can reference the file by saying "Please use the context from the llms.txt file in the .idea/ai directory".
5. The llms.txt file includes:
   • Detailed explanations of concepts
   • Code examples and their context
   • Related documentation references
   • Source file locations for verification

This helps ensure that the AI Assistant provides assistance that is consistent with documentation and best practices, using the same structured information that's available on the Mappedin Developer Portal.

Windsurf

To use the llms.txt file with Windsurf in VS Code:

1. Download the llms.txt file for this guide.
2. Create a .windsurf directory in your project root if it doesn't exist already.
3. Place the llms.txt file in the .windsurf directory.
4. When using Windsurf Chat, you can reference the file by saying "Please use the context from the llms.txt file in the .windsurf directory".
5. The llms.txt file includes:
   • Detailed explanations of concepts
   • Code examples and their context
   • Related documentation references
   • Source file locations for verification

This helps ensure that Windsurf provides assistance that is consistent with documentation and best practices, using the same structured information that's available on the Mappedin Developer Portal.

Xcode Project Setup

Add Mappedin SDK Using Swift Package Manager

Add the Mappedin SDK to your Xcode project using Swift Package Manager:

1. In Xcode, go to File > Add Package Dependencies
2. Enter the repository URL: https://github.com/MappedIn/ios.git
3. Select version 6.1.0-alpha.1
4. Click Add Package

Alternatively, you can add the package dependency to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/MappedIn/ios.git", from: "6.1.0-alpha.1")
]

The latest version can be found in the iOS GitHub repository releases.

Add Permissions

If you plan to display user location, add the following permissions to your Info.plist file:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to your location to show you on the map</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs access to your location to show you on the map</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to determine your location inside buildings</string>

Update the description strings to match your app's specific use case.

tip

The Mappedin iOS Github repository contains a reference project that demonstrates how to use the Mappedin SDK for iOS.

Display a Map

The core class of the Mappedin SDK for iOS is MapView, which is responsible for instantiating an WKWebView that loads Mappedin JS. MapView is the core class of which all other views and data models can be accessed.

Load Map Data

Call MapView.getMapData to load map data from Mappedin servers. This function must be called first and map data must be loaded before any other Mappedin functions can be called.

// See Trial API key Terms and Conditions
// https://developer.mappedin.com/docs/demo-keys-and-maps
let options = GetMapDataWithCredentialsOptions(
    key: "mik_yeBk0Vf0nNJtpesfu560e07e5",
    secret: "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
    mapId: "660c0c6e7c0c4fe5b4cc484c"
)
// Load the map data.
mapView.getMapData(options: options) { [weak self] r in
    guard let self = self else { return }
    if case .success = r {
        print("getMapData success")
    } else if case .failure(let error) = r {
        print("getMapData error: \(error)")
    }
}

Show a Map

Call MapView.show3dMap to display the map.

self.mapView.show3dMap(options: Show3DMapOptions()) { r2 in
    if case .success = r2 {
      print("show3dMap success")
    }
}

The following sample code combines the loading of map data and the display of the map and includes a function to be called when the map is ready.

import UIKit
import Mappedin

final class DisplayMapDemoViewController: UIViewController {
    private let mapView = MapView()
    private let loadingIndicator = UIActivityIndicatorView(style: .large)

    override func viewDidLoad() {
        super.viewDidLoad()
        title = "Display a Map"
        view.backgroundColor = .systemBackground

        let container = mapView.view
        container.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(container)

        // Add loading indicator
        loadingIndicator.translatesAutoresizingMaskIntoConstraints = false
        loadingIndicator.startAnimating()
        view.addSubview(loadingIndicator)

        NSLayoutConstraint.activate([
            container.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            container.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            container.topAnchor.constraint(equalTo: view.topAnchor),
            container.bottomAnchor.constraint(equalTo: view.bottomAnchor),

            loadingIndicator.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            loadingIndicator.centerYAnchor.constraint(equalTo: view.centerYAnchor),
        ])

		// See Trial API key Terms and Conditions
		// https://developer.mappedin.com/docs/demo-keys-and-maps
        let options = GetMapDataWithCredentialsOptions(
            key: "mik_yeBk0Vf0nNJtpesfu560e07e5",
            secret: "mis_2g9ST8ZcSFb5R9fPnsvYhrX3RyRwPtDGbMGweCYKEq385431022",
            mapId: "64ef49e662fd90fe020bee61"
        )
		// Load the map data.
        mapView.getMapData(options: options) { [weak self] r in
            guard let self = self else { return }
            if case .success = r {
                print("getMapData success")
				// Display the map.
                self.mapView.show3dMap(options: Show3DMapOptions()) { r2 in
                    if case .success = r2 {
                        DispatchQueue.main.async {
                            self.loadingIndicator.stopAnimating()
                        }
						self.onMapReady()
                    } else if case .failure(let error) = r2 {
                        DispatchQueue.main.async {
                            self.loadingIndicator.stopAnimating()
                        }
                        print("show3dMap error: \(error)")
                    }
                }
            } else if case .failure(let error) = r {
                print("getMapData error: \(error)")
            }
        }
    }

	// Place your code to be called when the map is ready here.
	private func onMapReady() {
		print("show3dMap success - Map displayed")
	}
}

Result

The app should display something that looks like this in the iPhone Emulator:

And zooming in to have a closer look:

Create a Key & Secret

A key and secret to use Mappedin Demo maps can be found on the Demo Keys & Maps Page. To use your own maps, create your own unique key and secret.

Using maps with your own key and secret requires a Pro or Solutions Map Account.

1. Log into the Mappedin Maker.
2. Click on the Developers tab.
3. Click Generate API Key.
4. Enter a name for the key.
5. Click Generate Key.
6. Store the key and secret is a safe and secure place.

Get a Map Id

Each map has a unique identifier used by Mappedin JS to load a map. To get the mapId of a map:

1. Log into the Mappedin Maker.
2. Click on the Developers tab.
3. Select the desired map from the dropdown.
4. The mapId will be shown in the code snippet.

Not seeing your map?

• Use of Mappedin JS requires a Pro or Enterprise Map Account. Demo API Keys will only work for Mappedin demo maps.
• Remember to set the map to Live. To do so click on the Share Maps button and change Draft to Live.

Debug Mode

Use Debug Mode to get a closer look at how various map components behave and interact. Here's how to enable it:

1. Enable Debug Mode

To activate the debug interface, call the following function in your code:

mapView.enableDebug()

MapView.enableDebug displays a panel on the right side of the map, revealing several tools and controls for direct interaction with the map's elements.

2. Navigating the Debug Panel

The debug panel provides access to a variety of controls:

Geometry Controls

• Adjust individual geometry settings, such as color, opacity, visibility. These controls make it easy to see how different elements respond to changes.

Interactivity

• Use toggles to turn interactivity on/off
• Change colors and hover effects to highlight specific areas

Scene Controls

• Manage the overall scene settings, such as scaling, positioning, and group management. Toggle the visibility of groups or containers within the scene
• Adjust padding, scale, and watermark positioning
• Markers & Labels — Add, remove, or edit markers and labels directly through the panel

Camera Controls

• Fine-tune camera settings, including zoom levels, pitch, and center position
• Set minimum and maximum zoom levels
• Adjust the focus to a specific area or level