iOS SDK
iOS SDK allows you to add an 2GIS map to your iOS application. Using the SDK, you can display a map on the screen, get information about map objects, use the navigator, build routes, and so on.
See SDK usage examples in the Examples section. For a detailed description of all classes and methods, see API Reference.
Geodata complies with OGC standards.
SDK versions
iOS SDK packages are available in two versions:
- Full is a full version that allows you to:
- Add a map to the application and manage it: add markers and geometric shapes, control the camera movement, display layers (for example, traffic), work with map styles, etc.
- Search for objects in the directory: organizations, buildings, places, and others.
- Work with the navigator in the application in one of the three modes: free-drive, turn-by-turn, or simulated navigation.
- Build optimal routes on the map, including routes inside buildings.
- Use offline data.
- Map is a lightweight version that allows you to:
Important
You cannot use Full and Map simultaneously. It causes an assembly error.
Getting API keys
To work with the SDK, you need to get a key file dgissdk.key
. It allows connecting to 2GIS servers and retrieving the geographical data, as well as using offline data and the navigator. To obtain the key file, fill in the form at dev.2gis.com and specify the appId
of the application for which the key is created.
After you receive the key, initialize the SDK. Follow the requirements:
- You can initialize the SDK only once per application. Only one key can be used for each application. Different keys are required in the following cases:
- If the application is available for different operating systems.
- If the application has several alternatives for a single OS (for example, one application for the driver and another for the passenger).
- If different SDK versions are used (Full and Map).
- The
appId
value of the application must match theapp_id
value in the key file. - Changing the key file while the application is running is not supported. Since the key file is selected during SDK initialization, you can give them different names (by default,
dgissdk.key
is used). To do this, pass a key with a different name via thekeySource
parameter inDGis.Container
.
Some SDK features use search and navigation APIs. Access to these APIs is provided with the SDK key. API usage is paid additionally, depending on the number of sent requests (and in some cases, on the number of received responses). See the list of features and additional APIs below.
Additional APIs
You can check the statistics of API request distribution in the Platform Manager.
Feature |
APIs |
---|---|
Creating a search engine (SearchManager class) |
Regions API |
Getting search results (SearchManager.search method) |
Access to certain information about objects is only available with additional key configuration for an extra fee: see the Object data structure section. |
Searching for objects in the directory by ID (SearchManager.searchById method) |
|
Building search suggestions (SearchManager.suggest method) |
Suggest API |
Searching for an optimal route considering traffic jams (TrafficRouter class) |
|
Starting the navigation (NavigationManager.start method): |
|
Searching for alternative routes (AlternativeRouteSelector class) |
|
Displaying routes on the map (RouteEditorSource class) |
|
Displaying traffic jams on the map (TrafficSource class) |
Regions API |
Displaying road events (RoadEventSource class) |
Regions API |
System requirements
- Xcode 14
- iOS 13 and later / iPadOS 13 and later (this SDK uses SwiftUI)
Installation
Swift Package Manager
To install iOS SDK via Swift Package Manager, add a package dependency to your project. See Apple documentation for instructions on installing Swift packages.
To connect SDK, specify the URL depending on the version:
https://github.com/2gis/mobile-sdk-full-swift-package
for the Full SDK version.https://github.com/2gis/mobile-sdk-map-swift-package
for the Map SDK version.
CocoaPods
To install iOS SDK via CocoaPods, add the DGisMobileSDK
dependency.
Use Swift Package Manager versioning, adding the -full
or -map
postfix, depending on the required SDK version.
You can view the pod specification at one of the following URLs:
https://github.com/2gis/mobile-sdk-full-swift-package/blob/master/DGisMobileSDK.podspec
for the Full SDK version.https://github.com/2gis/mobile-sdk-map-swift-package/blob/master/DGisMobileSDK.podspec
for the Map SDK version.
Binary artifact
You can download frameworks directly without using package managers. To do this, refer to the repository that contains the package specification for CocoaPods or Swift Package Manager:
https://github.com/2gis/mobile-sdk-full-swift-package
for the Full SDK version.https://github.com/2gis/mobile-sdk-map-swift-package
for the Map SDK version.
The Package.swift
file will contain a URL leading to downloading the SDK archive via a direct link. To navigate through versions, use git tags.
Demo project
You can find a demo app with the source code in the GitHub repository.