npm package: @situm/react-native-ar
Description: Situm Augmented Reality for React Native
Author: Situm Technologies
Latest version: 1.0.3

# @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.

```sh
yarn add @situm/react-native@3.18.9-arcompat @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:

```gradle
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](https://reactnative.dev/architecture/landing-page).
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`:

```properties
newArchEnabled=false
```

---

### iOS

Update the following configuration in `example/ios/Podfile`:

```ruby
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](https://situm.com/docs/initialization-and-common-configurations/).

---

### Android Permissions

Add the following permissions to your `AndroidManifest.xml`:

```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`:

```xml
<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](https://situm.com/docs/a-basic-react-native-app/) that integrates both the `SitumArManager` and the `MapView`.

```js
// 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](https://situm.com/contributions/).

- [Code of conduct](CODE_OF_CONDUCT.md)

## LICENSE

- [License](LICENSE)