URL Transformer

To store and retrieve tiles, FMTC uses a tile's 'storage-suitable UID'. Before a tile is created/updated/read from the cache, the tile real URL may first be transformed. A storage-suitable UID must refer to the same tile from the same server every time (unless the server changes and serves different tiles from the same path).

A storage-suitable UID may be tile's own real URL, because the URL is guaranteed to refer only to that tile from that server. However, some parts of the tile URL should not be stored. For example, an API key transmitted as part of the query parameters should not be stored. This is because, if the API key changes, the cached tile will still use the old UID containing the old API key, and thus the tile will never be retrieved from storage, even if the image is the same: the UID does not necessarily refer to the same tile (it is reliant on the API key).

FMTCTileProvider.urlTransformer (& the urlTransformer elsewhere) takes the tile's real URL as input, and should output the storage-suitable UID. By default, it uses the identity function and returns the input - this is not always suitable as discussed above.

The callback will be passed to a different isolate: therefore, avoid using any external state that may not be properly captured or cannot be copied to an isolate spawned with Isolate.spawn (see SendPort.send).

FMTCTileProvider.urlTransformerOmitKeyValues utility

This predefined utility method may be used as a urlTransformer. It removes key-value pairs from a string, given only the keys (using regex internally).

By default, it targets the query parameters (the part after the '?' character) of a URL (link is set to =, delimiter is set to &).

For example, the Mapbox URL uses the key 'access_token' (see above for why the associated API key should be removed from the storage-suitable UID):

FMTCTileProvider(
    // ...
    urlTransformer: (url) => FMTCTileProvider.urlTransformerOmitKeyValues(
        url: url,
        keys: ['access_token'],
    ),
);