Online, Offline, Preload and Caching ​

Four words come up in almost every mobile integration conversation, and they are routinely used as if they were four names for the same feature. They are not. This page defines each one, shows how they combine, and states what you get and what you give up in each case.

Everything here applies to the ExpoFP mobile SDK v5 on iOS, Android and React Native. The API names differ per platform; the model is identical.

The short version ​

The single sentence that resolves most of the confusion:

Online / offline answers where the plan comes from. Preload answers when it was loaded. They are independent choices. Caching is not a choice at all — it is something that happens to you, and you must never design against it.

Two independent axes ​

Because the source and the timing are independent, there are four real combinations, and all four are supported:

Online ​

The default. You give the SDK an expo key, and it loads https://<expoKey>.expofp.com, appending any plan parameters you set as query items.

<ExpofpView expoKey="demo" style={{ flex: 1 }} />

val presenter = ExpoFpPlan.createPlanPresenter(
    planLink = ExpoFpLinkType.ExpoKey("demo")
)

let presenter = ExpoFpPlan.createPlanPresenter(with: .expoKey("demo"))

Use it when connectivity is reliable, or when being current matters more than being resilient — a pre-event browsing screen, a sales portal, a web-like directory.

What you get: whatever the organizer published a moment ago. No storage to manage, no version to track, no cleanup code.

What you give up: with no network the plan does not load at all — the status callback reports an error and the view shows the WebView's failure page. A bad venue Wi-Fi network is the normal case at an event, not the exceptional one.

Offline ​

An offline plan is a versioned ZIP archive of the whole plan — its HTML, its assets and its data — that you fetch ahead of time and that the SDK then serves from local files. The plan's own JavaScript cannot tell the difference: it sees the same absolute paths it would see online.

Archives are named <expoKey>_<version>.zip, and version is the identity of the snapshot. demo_18 and demo_23 are two different, independently stored plans.

Downloading one ​

const info = await ExpofpViewModule.downloadPlan("demo");
// then, on the view:
// <ExpofpView downloadedExpoKey="demo" style={{ flex: 1 }} />

val result = ExpoFpPlan.downloader.downloadPlan("demo")
val downloadedPlanInfo = result.getOrNull()

val presenter = ExpoFpPlan.createPlanPresenter(
    planLink = ExpoFpLinkType.DownloadedPlanInfo(downloadedPlanInfo)
)

let result = await ExpoFpPlan.downloader.downloadPlan(withExpoKey: "demo")
let downloadedPlanInfo = try result.get()

let presenter = ExpoFpPlan.createPlanPresenter(
    with: .downloadedPlanInfo(downloadedPlanInfo)
)

Under the hood, downloadPlan calls the public Offline Data API: it asks GET /api/v2/expo-offline/{expoKey}/get-or-create/latest for the current state, waits for a build if one is needed, and then downloads the archive named in fileUrl. If the device already holds that exact expoKey + version, nothing is re-downloaded.

Shipping an archive inside your app ​

You can also bundle an archive in the app and unpack it at first run, so the very first launch works offline with no download at all. The file must keep the <expoKey>_<version>.zip name — that is how the SDK identifies it.

// android/app/src/main/assets/demo_18.zip  ·  iOS: added to the app bundle
await ExpofpViewModule.unzipPlan("demo_18");

val result = ExpoFpPlan.downloader.downloadPlanFromZip(zipFile.absolutePath)

let path = Bundle.main.path(forResource: "demo_18", ofType: "zip")!
let result = await ExpoFpPlan.downloader.downloadPlan(withZipFilePath: path)

Where archives live, and why that matters ​

Archives are unpacked into your app's cache directory — Library/Caches/expoFpPlan/ on iOS (excluded from iCloud backup), cacheDir/expoFpPlan/archives/ on Android.

That is a deliberate choice: it keeps plans out of the user's backup and lets the system reclaim the space instead of the app being killed for using too much of it. The consequence is the part integrators miss:

The number of downloaded plans is not limited by the SDK. Removing them is your responsibility:

const plans = await ExpofpViewModule.getDownloadedPlansInfo("demo");
ExpofpViewModule.removeOldVersionsOfDownloadedPlans("demo");

