Setting up your Guided Trail System

Before you begin

Make sure you have everything on this list ready before you start. Gathering these up front will save you interrupting your flow halfway through.

What does "web hosting access" mean?

You need somewhere on the internet to put the app files so visitors can reach them via a URL. Most commonly this is:

• cPanel hosting — the most common NZ hosting (e.g. SiteTech, FreeParking, OpenHost, CrazyDomains). You log in to a control panel and use "File Manager" to upload files.
• FTP access — if your host doesn't have cPanel, you can use a free FTP program like FileZilla or Cyberduck to upload files.
• Website builder platforms (Wix, Squarespace, Shopify) — these don't work with this app. The Guided Trail System needs traditional file-based hosting. If you're not sure, ask your hosting provider "can I upload HTML and JS files to a folder?"

Unzip & understand the files

Find the ZIP file you downloaded from us (likely in your Downloads folder). It will be named something like guided-trail-4.1.0.zip.

Unzip it

• Windows: Right-click the ZIP → "Extract All..." → choose a folder.
• Mac: Double-click the ZIP file. A folder will appear next to it.

What's inside

Open the unzipped folder. You should see this file structure:

Prepare your map tiles

Your map is the visual background visitors see when they open the app. It needs to be split into a grid of smaller image files called tiles. The default is a 3×3 grid (9 tiles), but you can use any grid from 1×1 up to 12×12.

Option A: Use the Map Tile & Bounds Tool (recommended)

Pick a map area and get the four GPS bounds the Guided Trail System needs, or split any image into a grid of named tiles ready for the /tiles folder.

How to do this

1. Go to the tool: Map Tile & Bounds Tool.
2. Follow the instructions onscreen.
3. You can setup your Base Map 🖼 Tiles black Tiles out and obtain GSP bounds for a selected area.
4. You can also split existing images into Tiles.
5. The app will name the Tiles correctly and provide a .zip download.

✨ Way easy.

Option B: Split the map image yourself

If you have an image editor (Photoshop, GIMP, or even a free online tool), split your map into a grid of equal-sized tiles before uploading. This gives you more control and lets you check each tile looks right.

Add your logo

Your logo appears in two places: the top header of the public app, and the top of any PDF printouts you generate. It needs to be a PNG file, ideally with a transparent background.

Logo specifications

• Format: PNG (transparent background preferred)
• Dimensions: Around 400×100 px (4:1 aspect ratio works best — wide and short)
• File size: Under 100 KB
• Colour: The header background is dark green, so a light-coloured or white logo works best. If your logo is dark, you may want a "white" version for use here.

Replace the placeholder

1. In your unzipped folder, open the images/ folder.
2. You'll see a file called logo.png (this is a placeholder).
3. Delete it (or rename it to logo-old.png just in case).
4. Copy your logo into the folder and rename it to logo.png (must be exactly this name).

Edit config.js

This is the only code file you'll touch. config.js holds your branding, contact info, and a few settings. Open it in any text editor.

How to open it

• Windows: Right-click config.js → "Open with" → Notepad (or better: download the free Notepad++).
• Mac: Right-click config.js → "Open With" → TextEdit. Important: in TextEdit, go to Format menu and make sure "Make Plain Text" is selected before saving.

What to change

When you open config.js, you'll see a block of settings. Edit only the values in quotes — don't change the property names (the words before the colons) and don't remove any commas or quotes.

const APP_CONFIG = {
  // ── Brand / Identity ──
  businessName:    'My Trail Trust',         // ← your organisation name
  businessUrl:     'https://mytrail.co.nz',  // ← your main website
  appTitle:        'My Trail Guide',         // ← shows in browser tab
  appDescription:  'My Trail Guide',         // ← shows in search results
  logoPath:        'images/logo.png',        // ← usually leave as-is

  // ── Data ──
  dataFileName:    'guidedtraildata.json',   // ← leave as-is

  // ── GPS ──
  triggerRadius:   10,         // metres — how close before audio plays
  gpsIntervalMs:   5000,       // ms — leave as-is

  // ── Labels ──
  itemLabelSingular: 'Sculpture',  // ← e.g. 'Artwork', 'Stop', 'Point of Interest'
  itemLabelPlural:   'Sculptures', // ← plural form

  // ── Admin ──
  adminPassKey:    'trail_admin_password',   // ← leave as-is
  defaultAdminPass: 'enter',                 // ← CHANGE THIS (see below)

  // ... (rest stays as-is)
};

