React Native Quickstart: A basic React Native app

Situm SDK can be used to build Wayfinding and Tracking applications, and dozens of use cases within those realms. In this guide we will walk you through the steps to build a basic React Native app that uses our @situm/react-native plugin to display your building’s cartography.

Prerequisites #

Before you begin, make sure you have:

• A Situm account and an API key.
• A Situm building set up and calibrated. You can use our Situm Mapping Tool for this.
• A React Native development environment up and running, including a compatible smartphone or emulator. If this is your first React Native project, follow the Set Up Your Environment guide on the official React Native site to install Node, a JDK, Android Studio and/or Xcode.

Choose your workflow #

The Situm React Native plugin can be integrated in two different kinds of projects. Pick the one that best fits your case and follow the corresponding section below:

• Using Expo. The simplest path if you’re starting a new app. You’ll use create-expo-app and the Expo CLI. Note that the Situm plugin does not work in the Expo Go app — you need a development build, which is what this guide walks you through.
• Using the React Native CLI (no framework). Use this if you need full control over the native project or you’re integrating Situm into an existing app built with @react-native-community/cli.

Follow one of the two options below to create and prepare your project, then continue with the common steps further down (configure permissions, add the Situm code, run the app).

Option A: Using Expo #

A1. Create a new Expo project #

npx create-expo-app@latest my-indoor-location-app
cd my-indoor-location-app

If you haven’t set up simulators or devices yet, follow Expo’s Set up your environment guide (select “Development build” and “Build locally”) before continuing.

A2. Install the Situm plugin #

npx expo install @situm/react-native react-native-webview

A3. Generate the native project #

Because the Situm plugin contains native code, a native project is required (Expo Go alone is not enough). Run:

npx expo prebuild

This generates the android/ and ios/ directories in your project.

A4. Add the Situm Maven repository (Android) #

Open android/build.gradle and add the Situm repository under allprojects > repositories:

allprojects {
    repositories {
        maven { url "https://repo.situm.com/artifactory/libs-release-local" }
    }
}

Note: npx expo prebuild may overwrite this file. If you run prebuild again, you’ll need to re-apply this change.

Your Expo project is now ready. Skip to Configure your app.

Option B: Using the React Native CLI (no framework) #

B1. Create a new React Native project #

If you had the old React Native CLI installed globally, uninstall it first, then scaffold a new project with the current community CLI:

npm uninstall -g react-native-cli @react-native-community/cli
npx @react-native-community/cli@latest init my_indoor_location_app
cd my_indoor_location_app

B2. Install the Situm plugin #

# Using npm (recommended)
npm install --save @situm/react-native react-native-webview

# Or using Yarn Classic (1.x)
yarn add @situm/react-native react-native-webview

Heads up — Yarn Berry (2.x / 3.x / 4.x): If you use Yarn Berry with its default PnP/zip cache, React Native CLI commands such as run-android can fail with an error like spawnSync .../setup_env.sh ENOTDIR, because the CLI tries to execute a shell script from inside a compressed cache. To avoid this, use npm, use Yarn Classic (1.x), or configure Berry by adding nodeLinker: node-modules to your .yarnrc.yml.

B3. Install iOS pods #

cd ios && pod install && cd ..

B4. Configure Android minSdkVersion #

Open android/build.gradle and make sure minSdkVersion is set to 21 or later:

buildscript {
    ext {
        minSdkVersion = 21
        // ...
    }
}

Your React Native CLI project is now ready. Continue with Configure your app.

Configure your app #

Once you’ve finished Option A or Option B, the remaining steps are the same regardless of which workflow you chose.

Configure permissions #

Android #

Add the ACCESS_FINE_LOCATION permission declaration to your android/app/src/main/AndroidManifest.xml (you can omit this step if you have configured Situm SDK not to use GPS):

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

iOS #

You will also need to include the following permissions in your app’s Info.plist file (modify the permission’s informative texts as you wish):

<key>NSLocationWhenInUseUsageDescription</key>
<string>Location is required to find out where you are</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Location is required to find out where you are</string>
<key>NSMotionUsageDescription</key>
<string>We use your phone sensors (giroscope, accelerometer and altimeter) to improve location quality</string>

