[Story] Customise maps provider

[Johennes]

• As a maintainer of a fork
• I want to be able to use my own provider for
  • the map tile server
  • the static map images API
• so that I can pick the option that works for my budget and privacy concerns

Size estimate

M

Dependencies

• [Prep] Set up SDK & reusable map view component #1684

Acceptance criteria

• The app does not value the tile server setting from .well-known because this doesn't cover static maps and will likely require a holistic redesign later
• Setting the API key or replacing the map provider URLs in forks is easy enough (e.g. dedicated file or interface)
• There is documentation in the repositories that explains how to replace the API key and URLs in forks
• The API keys used for Element's apps must not be put in the source code but rather they must be baked into the .apk/.ipa at build time using a GitHub Actions secret
  • For local builds (during development) a dev-only API key must be used in place of the platform-specific ones

Other

• It looks like we are already using a "provider" mechanism for allowing different push notification providers. In the android code is called "pushproviders" perhaps we could create a similar architecture for maps (e.g. a map providers interface which will have multiple implementations: maptiler... and perhaps others)

Out of scope

• Nothing

Subtasks

### Android
- [ ] https://github.com/vector-im/element-x-android/pull/886

### iOS
- [ ] https://github.com/vector-im/element-x-ios/pull/1313
- [ ] https://github.com/vector-im/element-x-ios/pull/1364

### Other

[alfogrillo]

@Johennes @julioromano should we do anything in this epic for this?
I fell like the code on iOS is already modular enough to enable a map provider switch very easily.
In other words boundaries between MapTiler and EX are very clear ATM.

[Johennes]

@alfogrillo what you say sounds like customizing the map provider by changing the app source code? I think ideally, there'd be a way to control the map provider via the home server's .well-known. That would allow users that are unable or unwilling to build and distribute the app themselves to opt out from our default map provider. MSC3488 does support this but only for the tile server URL, not for the static maps API.

[alfogrillo]

@alfogrillo what you say sounds like customizing the map provider by changing the app source code

Yep, we are quite ready for that.

I mean I think ideally, there'd be a way to control the map provider via the home server's .well-known

I'm not sure how we can make this generic across all the map providers.
Afaik other providers may use different endpoints for static/tiled maps for example.
And even if the format is the same, work needs be done on the source code to switch to the wanted provider sdk.

Maybe we may change the MSC3488 to introduce map provider specific information?
Would that be helpful?

Example (.well-known)

{
    "m.tile_server": { 
        "map_tiler": {
            "map_light_style_url": "https://www.example.com/style_light.json",
            "map_dark_style_url": "https://www.example.com/style_dark.json",
            "static_map_light_style_url": "https://www.example.com/static/style_light.json",
            "static_map_dark_style_url": "https://www.example.com/staic/style_dark.json"
        },
        "google_maps": {
            "some_url": "https://www.example.com/style.json"
        }
    },
    
    "m.homeserver": {
        "base_url": "https://matrix-client.matrix.org"
    },
    "m.identity_server": {
        "base_url": "https://vector.im"
    }
} 

[Johennes]

Maybe we may change the matrix-org/matrix-spec-proposals#3488 to introduce map provider specific information?

Yes, we'd likely need to change this in the MSC, too. It currently only includes the tile server configuration via .well-known.

"m.tile_server": { 
    "map_style_url": "https://www.example.com/style.json"
}

Your idea of having different objects for different map providers in .well-known sounds interesting. I suppose there would also have to be something in there that instructs the app which provider to choose if there are several?

I think a general problem there is that e.g. MapTiler and Mapbox use different formats for the static maps endpoints. MapTiler uses

https://api.maptiler.com/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format}

while Mapbox uses

https://api.mapbox.com/styles/v1/{username}/{style_id}/static/{overlay}/{lon},{lat},{zoom},{bearing},{pitch}|{bbox}|{auto}/{width}x{height}{@2x}

So I think in addition to the URL to request we'd also need to know where to insert the various parameters.

One slightly wild idea @julioromano and I had discussed a while ago was to add a URL template for the static maps endpoint in .well-known. Then to use your custom MapTiler account, you would specify something like

"template": "https://api.maptiler.com/maps/.../static/${lon},${lat},${zoom}/${width}x${height}${2x}.png"

whereas to use your Mapbox account, you could specify something like

"template": "https://api.mapbox.com/styles/v1/.../.../static/.../${lon},${lat},${zoom},auto/${width}x${height}${2x}"

The app could then replace all the various parameters (e.g. ${lon} with the actual longitude).

This isn't quite perfect though. It may not work for other static map providers and it definitely won't work when we add the geocoding API later because those return JSON that needs to be parsed differently for each provider. So that would probably only be a stopgap solution at best.

The MSC also doesn't currently support different tile server URLs for light and dark mode which is a similar problem and might require changes to the existing m.tile_server field.

[Johennes]

I've updated the description above with what we aligned on in the weekly today.