The two things you MUST change

  defaultAdminPass: 'enter',

  defaultAdminPass: 'MyTrail2026!',

Save and close

Once you've made those changes, save the file (File → Save) and close your text editor. You're done with config.js.

Upload to your hosting

Now you'll upload the entire trail/ folder to your web hosting so the world can reach it. There are two common ways to do this — pick the one that matches your hosting.

Option A: cPanel File Manager (most common)

Option B: FTP (if you don't have cPanel)

Verify the upload worked

Once everything's uploaded, open a browser and go to:

https://yoursite.co.nz/trail/

You should see the app load — probably with a blank map (because you haven't set your GPS bounds yet). If you see a 404 error or a directory listing, something went wrong with the upload.

Set your map GPS bounds

This is the most important step. The app needs to know exactly where on Earth your map corresponds to, so it can place pins accurately and track visitors via GPS. If you haven't used the provided Map Tile & Bounds Tool you will need to get these details.

What are "map bounds"?

Your map image represents a real physical area. The "bounds" are the GPS coordinates of the four edges of that area:

• North = latitude of the TOP edge of your map (the highest latitude, furthest north)
• South = latitude of the BOTTOM edge of your map (the lowest latitude, furthest south)
• East = longitude of the RIGHT edge of your map (the highest longitude, furthest east)
• West = longitude of the LEFT edge of your map (the lowest longitude, furthest west)

How to find your GPS coordinates

North (top lat):    -36.95780   ← from top-left, first number
South (bottom lat): -36.96320   ← from bottom-right, first number
East (right lng):   175.06120   ← from bottom-right, second number
West (left lng):    175.05340   ← from top-left, second number

Enter your bounds in the admin portal

Now you'll enter those four numbers into the app.

North (top lat):    -36.9578
South (bottom lat): -36.9632
East (right lng):    175.0612
West (left lng):     175.0534

Fine-tuning the bounds

If your map looks slightly off — the tiles are visible but pins you place later seem to be in the wrong spot — you can fine-tune the bounds. Common adjustments:

• If the map is shifted north: decrease the North value and increase the South value slightly (e.g. by 0.0001 — that's about 11 metres).
• If the map is shifted east: decrease the East value and increase the West value slightly.
• If the map looks stretched/squashed: the aspect ratio of your tile images doesn't match the aspect ratio of your bounds. You may need to re-split your map tiles with a different aspect ratio, or adjust your bounds to match the image.

The GPS offset feature (if your pins are systematically off)

If you've placed pins using the admin map and they look right on screen, but visitors using GPS find their blue dot is consistently offset from where they actually are, that's a GPS offset issue. You can fix this in Settings → GPS Fine-Tuning:

1. Open Settings (⚙ button in the admin header).
2. Find the "GPS Fine-Tuning" section.
3. Enter small metre values for Latitude and Longitude offsets. Positive = north/east, negative = south/west.
4. Click Save & Download JSON, then upload the new guidedtraildata.json to your data/ folder.

This is rare — only use it if multiple visitors report the same offset.

Add your marked items (pins)

Now that your map is in place, you can start adding your trail stops. Each pin represents one marked item — a sculpture, a historical point, an information sign, etc.

Make sure you're in "Marked Item" mode

At the top of the admin map, the first button in the toolbar should be highlighted: Marked Item. If it's not, click it.

Add a pin by clicking the map

1. Click on the map at the location of your first trail stop.
2. The editor panel opens on the right, pre-filled with the GPS coordinates of where you clicked.
3. Fill in the fields:
   • Pin # — the number shown on the pin (1, 2, 3...). The app auto-suggests the next number.
   • Item Title — e.g. "River Song"
   • Artist Name — e.g. "Jane Smith" (optional)
   • Year / Date — e.g. "2023" (optional)
   • Description — a paragraph about this stop. What visitors will read when they tap the pin.
   • More Information URL — a link to a website with more info (optional)
   • Latitude / Longitude — already filled in. You can fine-tune if needed.
   • Pin Layer — leave as "Main" for now (we cover layers below).
   • Image Path — relative to your /trail folder, e.g. images/river-song.png. We cover this in Step 11.
   • Audio Path — relative to your /trail folder, e.g. audio/river-song.mp3. Optional. We cover this in Step 11.
4. Click Save. The pin appears on the map.
5. Repeat for each trail stop.

Moving a pin

If a pin isn't quite in the right spot, you can drag it. Click and hold the pin, drag it to the correct location, and release. The new coordinates are saved automatically.

Editing a pin later

Click on any existing pin to re-open its editor. Make your changes and click Save.

About pin layers (optional)

If your trail has multiple sections (e.g. "Main Trail" and "Seasonal Extension"), you can use layers to organise pins. Visitors can toggle layers on and off.

1. Open Settings (⚙ button) → scroll to Pin Layers.
2. Type a name for your new layer (e.g. "Seasonal") and click + Add Layer.
3. When adding a pin, you can now select which layer it belongs to in the "Pin Layer" dropdown.

If you only have one trail, ignore this — the default "Main" layer is fine.

Add utility markers (WC / bins)

Besides your main trail stops, you can mark toilets (WC) and rubbish bins on the map. These show as small icons and help visitors plan their visit.

Add a toilet marker

1. Click the 🚻 WC button in the toolbar.
2. Click on the map where the toilet is.
3. A WC marker appears. Done — no editor opens for these.

Add a rubbish bin marker

1. Click the 🗑 Bin button in the toolbar.
2. Click on the map where the bin is.
3. A bin marker appears.

Moving or deleting utility markers

• Move: Click and drag the marker to a new spot.
• Delete: Find the marker in the "WC & Bin Markers" list in the right panel, and click the red ✕ next to it.

Utility markers are optional. Only add them if they're genuinely useful for your visitors — don't feel you have to map every bin on the trail.

Draw trail paths

Trail paths are the dashed lines that show visitors the walking route between pins. They're optional but recommended — they make the tour mode much more useful.

Draw a path segment

1. Click the 🛤 Trail Path button in the toolbar.
2. A small control bar appears below the toolbar with "Finish Segment", "Cancel", and "Clear All Paths" buttons.
3. Click on the map at the start of your path (usually near your first pin).
4. Click again at the next waypoint along the trail. A dashed red line appears between the two clicks.
5. Keep clicking to add more waypoints — follow the actual walking route.
6. When you've reached the end of this segment, click ✓ Finish Segment.
7. The path turns brown, indicating it's saved.

Multiple segments

If your trail branches or has multiple sections, draw each as a separate segment. Just start a new path after finishing the previous one.

Deleting paths

• Delete one segment: Find it in the "Trail Paths" list in the right panel and click the red ✕.
• Delete all paths: Click 🗑 Clear All Paths in the path controls. (This asks for confirmation.)

Add images & audio

Each marked item can have a photo and an audio guide. When visitors tap a pin (or walk within 10 metres of it), the photo and audio play automatically.

Image specifications

• Format: JPG or PNG
• Dimensions: Square (1:1) works best — e.g. 800×800 px
• File size: Under 200 KB per image
• Filename: Use lowercase, no spaces. E.g. river-song.jpg not River Song.JPG

Audio specifications

• Format: MP3 (best browser compatibility) or OGG
• Bitrate: 96–128 kbps is plenty for spoken audio
• Length: 30 seconds to 3 minutes per stop is typical
• File size: Under 5 MB per file
• Filename: Use lowercase, no spaces. E.g. river-song.mp3

Upload your media

1. Using File Manager (or FTP), upload your image files to the images/ folder inside trail/.
2. Upload your audio files to the audio/ folder inside trail/.

Link media to your pins

1. Back in the admin portal, click on a pin to open its editor.
2. In the Image Path field, enter the path relative to your /trail folder. For a file at trail/images/river-song.jpg, you enter: images/river-song.jpg
3. In the Audio Path field, enter: audio/river-song.mp3
4. Click Save.
5. Repeat for each pin.

Test on your phone

Before going live, test the app on your phone.

Test checklist

1. Open your phone's browser (Safari on iPhone, Chrome on Android).
2. Go to https://yoursite.co.nz/trail/
3. The map should load with your tiles and pins visible.
4. Tap a pin — the info panel should slide up from the bottom.
5. If the pin has audio, tap the audio button — it should play.
6. Tap ▶ Start Tour — the tour bar should appear at the top.
7. Tap ⊕ (Locate) — your phone should ask for location permission. Grant it. Your blue dot should appear on the map.
8. If you have a compass: tap 🧭 — the map should rotate to match your facing direction.
9. Tap 🗂 Layers — if you have multiple layers, you should see a toggle panel.
10. On a desktop browser, also test ?mode=admin and make sure you can log in.

If something doesn't work

See the Troubleshooting section below for common issues and fixes.

Publish & go live

Everything you've done in the admin portal so far has been saved to your browser's local storage — only you can see it. To make it visible to visitors, you need to publish.

The Publish step

1. In the admin header, click 🚀 Publish.
2. A ZIP file downloads to your computer. It contains:
   • data/guidedtraildata.json — all your trail data (pins, paths, bounds, settings)
   • tiles/ — any tile images you uploaded via the admin (if you did Option A in Step 3)
   • PUBLISH_README.txt — quick instructions
3. Open the ZIP and extract the data/guidedtraildata.json file.
4. Using File Manager (or FTP), upload this file to your trail/data/ folder, replacing the existing one.
5. If you have tile images in the ZIP's tiles/ folder, upload those to trail/tiles/ too (replace existing).

You're live!

Congratulations — your trail is now live at https://yoursite.co.nz/trail/. Share this URL on your signage, website, social media, and printed materials.

Optional: Add to Home Screen

Visitors on iPhone or Android can "Add to Home Screen" from their browser menu. The app will appear as an icon on their home screen, opening full-screen like a native app. No setup required from you — this works automatically.

Going forward

To make updates later:

1. Open https://yoursite.co.nz/trail/?mode=admin
2. Log in with your admin password
3. Make your changes (add a pin, edit a description, etc.)
4. Click 🚀 Publish and re-upload the JSON file

That's it. Your trail is live and maintainable.

Troubleshooting

Common issues and their fixes. If your problem isn't here, see Getting help below.

The page won't load (404 error)

• Check that index.html is uploaded to your trail/ folder.
• Check the URL — make sure it's yoursite.co.nz/trail/ with the trailing slash.
• Check that the trail folder is inside public_html (or your host's equivalent).

The page loads but looks broken (no styling)

• style.css didn't upload. Re-upload it to the trail/ folder.

The map area is grey / blank

• You haven't set your map bounds yet. See Step 6.
• Your tile images aren't in the tiles/ folder. Check via File Manager.
• Your tile images are named wrong. For 3×3: 1a.png through 1i.png (lowercase). For larger grids: R0C0.png etc.

The admin portal won't open

• Make sure the URL has ?mode=admin at the end: yoursite.co.nz/trail/?mode=admin
• Clear your browser cache and try again.
• If you forgot your password, edit defaultAdminPass in config.js and re-upload it.

Pins I placed are in the wrong spot

• Your map bounds are slightly off. Re-measure the four corners in Google Maps and re-enter them.
• You can also drag pins to fine-tune their position.

GPS blue dot is in the wrong place

• This is usually a device-level issue, not an app issue. Try standing next to a known pin and tapping it in the app — the Locate feature will re-align your blue dot.
• If the offset is consistent across all devices, set a GPS Offset in admin → Settings → GPS Fine-Tuning.

Audio won't autoplay

• This is browser policy — mobile browsers block audio from playing until the user has interacted with the page. The app handles this by "arming" audio on the first tap. Tap anywhere on the map first, then walk to a pin.
• If audio still won't play, check that the audio file path is correct (case-sensitive!) and that the file is in the audio/ folder.

Images don't show on pins

• Check the image path in the pin editor — it must be relative to /trail, e.g. images/my-photo.jpg.
• Check the file is uploaded and the filename matches exactly (case-sensitive).

Compass mode doesn't work on iPhone

• iOS 13+ requires permission. Tap the 🧭 button once and grant permission when prompted.
• If you denied permission earlier, go to iPhone Settings → Safari → Motion & Orientation Access and turn it on.

Changes I made in admin aren't visible to visitors

• You forgot to publish! Click 🚀 Publish in the admin header and re-upload the guidedtraildata.json file.

Getting help

If you get stuck, we're here to help. Tier 1 includes email support for setup questions.

Before you contact us

• Check the Troubleshooting section above — most common issues are covered there.
• Check the in-app README.md file (in your trail/ folder) for technical reference.
• Try a hard refresh in your browser (Ctrl+Shift+R or Cmd+Shift+R) — sometimes old cached files cause issues.

When you contact us, please include

• Your trail URL (e.g. https://mytrail.co.nz/trail/)
• The step number where you got stuck (e.g. "I'm on Step 6 — setting map bounds")
• A screenshot of what you're seeing
• Any error messages (from the browser console — press F12 to open it)

Contact

📧 Email: info@digitaleuan.com

🌐 Website: digitaleuan.com

⏱ Response time: Within 1 NZ business day (usually faster)