Location sharing: don't hardcode API key

In an effort to make it easier for forks to (a) use their own
API keys (b) change map styles or maybe even providers, move
the MapTiler key out of the source code and pass it in via
env var or property.

Also refactor the utility classes slightly to keep all the URL
related functions together, to reduce the chance of collisions
when maintaining such forks.

Author: csmith

.github/workflows/build.yml

@@ -38,6 +38,8 @@ jobs:
         with:
           cache-read-only: ${{ github.ref != 'refs/heads/develop' }}
       - name: Assemble debug APK
+        env:
+          ELEMENT_ANDROID_MAPTILER_API_KEY: ${{ secrets.MAPTILER_KEY }}
         run: ./gradlew assembleDebug $CI_GRADLE_ARG_PROPERTIES
       - name: Upload debug APKs
         uses: actions/upload-artifact@v3

.github/workflows/nightly.yml

@@ -35,6 +35,7 @@ jobs:
         run: |
           ./gradlew assembleNightly appDistributionUploadNightly $CI_GRADLE_ARG_PROPERTIES
         env:
+          ELEMENT_ANDROID_MAPTILER_API_KEY: ${{ secrets.MAPTILER_KEY }}
           ELEMENT_ANDROID_NIGHTLY_KEYID: ${{ secrets.ELEMENT_ANDROID_NIGHTLY_KEYID }}
           ELEMENT_ANDROID_NIGHTLY_KEYPASSWORD: ${{ secrets.ELEMENT_ANDROID_NIGHTLY_KEYPASSWORD }}
           ELEMENT_ANDROID_NIGHTLY_STOREPASSWORD: ${{ secrets.ELEMENT_ANDROID_NIGHTLY_STOREPASSWORD }}

docs/maps.md

@@ -0,0 +1,42 @@
+# Use of maps
+
+<!--- TOC -->
+
+* [Overview](#overview)
+* [Local development with MapTiler](#local-development-with-maptiler)
+* [Making releasable builds with MapTiler](#making-releasable-builds-with-maptiler)
+* [Using other map sources or MapTiler styles](#using-other-map-sources-or-maptiler-styles)
+
+<!--- END -->
+
+## Overview
+
+Element Android uses [MapTiler](https://www.maptiler.com/) to provide map
+imagery where required. MapTiler requires an API key, which we bake in to
+the app at release time.
+
+## Local development with MapTiler
+
+If you're developing the application and want maps to render properly you can
+sign up for the [MapTiler free tier](https://www.maptiler.com/cloud/pricing/).
+
+Place your API key in `local.properties` with the key
+`services.maptiler.apikey`, e.g.:
+
+```properties
+services.maptiler.apikey=abCd3fGhijK1mN0pQr5t
+```
+
+## Making releasable builds with MapTiler
+
+To insert the MapTiler API key when building an APK, set the
+`ELEMENT_ANDROID_MAPTILER_API_KEY` environment variable in your build
+environment. 
+
+## Using other map sources or MapTiler styles
+
+If you wish to use an alternative map provider, or custom MapTiler styles,
+you can customise the functions in
+`features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/MapUrls.kt`. 
+We've kept this file small and self contained to minimise the chances of merge
+collisions in forks.

features/location/api/build.gradle.kts

@@ -14,14 +14,33 @@
  * limitations under the License.
  */
 
+import java.util.Properties
+
 plugins {
     id("io.element.android-compose-library")
     alias(libs.plugins.ksp)
     id("kotlin-parcelize")
 }
 
+fun readLocalProperty(name: String) = Properties().apply {
+    try {
+        load(rootProject.file("local.properties").reader())
+    } catch (ignored: java.io.IOException) {
+    }
+}[name]
+
 android {
     namespace = "io.element.android.features.location.api"
+
+    defaultConfig {
+        resValue(
+            type = "string",
+            name = "maptiler_api_key",
+            value = System.getenv("ELEMENT_ANDROID_MAPTILER_API_KEY")
+                ?: readLocalProperty("services.maptiler.apikey") as? String
+                ?: ""
+        )
+    }
 }
 
 dependencies {

features/location/api/src/main/kotlin/io/element/android/features/location/api/StaticMapView.kt

@@ -34,9 +34,8 @@ import androidx.compose.ui.unit.dp
 import coil.compose.AsyncImagePainter
 import coil.compose.rememberAsyncImagePainter
 import coil.request.ImageRequest
-import io.element.android.features.location.api.internal.AttributionPlacement
 import io.element.android.features.location.api.internal.StaticMapPlaceholder
-import io.element.android.features.location.api.internal.buildStaticMapsApiUrl
+import io.element.android.features.location.api.internal.staticMapUrl
 import io.element.android.libraries.designsystem.preview.DayNightPreviews
 import io.element.android.libraries.designsystem.preview.ElementPreview
 import io.element.android.libraries.designsystem.text.toDp
@@ -64,6 +63,7 @@ fun StaticMapView(
         modifier = modifier,
         contentAlignment = Alignment.Center
     ) {
+        val context = LocalContext.current
         var retryHash by remember { mutableStateOf(0) }
         val painter = rememberAsyncImagePainter(
             model = if (constraints.isZero) {
@@ -72,17 +72,16 @@ fun StaticMapView(
             } else {
                 ImageRequest.Builder(LocalContext.current)
                     .data(
-                        buildStaticMapsApiUrl(
+                        staticMapUrl(
+                            context = context,
                             lat = lat,
                             lon = lon,
-                            desiredZoom = zoom,
+                            zoom = zoom,
                             darkMode = darkMode,
-                            attributionPlacement = AttributionPlacement.BottomLeft,
                             // Size the map based on DP rather than pixels, as otherwise the features and attribution
                             // end up being illegibly tiny on high density displays.
-                            desiredWidth = constraints.maxWidth.toDp().value.toInt(),
-                            desiredHeight = constraints.maxHeight.toDp().value.toInt(),
-                            doubleScale = true,
+                            width = constraints.maxWidth.toDp().value.toInt(),
+                            height = constraints.maxHeight.toDp().value.toInt(),
                         )
                     )
                     .size(width = constraints.maxWidth, height = constraints.maxHeight)

features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/MapUrls.kt

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2023 New Vector Ltd
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.element.android.features.location.api.internal
+
+import android.content.Context
+import io.element.android.features.location.api.R
+
+/**
+ * Provides the URL to an image that contains a statically-generated map of the given location.
+ */
+fun staticMapUrl(
+    context: Context,
+    lat: Double,
+    lon: Double,
+    zoom: Double,
+    width: Int,
+    height: Int,
+    darkMode: Boolean,
+): String {
+    return "${baseUrl(darkMode)}/static/${lon},${lat},${zoom}/${width}x${height}@2x.webp?key=${context.apiKey}&attribution=bottomleft"
+}
+
+/**
+ * Provides the URL to a MapLibre style document, used for rendering dynamic maps.
+ */
+fun tileStyleUrl(
+    context: Context,
+    darkMode: Boolean,
+): String {
+    return "${baseUrl(darkMode)}/style.json?key=${context.apiKey}"
+}
+
+private fun baseUrl(darkMode: Boolean) =
+    "https://api.maptiler.com/maps/" +
+        if (darkMode)
+            "dea61faf-292b-4774-9660-58fcef89a7f3"
+        else
+            "9bc819c8-e627-474a-a348-ec144fe3d810"
+
+private val Context.apiKey: String
+    get() = getString(R.string.maptiler_api_key)