Skip to content

Installation

Gradle Plugin

Add GitHub Package Registry

Create GitHub token

GitHub package registry requires authentication credentials. These must be created by following the guide here: https://github.com/settings/tokens/new

You will need to enable the following scope on the GitHub token creation form:

read:packages

Add GitHub Package Registry to project Gradle

If your project uses the legacy buildscript { dependencies } method to add build script dependencies then add the Github package registry to the top level build.gradle file as so:

build.gradle
buildscript {
    repositories {
        maven {
            url = "https://maven.pkg.github.com/attractions-io/maplayr-android"
            credentials {
                username "GitHub username here"
                password "GitHub token with packages read access here"
            }
        }
    }
}
build.gradle.kts
buildscript {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/attractions-io/maplayr-android")
            credentials {
                username = "GitHub username here"
                password = "GitHub token with packages read access here"
            }
        }
    }
}

An example can be found here: build.gradle

If your project uses the pluginManagement { repositories } method to configure plugin resolution then add the Github package registry to the settings.gradle file as so:

settings.gradle
pluginManagement {
    repositories {
        maven {
            url = "https://maven.pkg.github.com/attractions-io/maplayr-android"
            credentials {
                username "GitHub username here"
                password "GitHub token with packages read access here"
            }
        }
    }
}
settings.gradle.kts
pluginManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/attractions-io/maplayr-android")
            credentials {
                username = "GitHub username here"
                password = "GitHub token with packages read access here"
            }
        }
    }
}
Use environment variables for credential storage To avoid saving your GitHub credentials directly in your repo you can add them to your environment variables. They can then be accessed like so: === "Groovy"
build.gradle
buildscript {
    repositories {
        maven {
            url = "https://maven.pkg.github.com/attractions-io/maplayr-android"
            credentials {
                username System.getenv("GITHUB_USERNAME")
                password System.getenv("GITHUB_TOKEN")
            }
        }
    }
}
=== "Kotlin"
settings.gradle.kts
buildscript {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/attractions-io/maplayr-android")
            credentials {
                username = System.getenv("GITHUB_USERNAME")
                password = System.getenv("GITHUB_TOKEN")
            }
        }
    }
}

Add the MapLayr plugin class path to Gradle

Add the MapLayr plugin class path to Gradle by adding the following dependency to the top level build.gradle as so:

build.gradle
buildscript {
    dependencies {
        classpath 'io.attractions:maplayr-plugin:0.0.93'
    }
}
build.gradle.kts
plugins {
    id("io.attractions.maplayr-plugin") version("0.0.93")
}

An example can be found here: build.gradle

Add MapLayr Plugin to Gradle

Add the MapLayr plugin to Gradle in the app module build.gradle as so:

app/build.gradle
plugins {
    id 'io.attractions.maplayr-plugin'
}
app/build.gradle.kts
plugins {
    id("io.attractions.maplayr-plugin") version("0.0.93")
}

An example can be found here: app/build.gradle

Legacy Gradle syntax 
apply plugin: 'io.attractions.maplayr-plugin'

Use MapLayr Plugin

In the app module build.gradle configure the plugin.

API Key

The apiKey is required for any usage of the SDK

app/build.gradle
attractionsIo {
    apiKey = "{api_key}"
}
app/build.gradle.kts
attractionsIo {
    apiKey = "{api_key}"
}

An example can be found here: app/build.gradle

Bundle maps at build time

Maps can be downloaded at build time and bundled into the resulting aab or apk file, which makes the maps available for immediate use when the user opens the app even if they are offline.

Bundle a single map

To bundle a single map specify the desired map id using the mapId key as so:

app/build.gradle
attractionsIo {
    mapId = "{map_id}"
}
app/build.gradle.kts
attractionsIo {
    setMapId("{map_id}")
}

This map id can be retrieved in your code by using BuildConfig.MAPLAYR_MAP_0 if buildConfig is enabled in your app's gradle file

app/build.gradle
android {
    buildFeatures {
        buildConfig = true
    }
}
app/build.gradle.kts
android {
    buildFeatures {
        buildConfig = true
    }
}
Bundle multiple maps

Multiple maps can be specified by using the mapIds key as so:

app/build.gradle
attractionsIo {
    mapIds = ["{map_id_1}", "{map_id_2}", ...]
}
app/build.gradle.kts
attractionsIo {
    setMapIds(listOf("{map_id_1}", "{map_id_2}", ...))
}

These map ids can be retrieved in your code by using BuildConfig.MAPLAYR_MAP_0, BuildConfig.MAPLAYR_MAP_1, ... , BuildConfig.MAPLAYR_MAP_N if buildConfig is enabled in your app's gradle file