val plans = ExpoFpPlan.downloader.getDownloadedPlansInfo("demo")
ExpoFpPlan.downloader.removeOldVersionsOfDownloadedPlans("demo")

let plans = await ExpoFpPlan.downloader.getDownloadedPlansInfo(withExpoKey: "demo")
await ExpoFpPlan.downloader.removeOldVersionsOfDownloadedPlans(withExpoKey: "demo")

Keeping a downloaded plan fresh ​

An archive is a snapshot. Booths reserved, exhibitors edited or sessions added after the build are simply not in it. Refreshing is a loop you own:

1. Call downloadPlan(expoKey) again — on a schedule, on app start, or on a pull-to-refresh. It is a no-op if the newest archive is already on the device.
2. Point the view at the new version.
3. Call removeOldVersionsOfDownloadedPlans(expoKey) to reclaim the space.

If you need to see the version without downloading anything, read it from the Offline Data API directly: version is the newest built archive, and versionActual running ahead of it means a newer one is pending. Poll the API no faster than about every two minutes — responses are cached server-side for roughly that long, so a faster loop just re-reads the same answer.

Preload ​

Preloading creates the plan now and keeps the live instance in memory, so that when the screen finally opens, the map is already there. Nothing is written to disk.

const id = await ExpofpViewModule.preloadPlan({ expoKey: "demo" });
// later, on the view:
// <ExpofpView preloadedPlanId={id} style={{ flex: 1 }} />

val info = ExpoFpPlan.preloader.preloadPlan(
    planLink = ExpoFpLinkType.ExpoKey("demo")
)
val presenter = ExpoFpPlan.preloader.getPreloadedPlanPresenter(info)

let info = ExpoFpPlan.preloader.preloadPlan(with: .expoKey("demo"))
let presenter = ExpoFpPlan.preloader.getPreloadedPlanPresenter(with: info)

The link you preload can be either kind, and this is the important part:

// Preload an online plan — needs the network right now.
await ExpofpViewModule.preloadPlan({ expoKey: "demo" });

// Preload a downloaded plan — needs nothing but the archive on disk.
await ExpofpViewModule.preloadPlan({ downloadedExpoKey: "demo" });

// Preload an online plan — needs the network right now.
ExpoFpPlan.preloader.preloadPlan(planLink = ExpoFpLinkType.ExpoKey("demo"))

// Preload a downloaded plan — needs nothing but the archive on disk.
ExpoFpPlan.preloader.preloadPlan(
    planLink = ExpoFpLinkType.DownloadedPlanInfo(downloadedPlanInfo)
)

// Preload an online plan — needs the network right now.
ExpoFpPlan.preloader.preloadPlan(with: .expoKey("demo"))

// Preload a downloaded plan — needs nothing but the archive on disk.
ExpoFpPlan.preloader.preloadPlan(with: .downloadedPlanInfo(downloadedPlanInfo))

Things to know about preloaded plans:

• They are not disposed for you. A preloaded plan survives the Activity, Fragment or screen that created it, on purpose, so you can reuse it. You must call disposePreloadedPlan / removeAllPreloadedPlans when you are done, or it holds its memory for the life of the process.
• They do not survive the process. Kill the app and every preloaded plan is gone. Preload again on the next launch.
• One instance renders on one screen at a time. A preloaded plan is a single rendering engine; attaching it to a second screen moves it there.
• They cost memory. Each one is a live WebView. Preload the two or three plans a user is about to open, not the whole catalogue.

Use it when the delay of opening a map is the problem you are solving — a tab bar where the map tab must be instant, a list of halls the user pages through, a splash screen you want to spend usefully.

Caching ​

"Caching" is the word that causes the most damage, because it names three unrelated mechanisms, none of which is a feature you can rely on.

1. The WebView's HTTP cache. An online plan is a web page, and the platform WebView caches its responses under ordinary HTTP rules. This is why a second open sometimes feels faster, and why it occasionally half-works on a flaky network. It is sized, expired and evicted by the operating system. It is not a guarantee and it is not addressable from the SDK.

