From feb2770291f65cf8239c08cb731123bff895878b Mon Sep 17 00:00:00 2001 From: Dmitry Semenov Date: Wed, 2 Mar 2022 12:25:31 +0300 Subject: [PATCH] Update "Setting up" section of README (#918) * Update private token documentation * Update public token documentation * Update installation instructions * Rename readme setting up section * Add setting up for web readme section * Rearrange setting up readme section * Add const to public token documentation Related to https://github.com/flutter/flutter/issues/55870 * Fix typo in readme --- README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 52 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index fdf4672f1..098eb9131 100644 --- a/README.md +++ b/README.md @@ -8,40 +8,79 @@ This Flutter plugin allows to show embedded interactive and customizable vector ![screenshot.png](screenshot.png) +## Setting up -## How to use +This package is available on [pub.dev](https://pub.dev/packages/mapbox_gl). -This project is available on [pub.dev](https://pub.dev/packages/mapbox_gl), follow the [instructions](https://flutter.dev/docs/development/packages-and-plugins/using-packages#adding-a-package-dependency-to-an-app) to add a package into your flutter application. +Get it by running the following command: -### Private Mapbox access token +``` +flutter pub add mapbox_gl +``` + +### Mobile -This project does require a Mapbox access token to download the underlying Android/iOS SDKs. The secret access token must have the *Download: read* scope for -[Android](https://docs.mapbox.com/android/maps/guides/install/) and/or +#### Secret Mapbox access token + +A secret access token with the `Downloads: Read` scope is required for the underlying Mapbox SDKs to be downloaded. +Information on setting it up is available in the Mapbox documentation: +[Android](https://docs.mapbox.com/android/maps/guides/install/), [iOS](https://docs.mapbox.com/ios/maps/guides/install/). -If this configuration is not present, an error like the following appears during -the build process: +If the properly configured token is not present, +the build process fails with one the following errors *(for Android/iOS respectively)*: -#### Android ``` * What went wrong: A problem occurred evaluating project ':mapbox_gl'. > SDK Registry token is null. See README.md for more information. ``` -#### iOS ``` [!] Error installing Mapbox-iOS-SDK curl: (22) The requested URL returned error: 401 Unauthorized ``` -### Public Mapbox access token +### Web + +Include the JavaScript and CSS files in the `` of your `index.html` file: + +``` + + +``` + +*Note: Look for latest version in [Mapbox GL JS documentation](https://docs.mapbox.com/mapbox-gl-js/guides/).* + +### All platforms -Next to a private access token you will need to provide an public access token -to retrieve the style and underlying resources. This can be done with running your application with an additional define statement: +#### Public Mapbox access token + +A public access token must be provided to a MapboxMap widget for retrieving styles and resources. +While you can hardcode it directly into source files, +it's good practise to retrieve access tokens from some external source +(e.g. a config file or an environment variable). +The example app uses the following technique: + +The access token is passed via the command line arguments when either building + +``` +flutter build --dart-define ACCESS_TOKEN=YOUR_TOKEN_HERE +``` + +or running the application + +``` +flutter run --dart-define ACCESS_TOKEN=YOUR_TOKEN_HERE +``` +Then it's retrieved in Dart: ``` -flutter run -d {device_id} --dart-define=ACCESS_TOKEN=ADD_YOUR_TOKEN_HERE` +MapboxMap( + ... + accessToken: const String.fromEnvironment("ACCESS_TOKEN"), + ... +) ``` ## Supported API