Session local or GPS anchored

Session-local or GPS-anchored?

The first architectural decision in a location-based AR app is made per object, not once: does this thing live in the session's local coordinate frame, or is it tied to a place on Earth?

Getting it wrong is not a crash. It is a slow feeling of wrongness that is hard to attribute later, so it is worth deciding deliberately.

The two frames

Session-local. The object sits at a fixed position inside the AR tracking frame (arWorldGroup). It is welded to the tracked world, so it stays visually nailed to its spot for the whole session — and its GPS position drifts as the alignment is corrected, so it cannot be replayed or shared by coordinate. When the session ends it is gone unless you saved something yourself.

GPS-anchored. The object's truth is a latitude and longitude. Created through createGpsAnchor, it also lives inside arWorldGroup — so it rides with the camera and stays visually stable — but its local position is re-derived every tick from its GPS target and the current alignment, so it keeps its real-world coordinate. It survives a reload and can be handed to another device.

The mechanical difference is not "inside or outside the group": both of those live inside it. It is whether the object's local position is fixed or re-derived each tick from a coordinate. (There is a third placement — parented to the scene root at world coordinates — which keeps the world pose exactly right but visually floats, because the camera moves under corrections while the object stands still.)

The decision procedure

Ask one question: if a second person opened this experience on their phone, should they see this object in the same physical place?

If yes, it is GPS-anchored. If it is meaningless to them — because it exists only in this session, for this user, as a result of something they just did — it is session-local.

A few consequences fall out:

• A trail of where the user walked is session-local. It is a record of their path in their session. It should not be nudged by an alignment update, because the alignment update does not change where they walked.
• A waypoint on a tour is GPS-anchored. It exists before the user arrives and after they leave.
• A decoration the user placed by hand on a specific bench is session-local, even though it is "in a place" — because the user's intent was there, where I put it, not at these coordinates. Correcting it toward GPS truth moves it away from where they aimed.
• A shareable placement — the thing another person opens by link — is necessarily GPS-anchored. There is nothing else to send.
• A HUD element is neither. It belongs to the camera, not the world — and in a WebXR session that has its own set of rules.

The failure modes

Everything anchored. Hand-placed content drifts under the user's aim as the estimator improves. Each individual correction is defensible; the cumulative experience is that the app keeps moving things you carefully positioned. Users read this as a bug and are not wrong.

Everything local. Nothing persists and nothing shares. The app is a diorama that evaporates on reload, and its "location-based" claim comes down to a proximity check at startup.

Deciding by convenience. Local is easier to implement, so early prototypes tend to make everything local, and the persistence requirement then arrives as a rewrite. Deciding per object up front costs nothing and prevents that.

A worked example

A GPS-anchored scavenger hunt:

• Hidden objects at fixed coordinates — GPS-anchored. They are the game; every player must find them in the same physical spot.
• A "found it!" burst of particles — session-local, and momentary. Nobody else needs it.
• The path the player walked, drawn behind them — session-local. It is theirs.
• A marker the player drops to remember where they parked — session-local if it lasts one session; GPS-anchored the moment you want it to survive the app closing.
• Distance and direction indicators — camera-space HUD, driven by the anchored objects' positions.

Five kinds of content, three different frames, one app. Which is normal — the mistake is assuming a location-based app has one answer.