Skip to main content

Get Started

Additional Developer Resources

Before starting to develop your application with the Mapbox Maps SDK, you'll need to configure your credentials and add the SDK as a dependency to your Flutter project.

Configure credentials​

Before installing the SDK, you will need to gather the appropriate credentials.

The SDK requires two pieces of sensitive information from your Mapbox account. You can sign up if you do not have an account.

  • A public access token: from your account's tokens page, you can either copy your default public token or click the Create a token button to create a new public token. Creating a new token is the recommended option.
  • A secret access token with the Downloads:Read scope.
    1. From your account's tokens page, click the Create a token button.
    2. From the token creation page, give your token a name and make sure the box next to the Downloads:Read scope is checked.
    3. Click the Create token button at the bottom of the page to create your token.
    4. The token you've created is a secret token, which means you will only have one opportunity to copy it somewhere secure.

You should not expose these access tokens in publicly-accessible source code where unauthorized users might find them. Instead, you should store them somewhere safe on your computer and make sure they're only added when your app is compiled.

Configure your secret token​

Your secret token enables you to download the Android and iOS Mobile SDK files directly from Mapbox. Follow the steps below for each platform your Flutter app will run on.

Android​

Add your token as an environment variable:

  1. Find or create a gradle.properties file in your Gradle user home folder. The folder is located at «USER_HOME»/.gradle. Once you have found or created the file, its path should be «USER_HOME»/.gradle/gradle.properties. More details about Gradle properties in the official Gradle documentation.
  2. Add your secret token your gradle.properties file:
SDK_REGISTRY_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN

iOS​

To use your secret token, you will need to store it in a .netrc file in your home directory (not your project folder). This approach helps avoid accidentally exposing your secret token by keeping it out of your application's source code. Depending on your environment, you may have this file already, so check first before creating a new one.

Be sure .netrc has the correct file system permissions

The .netrc file needs 0600 permissions to work properly.

The .netrc file is a plain text file that is used in certain development environments to store credentials used to access remote servers. The login should always be mapbox. It should not be your personal username used to create the secret token. To set up the credentials required to download the SDK, add the following entry to your .netrc file:

machine api.mapbox.com
login mapbox
password YOUR_SECRET_MAPBOX_ACCESS_TOKEN

If you are having trouble with your .netrc file or the secret access token, follow our detailed instructions.

Configure your public token​

It's a good practice to retrieve your public token from some external source. You can then pass your token to the environment when building, running, or launching the Flutter app.

You can pass the public access token in using the --dart-define flag when running flutter build or flutter run on the command line:

$ flutter build <platform> --dart-define ACCESS_TOKEN=YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN
$ flutter run --dart-define ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN

If you are using Visual Studio Code, you can configure launch.json to add the --dart-define argument and each time the app is launched.

.vscode/launch.json
{
    "configurations": [
        {
            "name": "Flutter",
            "request": "launch",
            "type": "dart",
            "program": "lib/main.dart",
            "args": [
                "--dart-define",
                "ACCESS_TOKEN=YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN"
            ],
        }
    ]
}

Then, retrieve the token from the environment in the application and set it via MapboxOptions:

main.dart
...
String ACCESS_TOKEN = String.fromEnvironment("ACCESS_TOKEN");
MapboxOptions.setAccessToken(ACCESS_TOKEN);
...
GUIDE
Access token best practices

Learn how to keep access tokens private in mobile apps.

Add the dependency​

To use the Maps SDK for Flutter, add the git dependency to the pubspec.yaml:

pubspec.yaml
...
dependencies:
  mapbox_maps_flutter: ^2.0.0
...

Add a map​

Import the mapbox_maps_flutter library and add a map:

main.dart
import 'package:flutter/material.dart';
import 'package:mapbox_maps_flutter/mapbox_maps_flutter.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Pass your access token to MapboxOptions so you can load a map
  String ACCESS_TOKEN = const String.fromEnvironment("ACCESS_TOKEN");
  MapboxOptions.setAccessToken(ACCESS_TOKEN);

  // Define options for your camera 
  CameraOptions camera = CameraOptions(
    center: Point(coordinates: Position(-98.0, 39.5)), 
    zoom: 2, 
    bearing: 0, 
    pitch: 0);
  
  // Run your application, passing your CameraOptions to the MapWidget
  runApp(MaterialApp(home: MapWidget(
    cameraOptions: camera,
  )));
}

Launch your app for iOS or Android, and you'll see a full-screen globe centered on North America in your device emulator. You can move and zoom the map using touch gestures. As a next step, consider adding Markers and Annotations or changing the map style.

iOS
Android
Additional Developer Resources
Was this page helpful?