# Adding venue maps to the sample app

Starting in vmsdk-android 2.1.12 the demo loads venue maps from
bundled `venue_map_<VENUE_ID>.zip` archives placed in
`vmms/app/src/main/assets/`. On first launch the zip is extracted to
app storage and reused on subsequent runs.

This document covers how to add your own venue maps to the sample app
for evaluation.

## Quick start

1. Obtain your venue deliverable from Aegir. It will be a single file
   named `venue_map_<VENUE_ID>.zip` (e.g. `venue_map_AEGIRTEST.zip`).
2. Copy it into the sample app's assets directory:

   ```sh
   cp venue_map_AEGIRTEST.zip vmms/app/src/main/assets/
   ```

3. Build the app:

   ```sh
   ./gradlew :app:assembleDebug
   ```

4. Launch on an emulator or device. The new venue appears in the venue
   picker — its ID is the zip basename minus the `venue_map_` prefix
   and the `.zip` suffix (e.g. `venue_map_AEGIRTEST.zip` -> `AEGIRTEST`).

No `build.gradle`, manifest, or registry edits are required. Discovery
scans the assets root at runtime.

## Expected zip layout

The zip must use a flat layout at its root (no wrapping
`venue_map_<VENUE_ID>/` directory inside):

```
venue_map_<VENUE_ID>.zip
  venue_map_<VENUE_ID>.xml
  venue_map_<VENUE_ID>.svg
  google/
    geojson.zip
    venue_map_<VENUE_ID>.geojson
    venue_map_<VENUE_ID>_labels.geojson
    venue_map_<VENUE_ID>_amenities.geojson
    venue_map_<VENUE_ID>_wayfinding.geojson
    vector-tiles/<layer>/*.mvt
    vector-common/<layer>/*.mvt
```

The `google/` provider subfolder is required for the demo's default
load path (`MapProvider.GOOGLE`). The `<VENUE_ID>` token must match
across the zip filename and the inner file basenames.

## What gets committed

Venue zips are gitignored repo-wide except for the shipped sample:

```gitignore
vmms/app/src/main/assets/venue_map_*/
!vmms/app/src/main/assets/venue_map_AEGIRH/
vmms/app/src/main/assets/venue_map_*.zip
!vmms/app/src/main/assets/venue_map_AEGIRTEST.zip
```

Your partner zips stay local unless you override the rule. The shipped
`venue_map_AEGIRTEST.zip` is tracked via Git LFS — run `git lfs pull`
after a fresh clone if you only see a small text pointer stub.

## Extraction model

On first load, `VenueAssets.ensureExtracted(...)` unzips the asset to
`{filesDir}/venues/venue_map_<VENUE_ID>/` and writes a `.extracted`
marker. Subsequent loads short-circuit to the cached directory. The
extracted base path is threaded into `VMMapViewLoadConfig` as a
`file://` URI, which `WebMapInterface.kt` rewrites to
`https://appassets.androidplatform.net/abs/...` so the inner WebView
can fetch tiles under its https origin (raw `file://` would hit CORS
isolation).

Implication: don't try to ship venues as loose APK assets. Android
caps APK zip entries at 65,535 and a venue's vector tile tree blows
past that easily. Bundled-zip + extract-to-cache is the supported path.

## Required configuration

The basemap requires a MapTiler API key. Venue tiles are local and have
no key dependency, but the basemap renders blank without a key.

Copy `vmms/local.properties.template` to `vmms/local.properties` and set:

```properties
MAPTILER_API_KEY=<your key>
GOOGLE_MAPS_API_KEY=<optional, only needed for the Google Maps demo path>
```

`local.properties` is gitignored. CI/CD environments can set the same
keys as environment variables instead.

## Gotchas

- Zip must be flat-rooted. A wrapping `venue_map_<VENUE_ID>/` directory
  inside the zip will fail to load.
- `<VENUE_ID>` must match exactly across the zip filename and the
  internal `venue_map_<VENUE_ID>.xml` basename.
- If the picker still lists `AEGIRH` after you drop a different venue,
  that's expected — `AEGIRH` is hardcoded into the venue list as a
  legacy default and will show even if no `venue_map_AEGIRH.*` asset
  exists. Selecting it without the asset will fail to load.
- After replacing a venue zip with a new build, clear the app's storage
  or uninstall — the `.extracted` marker won't auto-invalidate when the
  bundled zip changes.
- Partners do NOT need Git LFS for their own zips (gitignored). LFS is
  only required to pull the committed `venue_map_AEGIRTEST.zip` sample.
- The legacy loose-directory model (`venue_map_<VENUE_ID>/` directly
  under assets) still loads as a fallback, but new partners should use
  zips exclusively to stay under the APK zip-entry limit.
