Serve BeNomad vector basemaps to a browser by reading one authenticated PMTiles archive over HTTP, either through the BeMap SDK or through raw MapLibre + pmtiles.js.
MapLibre-only. PMTiles needs the vector-tile pipeline that Leaflet and OpenLayers don't have: use bemap.MapLibreMap. pmtiles.js must be loaded on the page whenever ctx.tilesHost is set, otherwise the pmtiles:// protocol is never registered and the map stays empty. For native / fleet clients that can't do Range reads, use the ZXY delivery mode instead.
## Try it
A BeNomad Tiles basemap over Paris. Once the Context has a tilesHost, login, JWT renewal, request signing, style resolution and tile caching are all handled by the SDK: this is the whole integration.
## At a glance
One archive per map: pmtiles://https://<tilesHost>/<map>, read by byte ranges, no tile pyramid to deploy.
Two read modes: cacheable 200-slices (?r=A-B, the default) or classic HTTP Range (206).
The 200-slice default lands in the browser's own HTTP cache, so no Service Worker is required.
Path A: bemap.Context + bemap.MapLibreMap: auth, JWT refresh and caching are automatic.
Path B: raw MapLibre + pmtiles.js: you own login, the TILES_SOURCE swap and the ~55 min re-login.
Always address the map by the default alias, never a dated filename.
## Usage
### Script load order (required)
The order matters: `bemap-js-api.js` registers the `pmtiles://` protocol at construction time and needs both globals already present.
```html
```
### Path A: the SDK way (recommended)
Set `tilesHost` on the Context. That single field promotes the MapLibre background to BeNomad Tiles and switches on `bemap.TilesAuth` (login, JWT, `transformRequest` signing, silent renewal) and the tile cache.
```js
var ctx = new bemap.Context({
host: 'bemap-beta.benomad.com', // BeMap host - services auth
secure: true,
login: 'YOUR_LOGIN', // demo / evaluation only
password: 'YOUR_PASSWORD', // production → token provider
tilesHost: 'mptiles-api-beta.benomad.net' // tiles backend
});
var map = new bemap.MapLibreMap(ctx, 'map');
map.move(2.35, 48.85, 12); // lon, lat, zoom - lon FIRST
// Tile- and style-load failures are logged to the browser console. If you need to
// react in code, MapLibre's own error event is the available hook - note the
// callback receives a bemap.MapEvent, so the native error lives on evt.native.
map.on('error', function (evt) {
var err = evt && evt.native && evt.native.error;
console.error('maplibre tiles error:', err && (err.message || err));
});
```
Never ship a login/password to a production browser: swap them for a backend token provider. The two hosts move together: swap `host` and `tilesHost` in the same edit: beta uses `mptiles-api-beta.benomad.net`, preprod `mptiles-api-preprod.benomad.net`, production `mptiles-api.benomad.net`.
### Path B: raw MapLibre + pmtiles.js (no SDK)
Only if you're already committed to raw MapLibre. You take over everything the SDK does for you: the protocol registration, the login call, the style placeholder swap, and the token lifetime.
```js
var TILES = 'https://mptiles-api-beta.benomad.net';
var LOGIN = 'YOUR_LOGIN', PASS = 'YOUR_PASSWORD'; // demo / evaluation only
function b64(s) { return btoa(unescape(encodeURIComponent(s))); }
async function login() {
var r = await fetch(TILES + '/api/login', {
method: 'POST',
headers: { 'Authorization': 'Basic ' + b64(LOGIN + ':' + PASS) }
});
if (!r.ok) throw new Error('login HTTP ' + r.status);
return (await r.json()).token;
}
async function resolveStyle(token) {
var raw = await (await fetch(TILES + '/api/default-style?token=' + token)).json();
var srcPh = (raw.metadata && raw.metadata.source_placeholder) || 'TILES_SOURCE';
raw.sources = raw.sources || {};
raw.sources['tiles'] = Object.assign({}, raw.sources[srcPh], {
type: 'vector',
url: 'pmtiles://' + TILES + '/default.pmtiles?token=' + token,
maxzoom: 14
});
if (srcPh !== 'tiles') delete raw.sources[srcPh];
(raw.layers || []).forEach(function (l) { if (l.source === srcPh) l.source = 'tiles'; });
return raw;
}
(async function () {
var token = await login();
maplibregl.addProtocol('pmtiles', new pmtiles.Protocol().tile);
var map = new maplibregl.Map({
container: 'map', style: await resolveStyle(token),
center: [2.35, 48.85], zoom: 12
});
// The token lives ~1 h - re-login and re-apply the style before it lapses.
setInterval(async function () {
try { var t = await login(); map.setStyle(await resolveStyle(t)); }
catch (e) { console.warn('refresh failed', e); }
}, 55 * 60 * 1000);
})();
```
This snippet authenticates with `?token=` on the query string, the only method that composes with `pmtiles.js` Range requests without extra plumbing. `X-Session-Token` is more secure but needs a fetch interceptor, which is exactly what Path A gives you.
## Reference
### The two read modes
| Mode | Request | Success | Cacheable |
| --- | --- | --- | --- |
| **200-slice** (default) | `GET /default?r=A-B` | **200** | Yes: `Cache-Control: public, max-age=2592000, immutable` + `ETag` |
| **Range** | `GET /default.pmtiles` + `Range: bytes=A-B` | **206** | No: browsers don't reliably cache partials |
Both return identical bytes. `tilesSliceMode: '200'` is the **default** because a plain 200 with `immutable` is stored by the browser's native HTTP cache: repeat tiles and repeat visits cost nothing and **no Service Worker is needed**. On the 206 path the Service Worker is the only client-side cache, so the SDK turns it back on automatically when you select `'range'` (`'206'` is accepted as a synonym).
### How the archive URL is built
```text
pmtiles://https:///