2. The SDK's archive store. The unpacked downloaded plans described above. This one is real and addressable — but it lives in a cache directory, so the OS may still reclaim it (see the warning above).

3. The Offline Data API's server-side cache. get-or-create and get responses are cached for about 120 seconds. This affects how fast you learn that a new version exists; it has nothing to do with what is on the device.

What works in each mode ​

A note on the blue dot: it does not come from the plan. Positions are pushed into the plan by the location provider you install, and whether that provider works without a network is a property of the provider, not of the plan — check its own documentation. A location provider failing never blocks the plan: the map keeps loading and stays usable, just without a blue dot.

Choosing ​

Recipe: offline first, online fallback ​

The setup most event apps actually want. Note that the fallback is your code — the SDK does not chain sources for you, and passing both keys does not create a chain.

import { useEffect, useState } from "react";
import { ExpofpView, ExpofpViewModule } from "@expofp/react-native-efp-sdk";

const EXPO_KEY = "demo";

export function PlanScreen() {
  const [source, setSource] = useState<
    { downloadedExpoKey: string } | { expoKey: string } | null
  >(null);

  useEffect(() => {
    (async () => {
      // 1. Drop versions left over from previous runs, while nothing is on screen.
      ExpofpViewModule.removeOldVersionsOfDownloadedPlans(EXPO_KEY);

      // 2. Is a copy already on the device? Open it immediately, network or not.
      const local = await ExpofpViewModule.getDownloadedPlansInfo(EXPO_KEY);
      setSource(
        local.length > 0 ? { downloadedExpoKey: EXPO_KEY } : { expoKey: EXPO_KEY },
      );

      // 3. Refresh in the background. A no-op when the newest archive is present.
      try {
        await ExpofpViewModule.downloadPlan(EXPO_KEY);
        setSource({ downloadedExpoKey: EXPO_KEY }); // resolves to the newest version
      } catch {
        // Offline, or the build is still running. Step 2's choice stands.
      }
    })();
  }, []);

  if (!source) return null;
  return <ExpofpView {...source} style={{ flex: 1 }} />;
}

Note the order: superseded versions are removed at start-up, not right after the refresh. Deleting the files of an archive that is currently on screen is asking for trouble; leaving one extra version on disk until the next launch is not.

The same steps apply on native: getDownloadedPlansInfo to decide, downloadPlan to refresh, removeOldVersionsOfDownloadedPlans to clean up. Add preloadPlan on top if the screen must also open instantly.

Common misconceptions ​

"Preload means it works offline." No. Preload replays whatever link you gave it. Preloading an expo key needs the network at preload time, and the instance is gone when the process dies. Only a downloaded archive gives you offline capability.

"The plan is cached after the first open, so the second one works offline." No. That is the WebView's HTTP cache — opportunistic, evictable, and outside your control. It will work in testing and fail at the venue.

"Once downloaded, the plan is up to date." No. An archive is frozen at its version. Re-run downloadPlan to pick up a newer one.

"Offline is a flag on the view." No. There is no offline: true. You pass a different kind of link — an expo key for online, a downloaded plan for offline.

"downloadPlan downloads the plan for a particular view." No. It writes into app-wide storage keyed by expo key and version. Any view, any screen, can then open it.

"Setting both expoKey and downloadedExpoKey gives me an automatic fallback." No — and this one bites people. When both are set, expoKey wins and you get the online plan. Choose one, and implement the fallback yourself: check getDownloadedPlansInfo first, and pass downloadedExpoKey when there is a copy on the device.

"A downloaded plan stays on the device until I delete it." Usually, but not guaranteed. Archives live in a cache directory the system may reclaim under storage pressure. Verify before you depend on it.

Diagnosing a failure ​

The plan reports its state through the plan status callback — onPlanStatus in React Native, planStatusFlow on Android, planStatusPublisher on iOS — as Initialization, Loading(percentage), Ready or Error. The error usually tells you which of the four concepts went wrong:

See also ​

• Offline Data API — the endpoints behind downloadPlan, for building your own refresh logic
• iOS SDK reference
• Android SDK reference
• React Native SDK reference