Document how to add Mapbox to Android Studio

[xobs]

New Feature

The instructions at https://docs.mapbox.com/android/navigation/guides/get-started/install/ purport to describe how to add Mapbox Android to a project. However, the documentation appears to be incomplete, outdated, or incorrect.

Why

I am not familiar with Android Studio, so I thought I'd refer to Mapbox documentation in order to try out their widget. However, the documentation appears to not match what I'm seeing:

1. There is no R.strings.xml file present. Perhaps you meant res/values/strings.xml?
2. The path to AndroidManifest.xml is not entirely clear. I believe you meant manifests/AndroidManifest.xml
3. The installation instructions say to add a string to settings.gradle or build.gradle, however neither of these files exist. I attempted to add them to settings.gradle.kts or either of the two copies of build.gradle.kts, but that resulted in a syntax error.
4. Copying the maven {} key from build.gradle.kts into my project results in an error e: settings.gradle.kts:17:67: Function invocation 'project(...)' expected

Overall I would like there to be documentation on how to get started, but as-is the documentation seems to be misleading or invalid, and so I don't know that I can get started.

[Mr94t3z]

Maybe you can try this:

On strings.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="mapbox_access_token">YOUR_PUBLIC_KEY</string>
</resources>

Then, add MAPBOX_DOWNLOADS_TOKEN=YOUR_SECRET_KEY to gradle.properties

[xobs]

I think the issue is that the build system needs to download the libraries, so they need to be present in a format that the build system can read. strings.xml will just add it to the runtime. However, the project will fail to build.

The solution appears to be to modify settings.gradle.kts to look like this:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            authentication {
                create<BasicAuthentication>("basic")
            }
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
            credentials {
                username = "mapbox"
                password = if (providers.gradleProperty("MAPBOX_DOWNLOADS_TOKEN").isPresent) {
                    providers.gradleProperty("MAPBOX_DOWNLOADS_TOKEN").get()
                } else {
                    System.getenv("MAPBOX_DOWNLOADS_TOKEN")
                } ?: throw IllegalArgumentException("MAPBOX_DOWNLOADS_TOKEN key is not specified")
            }
        }
    }
}

I believe what's hapened is Google has updated Android Studio so it now produces "kotlin" build files rather than "gradle" build files, or something to that effect. So the existing documentation is for the old build system, and needs to be updated for the modern build system.

[dryaz]

The instructions at https://docs.mapbox.com/android/navigation/guides/get-started/install/ purport to describe how to add Mapbox Android to a project. However, the documentation appears to be incomplete, outdated, or incorrect.

You reffer to the NAVIGATION sdk but not the MAP sdk at the first place, check this out if it solve your issue: https://docs.mapbox.com/android/maps/guides/install/

[xobs]

The maps SDK also appears to refer to settings.gradle which doesn't exist in new projects created with the latest Android Studio. It only refers to "Android Studio Arctic Fox (2020.3.1) or later and Gradle v6.0 or later", and "Android Studio Giraffe" is newer than "Android Studio Arctic Fox".

Additionally, the Navigation SDK doesn't say you need to install the Map SDK first, so I'm not sure if it's required. If it is required, then the instructions should be updated to mention that.

[dudeuter]

@xobs Recently, Android Studio switched the default from the Groovy Gradle DSL to the Kotlin Gradle DSL, which is the primary reason the docs are out of date at the moment and the reason that you don't have a settings.gradle file.

If you choose Groovy DSL the existing docs will work, although I would recommend using Kotlin and porting the configuration as you did above.

The existing docs ported to Kotlin are verbatim:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
            authentication {
                create<BasicAuthentication>("basic")
            }
            credentials {
                // Do not change the username below.
                // This should always be `mapbox` (not your username).
                username = "mapbox"
                // Use the secret token you stored in gradle.properties as the password
                val MAPBOX_DOWNLOADS_TOKEN: String by settings
                password = MAPBOX_DOWNLOADS_TOKEN
            }
        }
    }
}

Our instructions don't recommend providing the access tokens as an environment variable, although this is more or less splitting hairs, you should feel comfortable using whichever method helps meet your security requirements.