# Installation
> **Note (legacy): A newer version of the Maps SDK is available**
>
> This page uses v6.4.1 of the Mapbox Maps SDK. A newer version of the SDK is available. Learn about the latest version, v11.31.0, in the [Maps SDK documentation](https://docs.mapbox.com/ios/maps/guides/).
Before starting to develop your application with the Maps SDK, you'll need to configure your credentials and add the SDK as a dependency.
## Configure credentials
> **Note**
>
> If you plan to install the SDK via [direct download](#add-the-dependency), you do not need to configure a secret token. You will still need to configure a public token.
Before starting to develop your application with the Maps SDK, you'll need to create and configure your credentials.
### Step 1: Log in/Sign up for a Mapbox account
Login to your [Mapbox account](https://console.mapbox.com/). If you don't have an account, you can [sign up for free](https://account.mapbox.com/auth/signup/).
Your account includes a default public access token and allows you to create a secret access token for use in the installation of the SDK.
### Step 2: Configure your public token
Follow these steps to grab a public access token from your Mapbox account and add it to your project's `Info.plist`.
1. Open your project or create a new project in Xcode.
- If creating a new project, we recommend using the `App` project type.
2. Navigate to your project's `Info.plist` file.
- This is located in your main project page. You can go here by double clicking the project title in the top left corner, then `Info` in the middle of the screen.
3. Hover over a key and click the plus button.
4. Type `MBXAccessToken` into the key field and hit tab to select the value field.
5. Grab your default public access token.
- To grab your token, open up a browser and go to your account's [tokens page](https://console.mapbox.com/account/access-tokens/).
- On the top of your token list, copy your **Default Public Token**.
6. Go back to Xcode and in the value field, paste in your default public token.
Your public access token is now available for use in your iOS project and you will be able to access the Mapbox SDK.
> **Related content (guide): [Access token best practices](https://docs.mapbox.com/help/dive-deeper/private-access-token-android-and-ios/)**
>
> Learn how to keep access tokens private in mobile apps.
## Configure location permissions
The Mapbox Maps SDK for iOS requests permissions for user location on your behalf when `MGLMapView.showsUserLocation` is set to `YES`.
Prior to iOS 14, the device could only send the user's exact location. With iOS 14, users can opt into [Approximate Location](https://www.apple.com/ios/ios-14-preview/features/). Since users may toggle precise location off when initial permission for their location is requested by the app or in the System settings, developers are strongly encouraged to support Approximate Location.
### Handle the User Interface
The Maps SDK provides an approximate user location indicator that mirrors the approximate user location indicator previewed by Apple. This indicator will appear by default when `MGLMapView.showsUserLocation` is set to `YES` and precise location has been opted out. You may further configure or hide this component.
### Request temporary access to precise location
Certain application features may require precise location. The Mapbox Maps SDK for iOS provides a wrapper of Apple's CoreLocation APIs that requests temporary access to precise location when the user has opted out at the application settings level:
```xml
[MGLLocationManager.requestTemporaryFullAccuracyAuthorizationWithPurposeKey:]
```
Make the following adjustments to your Info.plist file to provide explanations for system prompts that may appear during location prompts:
Provide users a brief explanation of how the app will use their location data for temporary access:
```xml
NSLocationWhenInUseUsageDescription
Your precise location is used to calculate turn-by-turn directions, show your location on the map, and help improve the map.
```
Add `MGLAccuracyAuthorizationDescription` as an element of the `NSLocationTemporaryUsageDescriptionDictionary` dictionary to give users a brief explanation of why a feature in your app requires their exact location:
```xml
NSLocationTemporaryUsageDescriptionDictionary
MGLAccuracyAuthorizationDescription
Please enable precise location. Turn-by-turn directions only work when precise location data is available.
```
As a convenience, if your application uses a `MGLMapView.userTrackingMode` to track user location, the Maps SDK will check for full accuracy authorization and request access on your behalf.
## Handle changes in location authorization
At any point, a user may grant or revoke access to precise location in System settings. The Maps SDK for iOS provides a delegate method to handle these changes:
```
[MGLMapViewDelegate mapView:didChangeLocationManagerAuthorization:]
```
For more detail, see the [example](https://docs.mapbox.com/ios/legacy/maps/examples/approximate-location/) implementation of this delegate method.
After the current session elapses, your users will be prompted to give location permissions the next time they open your app. Your users must enable precise location during this prompt or in the app's System settings to avoid being asked repeatedly for location accuracy permissions.
## Add the dependency
Mapbox provides the Maps SDK via **Carthage**, **CocoaPods** , and **direct download**. You can choose whichever you prefer.
**CocoaPods**
To add the Mapbox Maps SDK dependency with CocoaPods, you will need to configure your build to download the Maps SDK from Mapbox directly. This requires a valid username and an access token with the `Downloads: Read` scope. In a previous step, you added these items to your `.netrc` file.
1. Add the following to your `Podfile`:
```ruby
use_frameworks!
target 'TargetNameForYourApp' do
pod 'Mapbox-iOS-SDK', '~> 6.4.1'
end
```
2. Run `pod install` to install the dependency.
**Carthage**
To add the Mapbox Maps SDK dependency with Carthage, you will need to configure your build to download the Maps SDK from Mapbox directly. This requires a valid username and an access token with the `Downloads: Read` scope. In a previous step, you added these items to your `.netrc` file.
1. Open your project in Xcode.
2. Confirm that you are using Carthage version `0.35.0` or higher.
3. Add the following to your `Cartfile`:
```
binary "https://api.mapbox.com/downloads/v2/carthage/mobile-maps/mapbox-ios-sdk-dynamic.json" ~> 6.4.1
github "mapbox/mapbox-events-ios" ~> 0.10.4
```
4. Install the SDK with `carthage update --platform iOS --use-netrc`.
5. Continue setting up the Maps SDK for iOS by following the [Carthage quick start instructions](https://github.com/Carthage/Carthage/#quick-start), starting with step 6 with both the generated `Mapbox.framework` and `MapboxMobileEvents.framework`.
> **Note (warning): Using Carthage bootstrap**
>
> Always use the --use-netrc flag when running carthage bootstrap.
**Direct download**
You can also download the Maps SDK for iOS directly. You need to be signed in to your Mapbox account to download the SDK directly.
1. Start by downloading the SDK with the button below.
Download for iOSYou must [sign in](https://account.mapbox.com/auth/signin/?route-to="") to download this SDK.
2. Once you have downloaded the SDK, unzip the file and navigate to the `dynamic` directory.
3. Drag both the `Mapbox.framework` and the `MapboxMobileEvents.framework` into your project's file navigator, making sure the `Copy items if needed` checkbox is selected.
4. Go to your app's target settings. Under `Frameworks, Libraries, and Embedded Content`, make sure that both `Mapbox.framework` and the `MapboxMobileEvents.framework` have their embed settings set to `Embed & Sign`.
## Add a map
You can add a map to your application in one of three ways: using **Swift**, **Objective-C**, or a **storyboard**. Select one of the following options to learn how to create a map using your preferred method.
> **Note**
>
> The Maps SDK can be used with **SwiftUI** by wrapping it in a `View` conforming to `UIViewRepresentable`. Refer to the [SwiftUI documentation](https://developer.apple.com/documentation/swiftui/uiviewrepresentable) for more details on how to use `UIViewRepresentable`.
**Swift**
Insert the following code snippets into your `ViewController`.
```swift
import Mapbox
class ViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
let url = URL(string: "mapbox://styles/mapbox/streets-v12")
let mapView = MGLMapView(frame: view.bounds, styleURL: url)
mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
mapView.setCenter(CLLocationCoordinate2D(latitude: 59.31, longitude: 18.06), zoomLevel: 9, animated: false)
view.addSubview(mapView)
}
}
```
**Objective-C**
Insert the following code snippets into your `ViewController`.
```objc
#import "ViewController.h"
@import Mapbox;
@implementation ViewController
- (void)viewDidLoad {
[super viewDidLoad];
NSURL *url = [NSURL URLWithString:@"mapbox://styles/mapbox/streets-v12"];
MGLMapView *mapView = [[MGLMapView alloc] initWithFrame:self.view.bounds styleURL:url];
mapView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[mapView setCenterCoordinate:CLLocationCoordinate2DMake(59.31, 18.06)
zoomLevel:9
animated:NO];
[self.view addSubview:mapView];
}
@end
```
**Storyboard**
In a storyboard, add a view to your View Controller. In the Identity inspector, change its class to `MGLMapView`. Then, in the Attributes inspector, set its Style URL to:
```
mapbox://styles/mapbox/streets-v12
```
Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/ios/ios/assets/medias/InstallIosMap-adc59e90093d73545876ff2fa9a55837.mp4).
Run your application and you will see a map on the screen.
Running into problems installing? Read more about common installation issues in our [troubleshooting guide](https://docs.mapbox.com/help/troubleshooting/ios-sdk-installation/).