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 flutter/flutter#55870 * Fix typo in readme
flutter-mapbox-gl · Mar 2, 2022 · feb2770 · feb2770
1 parent 87b8344
commit feb2770
Showing 1 changed file with 52 additions and 13 deletions.
diff --git 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 `<head>` of your `index.html` file:
+
+```
+<script src='https://api.mapbox.com/mapbox-gl-js/v2.7.0/mapbox-gl.js'></script>
+<link href='https://api.mapbox.com/mapbox-gl-js/v2.7.0/mapbox-gl.css' rel='stylesheet' />
+```
+
+*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 <platform> --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