Flutter Native - Offline Mode

This guide explains how to enable and use offline mode so the map works without network access. Pack data (vector tiles, POIs, indoor data) must be available locally and provided via packDataPath in MapOptions. See Map Configuration for the option reference.

---

Overview

When offlineMode is true, the map loads data from a local pack data ZIP file instead of the network. You must:

1. Obtain pack data — either download it at runtime or bundle it with your app
2. Provide the file path — pass it to MapOptions via packDataPath
3. Optionally add raster tiles — if your pack data does not include them, use rasterZipFileName

The pack data ZIP contains map structure, POIs, indoor levels, and vector data for the selected map.

---

Option 1: Download pack data via PackDataManager (recommended)

Use PackDataManager.downloadPackData(mapID) to download pack data for a given map. This requires network access and valid mapID. The returned PackData object contains a filePath you can pass to packDataPath.

Basic download

import 'package:wemap_sdk_flutter/wemap_sdk_flutter.dart';

Future<void> loadMapOffline() async {
  const mapID = yourMapID;

  final packData = await PackDataManager.downloadPackData(mapID);

  // Store packData.filePath, packData.eTag, packData.version for reuse
  // and pass filePath to MapOptions when displaying the map
}

Using the path with the map

// After download, display the map
WemapMap(
  options: MapOptions(
    mapID: mapID,
    token: yourToken,
    environment: Environment.PROD,
    offlineMode: true,
    packDataPath: packData.filePath,
  ),
)

Checking for updates

Before re-downloading, you can check if a newer version of the pack data is available using the stored ETag:

final isAvailable = await PackDataManager.isNewPackDataAvailable(mapID, packData.eTag);

if (isAvailable) {
  final newPackData = await PackDataManager.downloadPackData(mapID);
  // Use newPackData.filePath for the map
}

PackData fields

Field	Type	Description
filePath	String	Full path to the downloaded ZIP file (use for packDataPath)
eTag	String	ETag for change detection (use with isNewPackDataAvailable)
version	String	Version identifier
fileName	String	Original file name

---

Option 2: Bundle pack data from assets

If you want the map to work fully offline without any download step, bundle the pack data ZIP in your app assets.

1. Add the asset

Place the pack data ZIP in your project (e.g. assets/packdata.zip) and declare it in pubspec.yaml:

flutter:
  assets:
    - assets/packdata.zip

2. Copy asset to a writable path

The SDK expects a file path on disk. Assets are stored in the app bundle and are read-only, so you must copy the asset to a temporary or documents directory first. Add path_provider to pubspec.yaml:

dependencies:
  path_provider: ^2.1.5

3. Helper to get the path

import 'dart:io';
import 'package:flutter/services.dart';
import 'package:path_provider/path_provider.dart';

Future<String> getAssetPackDataPath(String assetPath) async {
  final dir = await getTemporaryDirectory();
  final fileName = assetPath.split('/').last;
  final file = File('${dir.path}/$fileName');

  if (!await file.exists()) {
    final bytes = await rootBundle.load(assetPath);
    await file.writeAsBytes(bytes.buffer.asUint8List());
  }

  return file.path;
}

4. Use with the map

final packDataPath = await getAssetPackDataPath('assets/packdata.zip');

WemapMap(
  options: MapOptions(
    mapID: yourMapId,
    token: yourToken,
    environment: Environment.PROD,
    offlineMode: true,
    packDataPath: packDataPath,
  ),
)

Note: If you use getTemporaryDirectory(), the file may be cleared when the system reclaims cache space. For persistent storage, use getApplicationDocumentsDirectory() instead.

---

Optional: Separate raster tiles

If your pack data does not include raster tiles (satellite imagery, custom imagery) and you need them offline, you can provide a separate raster ZIP. This is also useful when you have multiple pack data files (e.g. one per language) and want to share a single raster tiles file to save storage.

Setup

1. Add the raster ZIP to your assets in pubspec.yaml:

flutter:
  assets:
    - assets/packdata.zip
    - assets/raster-tiles.zip

2. Specify rasterZipFileName in MapOptions. The value is the file name of the raster ZIP (the SDK looks for it under assets/):

MapOptions(
  mapID: yourMapId,
  token: yourToken,
  environment: Environment.PROD,
  offlineMode: true,
  packDataPath: packDataPath,
  rasterZipFileName: "raster-tiles.zip",
)

On Android and iOS, the raster ZIP is extracted and merged into the pack data directory when loading.

---

Troubleshooting

Issue	Solution
Map does not load in offline mode	Ensure packDataPath points to an existing ZIP file and offlineMode is true
FileNotFound / "Zip file not found"	Verify the path is valid on the device. Use path_provider for app storage; avoid hardcoded paths
Download fails	Check network connectivity and that mapID is a valid ID
Raster tiles not showing	Confirm rasterZipFileName matches the asset name and the raster ZIP is in pubspec.yaml