app/build.gradle
android {
    buildFeatures {
        buildConfig = true
    }
}
app/build.gradle.kts
android {
    buildFeatures {
        buildConfig = true
    }
}
Bundle named map(s)

Map id(s) can be provided alongside a friendly name by using the maps key as so:

app/build.gradle
attractionsIo {
    maps = [
        "{my_first_map}": "{map_id_1}",
        "{my_second_map}": "{map_id_2}",
        ...
    ]
}
app/build.gradle.kts
attractionsIo {
    setMaps(
        mapOf(
            "{my_first_map}" to "{map_id_1}", 
            "{my_second_map}" to "{map_id_2}", 
            ...
        )
    )
}

These map id(s) can be retrieved in your code by using the friendly name(s); BuildConfig.MAPLAYR_MAP_MY_FIRST_MAP, BuildConfig.MAPLAYR_MAP_MY_SECOND_MAP if buildConfig is enabled in your app's gradle file

app/build.gradle
android {
    buildFeatures {
        buildConfig = true
    }
}
app/build.gradle.kts
android {
    buildFeatures {
        buildConfig = true
    }
}
Build variants, build types & product flavors

Any of the methodologies above for specifying map ids to be bundled into the app at build time can be nested in the build variants, build types or product flavors namespace to make them specific to that build.

app/build.gradle
attractionsIo {
    variants {
        variant1 {
            mapId = "{map_id}"
        }
        variant2 {
            mapId = "{map_id}"
        }
    }
    buildTypes {
        buildType1 {
            mapId = "{map_id}"
        }
        buildType2 {
            mapId = "{map_id}"
        }
    }
    productFlavors {
        productFlavor1 {
            mapId = "{map_id}"
        }
        productFlavor2 {
            mapId = "{map_id}"
        }
    }
}
app/build.gradle.kts
attractionsIo {
    variants {
        maybeCreate("variant1").apply {
            setMapId("{map_id}")
        }
        maybeCreate("variant2").apply {
            setMapId("{map_id}")
        }
    }
    buildTypes {
        maybeCreate("buildType1").apply {
            setMapId("{map_id}")
        }
        maybeCreate("buildType2").apply {
            setMapId("{map_id}")
        }
    }
    productFlavors {
        maybeCreate("productFlavor1").apply {
            setMapId("{map_id}")
        }
        maybeCreate("productFlavor2").apply {
            setMapId("{map_id}")
        }
    }
}

An example can be found here: app/build.gradle

Set cache time

The maps are cached for a default period of 24 hours but this can be modified. For example, a build system could have this set to 0 so that the latest map is downloaded for every build.

app/build.gradle
attractionsIo {
    cacheMapsForHours = 24
}
app/build.gradle.kts
attractionsIo {
    cacheMapsForHours = 24
}

An example can be found here: app/build.gradle

 

MapLayr Implementation

Use the same GitHub token as created above #Create GitHub token

Add GitHub Package Registry to module Gradle

If your project uses the legacy per-module repositories {} block within the module's build.gradle file then add the GitHub package registry to the module level build.gradle as so:

app/build.gradle
repositories {
    maven {
        url = "https://maven.pkg.github.com/attractions-io/maplayr-android"
        credentials {
            username "GitHub username here"
            password "GitHub token with packages read access here"
        }
    }
}
app/build.gradle.kts
repositories {
    maven {
        url = uri("https://maven.pkg.github.com/attractions-io/maplayr-android")
        credentials {
            username "GitHub username here"
            password "GitHub token with packages read access here"
        }
    }
}

An example can be found here: app/build.gradle

If your project uses the centralised repository approach within settings.gradle using the dependencyResolutionManagement { repositories } block then add the GitHub package registry as so:

settings.gradle
dependencyResolutionManagement {
    repositories {
        maven {
            url = "https://maven.pkg.github.com/attractions-io/maplayr-android"
            credentials {
                username "GitHub username here"
                password "GitHub token with packages read access here"
            }
        }
    }
}
settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        maven {
            url = uri("https://maven.pkg.github.com/attractions-io/maplayr-android")
            credentials {
                username "GitHub username here"
                password "GitHub token with packages read access here"
            }
        }
    }
}

Add MapLayr implementation to Gradle module dependencies

app/build.gradle
dependencies {
    implementation "io.attractions:maplayr:0.0.93"
}
app/build.gradle.kts
dependencies {
    implementation("io.attractions:maplayr:0.0.93")
}

An example can be found here: app/build.gradle