@situm/react-native-ar

Augmented Reality integration for Situm in React Native applications.

This package provides a React Native interface to Situm’s native AR capabilities, designed to work in conjunction with the Situm MapView.

ℹ️ Notice

This module is an adaptation of an existing native AR solution to React Native.

Installation

@situm/react-native-ar operates in conjunction with @situm/react-native. This document provides guidance on how to configure and integrate both modules correctly.

yarn add @situm/[email protected] @situm/react-native-ar react-native-webview

⚠️ Important: After installation, verify that your yarn.lock resolves @situm/react-native to exactly version 3.18.9-arcompat.
Other versions are not supported.

Platform Configuration

Android

At the moment, the AR native library must be included manually in your application.

1. Configure local AAR repository

In android/app/build.gradle, at the root level:

repositories {
  flatDir {
    println "⭐ App library path 👉 $rootDir/libs"
    dirs "$rootDir/libs"
  }
}

2. Add the AR library

Create the directory:

android/libs/

Then place the AR library file inside it:

android/libs/ar-release.aar

Please contact Situm to obtain the required AAR file.

iOS

All required native dependencies are installed automatically when you add this module.
No additional manual steps are currently required.

React Native Architecture Support

ℹ️ React Native New Architecture Limitation

This module currently works only with the React Native Legacy Architecture on iOS. More information about React Native New Architecture in the official documentation. Support for React Native’s New Architecture is planned for future releases, and the codebase will be progressively adapted to work correctly with it.

Android

Configure the architecture in android/gradle.properties:

newArchEnabled=false

iOS

Update the following configuration in example/ios/Podfile:

ENV['RCT_NEW_ARCH_ENABLED'] = '0'

# Use the following only when enabling the New Architecture
# (not supported yet for this module):
installer.aggregate_targets.each do |aggregate_target|
  aggregate_target.user_project.build_configurations.each do |config|
    # Uncomment to enable New Architecture (not supported):
    # config.build_settings['RCT_NEW_ARCH_ENABLED'] = '1'
  end
end

Permissions

@situm/react-native-ar needs camera access to enable the AR experience. Additionally, please note that @situm/react-native requires a dedicated permission configuration to enable positioning, as described below.

You can find more information about the @situm/react-native setup in the official documentation.

Android Permissions

Add the following permissions to your AndroidManifest.xml:

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

⚠️ Important: Even though the CAMERA permission is declared in the manifest, it must still be requested at runtime according to Android’s permission model. Make sure your application handles this request before displaying any AR content.

iOS Permissions

Add the following entries to your Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for the AR experience</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Location is required to determine your position</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>Location is required to determine your position</string>

<key>NSMotionUsageDescription</key>
<string>Motion sensors are used to improve positioning accuracy</string>

Usage

The recommended integration approach is through SitumArManager, as shown in the example application.

SitumArManager is a high-level component that:

• Manages the native AR view lifecycle
• Integrates automatically with Situm MapView
• Subscribes to the required native events
• Controls AR visibility based on the MapView state

It requires a reference to a MapView (MapViewRef) to function correctly.

The following example is an evolution of the React Native Quickstart that integrates both the SitumArManager and the MapView.

// App.tsx
import { View, StyleSheet } from 'react-native';
import React, { useEffect, useRef } from 'react';

import SitumPlugin, {
  MapView,
  type MapViewRef,
  SitumProvider,
} from '@situm/react-native';
import { SitumArManager } from '@situm/react-native-ar';

const SITUM_API_KEY = 'YOUR_API_KEY';
const SITUM_BUILDING_ID = 'YOUR_BUILDING';
const SITUM_PROFILE = 'YOUR_PROFILE';

function App(): React.JSX.Element {
  const mapViewRef = useRef<MapViewRef | null>(null);

  useEffect(() => {
    SitumPlugin.init();
    SitumPlugin.enableUserHelper();
    setLocationCallbacks();

    SitumPlugin.requestLocationUpdates({
      buildingIdentifier: Number.parseInt(SITUM_BUILDING_ID),
    });

    return () => {
      SitumPlugin.removeLocationUpdates();
    };
  }, []);

  const setLocationCallbacks = () => {
    SitumPlugin.onLocationUpdate((location) => {
      console.log(`Location update: ${JSON.stringify(location)}`);
    });

    SitumPlugin.onLocationStatus((status) => {
      console.log(`Location status: ${status.statusName}`);
    });

    SitumPlugin.onLocationError((error) => {
      console.log(`Location error (${error.code}): ${error.message}`);
    });
  };

  const handleMapLoaded = (event: any) => {
    console.log('Map loaded:', JSON.stringify(event));
  };

  return (
    <View style={styles.container}>
      <SitumProvider apiKey={SITUM_API_KEY}>
        <View style={styles.viewerContainer}>
          <MapView
            ref={mapViewRef}
            configuration={{
              buildingIdentifier: SITUM_BUILDING_ID,
              profile: SITUM_PROFILE,
            }}
            onLoad={handleMapLoaded}
          />
          <SitumArManager
            mapViewRef={mapViewRef}
            buildingIdentifier={SITUM_BUILDING_ID}
            profile={SITUM_PROFILE}
          />
        </View>
      </SitumProvider>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  viewerContainer: {
    flex: 1,
    width: '100%',
    height: '100%',
  },
});

export default App;

Contributing

You will need to sign a Contributor License Agreement (CLA) before making a submission. Learn more here.

• Code of conduct

LICENSE

• License