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

Add the GitHub package registry to the top level build.gradle as so:

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"
            }
        }
    }
}

An example can be found here: build.gradle

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:

buildscript {
    repositories {
        maven {
            url = "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:

buildscript {
    dependencies {
        classpath 'io.attractions:maplayr-plugin:0.0.86'
    }
}

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:

plugins {
    id 'io.attractions.maplayr-plugin'
}

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

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:

attractionsIo {
    mapId = "{map_id}"
}

This map id can be retrieved in your code by using BuildConfig.MAPLAYR_MAP_0.

Bundle multiple maps

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

attractionsIo {
    mapIds = ["{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.

Bundle named map(s)

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

attractionsIo {
    maps = [
        "{my_first_map}": "{map_id_1}",
        "{my_second_map}": "{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.

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.

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}"
        }
    }
}

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.

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

Add the GitHub package registry to the module level build.gradle as so:

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"
        }
    }
}

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

Add MapLayr implementation to Gradle module dependencies

dependencies {
    implementation "io.attractions:maplayr:0.0.86"
}

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