Add the Situm code #

Open your app’s entry file and replace its contents with the snippet below:

• In a default Expo project (with expo-router), edit app/index.tsx.
• In a React Native CLI project — or an Expo project created with --template blank — edit App.tsx at the project root.

The snippet below uses the App/App.tsx naming. If you’re using expo-router, save the file as app/index.tsx and rename the exported component from App to Index.

import React, { useEffect } from 'react';
import { SafeAreaView, StyleSheet } from 'react-native';
import SitumPlugin, { MapView, SitumProvider } from '@situm/react-native';

const SITUM_API_KEY = 'YOUR_SITUM_API_KEY';
const SITUM_BUILDING_ID = 'YOUR_BUILDING_ID';
const SITUM_PROFILE = 'YOUR_PROFILE';

const Screen = () => {
  useEffect(() => {
    // 1. Initialize the Situm plugin
    SitumPlugin.init();

    // 2. (Optional) Let the SDK handle permissions and sensor issues for you
    SitumPlugin.enableUserHelper();

    // 3. (Optional) Listen to positioning events
    SitumPlugin.onLocationUpdate((location) => {
      console.log(`SitumPlugin> Location: ${JSON.stringify(location)}`);
    });
    SitumPlugin.onLocationStatus((status) => {
      console.log(`SitumPlugin> Status: ${status.statusName}`);
    });
    SitumPlugin.onLocationError((error) => {
      console.log(`SitumPlugin> Error(${error.code}): ${error.message}`);
    });
  }, []);

  // 4. Show the building cartography
  return (
    <MapView
      style={styles.mapview}
      configuration={{
        buildingIdentifier: SITUM_BUILDING_ID,
        situmApiKey: SITUM_API_KEY,
        profile: SITUM_PROFILE,
      }}
      onPoiSelected={(poi) => console.log(`Poi selected: ${poi.identifier}`)}
      onLoad={(event) => console.log('Map is ready: ' + JSON.stringify(event))}
    />
  );
};

const App = () => (
  <SafeAreaView style={styles.container}>
    <SitumProvider>
      <Screen />
    </SitumProvider>
  </SafeAreaView>
);

const styles = StyleSheet.create({
  container: { flex: 1 },
  mapview: { flex: 1 },
});

export default App;

Run the app #

If you followed Option A (Expo):

# Android
npx expo run:android

# iOS
npx expo run:ios

If you followed Option B (React Native CLI):

# Android
npx react-native run-android

# iOS
npx react-native run-ios

In any case, you should see something like this:

iOS note: Situm uses CocoaPods to manage iOS dependencies. If the build fails after updating the plugin, run cd ios && pod repo update && pod install and try again.

Understanding the code #

The snippet uses two main building blocks from our plugin:

• MapView — the React Native component that displays the building’s cartography. Add it to your view hierarchy and configure it with your building identifier, API key and profile.
• SitumProvider — a wrapper that the Situm plugin uses to keep its internal state. You must wrap any screen that uses Situm with it, or wrap your entire application.

About SitumPlugin.enableUserHelper #

Starting in @situm/react-native@3.15.0, the SDK can automatically request the permissions needed for positioning and handle common sensor issues (e.g. BLE or Location disabled) for you. You can enable this by calling:

SitumPlugin.enableUserHelper();

This is a convenience shortcut and is entirely optional. If you’d rather manage permissions yourself (for example, with react-native-permissions), you can omit this call. You can also customise the UI with your own colour scheme via SitumPlugin.configureUserHelper(UserHelperOptions).

More examples #

Take a look at our example app, which contains different examples on how to perform several other actions using Situm.

To further configure the user experience, see our Advanced Topics section, which covers additional capabilities of both Situm SDK and MapView. Topics you may be interested in include: battery efficiency, location cache, working offline with cached data, foreground and background execution, external provider locations, listening to geofence entries and exits, providing your iOS app’s privacy manifest, and configuring the MapView UX.