Introduction #
Share Live Location allows a user to share their real-time indoor position with another user for a limited period of time.
When sharing starts, the app creates a temporary sharing session, identified by a unique session ID. A link containing this ID is generated and can be sent to other users. Anyone opening the link subscribes to the session and can view the sender’s live position on a map, either in a web browser or inside a mobile app (if deep linking is configured).
Location updates are automatically delivered while the session remains active, until the selected duration expires or the sender stops sharing manually. If positioning temporarily stops (for example, due to connectivity or the app going to background), the session itself remains active and updates resume automatically when positioning continues.
Requisites #
In order to work, some pre-requisites (detailed below) must be satisfied:
- The Viewer profile used by the app must have Share Live Location enabled.
- The sender must use a mobile application integrating the Situm SDK and Map Viewer.
- The sender must be positioned inside a calibrated Situm building.
- The receiver must open the generated session link, either in a browser or in a mobile app (configured to handle it via deeplinking).
How Share Live location works #
As mentioned above, the Share Live Location feature involves two distinct roles:
- Sender: the user who shares their real-time location from a Situm-powered mobile app.
- Receiver: the user who opens a link and views a map (either on a browser or a mobile app) displaying the sender’s live position.
Sender #
Starting a Shared location session #
To be able to share its location, the sender must be actively positioning within the bounds of a building configured and calibrated with Situm. The user will see a pin-shaped button in the sidebar to start sharing his/her location.
Upon tapping this button, a modal dialog opens allowing to:
- Select the duration of the Shared Location Session: 15 minutes, 1 hour or 3 hours.
- Start sharing the location (enabled only if the user is currently positioning within the venue).
- Cancel the shared location session
Managing an Active Session #
Immediately after the session starts, a top banner appears, indicating that a Shared location session is currently active (and the remaining sharing time).
Also, if the user taps either the active session banner or the sidebar sharing button, a modal dialog will open, allowing the user to stop the current session or share/copy the session link again.
Sharing an Active Session #
Once the user starts a shared location session:
- The application generates a unique link.
- The user can share the link using the device’s share menu (using the Web Share API underneath) or copy it to the clipboard.
Session Expiration #
The session will terminate once the selected time period has elapsed (15 minutes, 1 hour, or 3 hours), or if the user manually stops it. When the configured duration expires, a modal dialog appears informing the user that the session has ended and offering the option to start a new shared location session.
Edge cases #
If any of the following occurs during an active session the live location updates will temporarily stop:
- The sender goes offline.
- The user moves outside of the venue bounds.
- The user closes the application.
However:
- The session itself does not expire.
- If the user resumes positioning before the session duration ends, live streaming will automatically resume.
Receiver #
The receiver gets the link from the sender. This link can be:
- A web app URL (default behavior), or
- A deeplink, if specifically configured.
When opened, the link launches a MapViewer that subscribes to the live location stream of the sender.
What does the receiver see? #
The receiver sees:
- A banner indicating that a shared location is being shown, as well as the remaining session time.
- Tapping the banner centers the camera on the shared location.
- A POI-like marker on the map representing the sender’s position.
- This marker is updated as new locations are received.
- A bottom drawer panel displaying:
- Whether the location has been updated recently (or when was it acquired).
- A button to cancel the subscription to the shared location.
When does the Session end? #
If the session expires or is manually canceled by the sender:
- The banner is removed.
- The map marker disappears.
- The bottom drawer indicates that the shared location session has finished.
Behaviour and limitations #
- Session persistence (receiving side): The active viewing session is stored locally on the receiving device. If the application is closed and reopened, the Viewing Shared Location state is automatically restored, provided the session is still active.
- Device support: This feature is designed for mobile devices only. Desktop devices are not supported yet.
- Mutual exclusivity: A user cannot share their location and receive (view) a shared location at the same time.
- Navigation: Navigation to the shared location is not supported.
- Camera behavior: Automatic camera focus on the shared location is not available. The user must manually re-center the map (e.g., via the banner interaction).
- Invalid or stale location updates: If a shared location session is active but the sender location is not valid, the receiver will see a different status message:
- In the top banner.
- In the POI description within the bottom drawer.
How to enable Share Live Location #
Enabling Share Live Location in your Viewer profile #
Before users can share their location, the feature must be enabled in the Map Viewer profile.
To do this:
- Open the Configuration Panel in Situm’s Map Viewer
- Go to Developer Settings → Features,
- Enable Share Live Location, and save the profile.
Once enabled, the sharing controls will appear in the viewer and users will be able to start sharing sessions (see Starting Shared location session)
Enabling the sender to share their location #
The user who shares their location must use a mobile application that integrates the Situm SDK and includes the Situm Map Viewer (see the QuickStart corresponding guides [iOS, React Native] for integration details). This mobile app must also use the profile where Share Live Location was enabled (see previous section).
The user must also be actively positioning inside a calibrated Situm building. When these conditions are met, the user will be able to start a sharing session and generate a link that can be sent to other users (see Sharing an Active Session).
These are the minimum SDK versions that support this feature:
| Platform | Minimum version |
|---|---|
| Android | Not implemented yet |
| iOS | 3.36.0+ |
| React Native | 3.18.5+ |
| Flutter | Not implemented yet |
| Cordova/Capacitor | Not implemented yet |
Enabling the receiver to view the shared location #
The receiver can access the shared location either in a browser or inside a mobile application, depending on how the integration is configured.
Viewing the location in a browser (default behaviour) #
No additional configuration is required. The receiver simply opens the link sent by the sender and a web Map Viewer will display the live position.
Viewing the location inside a mobile app (using deep linking) #
For a more integrated experience, the link can open directly inside your mobile application instead of a browser. This can be achieved with Deep Links: a type of hyperlink that goes beyond a simple website URL. Instead of just opening a web page in a browser, a deep link is designed to open a mobile application (on Android or iOS) directly.
To support this:
- First, associate your domain with your app (Universal Links on iOS / App Links on Android) so the operating system knows your app should handle the link.
- Then, configure the Viewer profile to use your domain as the base URL instead of
https://maps.situm.com. From that point on, generated sharing links will use your domain.
- When the app is opened from the link, extract the
shared_session_idparameter from the URL and pass it to the Situm SDK so the Map Viewer subscribes to the correct sharing session:
| Platform | Method |
|---|---|
| Android | Not implemented yet |
| iOS | setShareLiveLocationSession |
| React Native | setShareLiveLocationSession |
| Flutter | Not implemented yet |
| Cordova / Capacitor | Not implemented yet |