# Adding venue maps to the sample app

The sample app loads venue maps from two places at runtime:

1. The shipped reference venue at `TestApp/venue_map_AEGIRH/`.
2. Any `venue_map_<VENUE_ID>/` directory you drop into `TestApp/venues/`.

This document covers (2) — 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 directory
   named `venue_map_<VENUE_ID>/` (e.g. `venue_map_AEGIRTEST/`).
2. Copy the directory into the sample app's `TestApp/venues/` folder:

   ```sh
   cp -R venue_map_AEGIRTEST VMSDK-Demo-Swift/TestApp/venues/
   ```

3. Open `TestApp.xcworkspace` in Xcode and build the `TestApp` scheme.
   No project edits are required — `TestApp/venues/` is wired into the
   Xcode project as a folder reference, so Xcode picks up the contents
   on every build.
4. Launch the app. Tap **Built-in Venues** -> **Select Venue...** ->
   pick `<VENUE_ID>`.

## Expected directory layout

Each venue must be an unzipped directory tree (not a single archive)
with this layout:

```
venue_map_<VENUE_ID>/
  venue_map_<VENUE_ID>.xml           # VMD metadata (required entry point)
  venue_map_<VENUE_ID>.svg
  apple/
    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
  google/                            # same layout as apple/
```

`<VENUE_ID>` is the uppercase venue identifier. The directory name, the
`.xml`/`.svg` basenames, and the entry shown in the picker must all use
the same `<VENUE_ID>`.

The `apple/` subtree is required for the default Apple Maps demo path.
`google/` is only required if you build/run the Google Maps demo
controller.

## What gets committed

The `TestApp/venues/` directory is gitignored except for `.gitkeep`, so
your venue drops stay local and never land in source control unless you
explicitly stage them:

```gitignore
VMSDK-Demo-Swift/TestApp/venues/*
!VMSDK-Demo-Swift/TestApp/venues/.gitkeep
```

The release pipeline also strips `TestApp/venues/` from the partner zip,
so partner-shipped sample apps come with only `AEGIRH` bundled by
default; you must drop venues in yourself after extracting the zip.

## How discovery works

On launch, `VenueListController.discoverBuiltInVenues()` scans the
bundled `venues/` resource directory, strips the `venue_map_` prefix
from each `venue_map_*` subdirectory, and adds the resulting ID to the
picker. `AEGIRH` is always present (hardcoded reference venue).

Path resolution when a venue is tapped: the controller first looks for
`venue_map_<VENUE_ID>` at the bundle root (where `AEGIRH` lives), then
falls back to `venues/venue_map_<VENUE_ID>/`. Either location works.

## Required configuration

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

Copy `TestApp/LocalKeys.xcconfig.template` to `TestApp/LocalKeys.xcconfig`
and set:

```
MAPTILER_API_KEY=<your key>
```

`LocalKeys.xcconfig` is gitignored. Re-run `pod install` after creating it.

## Remote venues (HTTPS)

If you want to test loading venues from a hosted bucket instead of
bundling them, use the **Custom Venue (HTTPS)** entry in the picker.
Enter:

- **Base URL:** the directory containing the venue folder. The path
  must end with `/`. The app concatenates `<Base URL><VENUE_ID>/...` at
  load time.
- **Venue ID:** `<VENUE_ID>`.

The remote layout must mirror the bundled directory tree:
`<Base URL><VENUE_ID>/venue_map_<VENUE_ID>/venue_map_<VENUE_ID>.xml`
plus the `apple/` and (optionally) `google/` subtrees.

## Gotchas

- Don't add per-venue folder references in `TestApp.xcodeproj`. The
  single `venues/` folder reference covers every drop; an extra
  reference will fight the discovery logic.
- Large venues inflate app bundle size. Xcode's folder reference copies
  the entire tree verbatim into the .app — strip out provider subtrees
  you don't need (e.g. delete `google/` if you only target Apple Maps).
- If the picker doesn't show your venue, confirm the folder is under
  `TestApp/venues/` (not loose in `TestApp/`) and that the `<VENUE_ID>`
  matches the filename suffixes inside.
- The picker entry for `AEGIRH` is hardcoded and will appear even if
  the bundled `venue_map_AEGIRH/` directory is missing — selecting it
  in that case will fail to load.
