Installation Guide for react-native-pointr NPM Package

This guide will walk you through the steps to install and configure the react-native-pointr npm package for your React Native project.

Prerequisites

Ensure you have the following set up before proceeding:

• Node.js installed (v18 or above).
• React Native CLI or Expo CLI installed.
• A React Native project already set up.

1. Install the Package

From npm Registry

Run the following command to install the package using npm:

npm i react-native-pointr

Or, if you use Yarn:

yarn add react-native-pointr

From Local Storage

If you have the package in your local project (e.g., in a modules folder), you can install it by referencing the local path:

Using npm:

npm install file:./modules/react-native-pointr

Or with Yarn:

yarn add file:./modules/react-native-pointr

Alternatively, you can add it directly to your package.json:

"dependencies": {
  "react-native-pointr": "file:./modules/react-native-pointr"
}

Then run npm install or yarn install to install the dependencies.

2. Integration to Mobile Platforms

=== "iOS"

For iOS projects, make sure to install the CocoaPods dependencies:

Navigate to the iOS folder:

```
cd ios
```

Open the `Podfile` with a text editor and add the access token and source for `PointrKit.xcframework` to the top of the file

```
source "https://github.com/pointrlabs/public-podspecs.git"
ENV['POINTR_SDK_TOKEN'] = '<YOUR_TOKEN>'
```

!!! note

    Acquire token (`<YOUR_TOKEN>`) to download the package and Pointr iOS native library from Pointr representative.

Run the following command to install the Pods:
```
pod install
```

!!! warning

    - If you encounter an issue similar to the following:
    ```
    [!] Unable to find a specification for `SocketRocket (= 0.7.0)` depended upon by `React-Core`
    You have either:
     * mistyped the name or version.
     * not added the source repo that hosts the Podspec to your Podfile.
    ```
    - Next, add the following line within your target block.
    ```
    pod 'SocketRocket', :git => 'https://github.com/facebookincubator/SocketRocket.git', :tag => '0.7.0'
    ```
    For example, if your project name is "TestProject", your target 'TestProject' should look like this:
    ```
    target 'TestProject' do
      config = use_native_modules!
      pod 'SocketRocket', :git => 'https://github.com/facebookincubator/SocketRocket.git', :tag => '0.7.0'
      use_react_native!(
        :path => config[:reactNativePath],
        # An absolute path to your application root.
        :app_path => "#{Pod::Config.instance.installation_root}/.."
      )
      ...
    ```


Return to the root project directory:

```
cd ..
```

=== "Android"

For Android projects, make sure you add the repository to get Pointr Android native libraries.

Navigate to the Android folder:

```
cd android
```

Open `build.gradle` with an editor and add the following lines. 

```
allprojects {
    repositories {
        maven {
            url "https://android.pointr.dev/artifactory/gradle-release-local"
            credentials {
                username '<USERNAME>'
                password '<PASSWORD>'
            }
        }
    }
}
```

!!! note

    Acquire user name (`<USERNAME>`) and password (`<PASSWORD>`) to access the repository that hosts Pointr Android native library from Pointr representative.

Return to the root project directory:

```
cd ..
```

Make sure your Android project is set up to use AndroidX (React Native 0.60 and above support AndroidX out of the box). No additional steps should be necessary. If you encounter any issues, ensure your android/build.gradle is using the correct dependencies.

4. Usage

Import the package exports and render the map widget:

import { PTRMapWidget, PTRSiteCommand } from 'react-native-pointr';
import type { PTRConfiguration, PTRMapWidgetConfiguration } from 'react-native-pointr';

The simplest integration passes sdkConfig, mapWidgetConfig, and command as props directly — the widget handles initialization automatically:

const SDK_CONFIG: PTRConfiguration = {
  clientId: '<CLIENT_ID>',
  licenseKey: '<LICENSE_KEY>',
  baseUrl: 'https://<your-instance>.pointr.cloud',
};

const MAP_CONFIG: PTRMapWidgetConfiguration = {
  isLevelSelectorEnabled: true,
  isExitButtonEnabled: false,
};

function MapScreen() {
  return (
    <PTRMapWidget
      style={{ flex: 1 }}
      sdkConfig={SDK_CONFIG}
      mapWidgetConfig={MAP_CONFIG}
      command={new PTRSiteCommand('<SITE_EXTERNAL_ID>')}
      onMapWidgetDidEndLoading={(e) => console.log('Map loaded', e.nativeEvent)}
      onWayfindingEvent={(e) => console.log('Navigation event', e.nativeEvent)}
    />
  );
}

To manage the SDK lifecycle and position updates at the app level, use the usePointrSdk hook:

import { usePointrSdk, usePointrPosition } from 'react-native-pointr';

function App() {
  const { sdk, isStarted, state } = usePointrSdk(SDK_CONFIG);

  const position = usePointrPosition(isStarted);

  const checkPosition = async () => {
    const loc = await sdk.getCurrentLocation();
    if (loc) console.log(loc.latitude, loc.longitude, loc.levelIndex);
  };
}

Available Commands

import { PTRSiteCommand, PTRBuildingCommand, PTRLevelCommand, PTRPoiCommand,
         PTRPathCommand, PTRStaticPathCommand, executeMapCommand } from 'react-native-pointr';

executeMapCommand(mapRef, new PTRSiteCommand('site-id'));
executeMapCommand(mapRef, new PTRBuildingCommand('site-id', 'building-id'));
executeMapCommand(mapRef, new PTRLevelCommand('site-id', 'building-id', 2));
executeMapCommand(mapRef, new PTRPoiCommand('site-id', 'poi-id'));
executeMapCommand(mapRef, new PTRPathCommand('site-id', 'poi-id'));
executeMapCommand(mapRef, new PTRStaticPathCommand('site-id', 'from-poi', 'to-poi'));

Available Hooks

import { usePointrSdk, usePointrPosition, usePointrPois,
         usePointrGeofence, usePointrBuildingClick, usePointrSiteClick } from 'react-native-pointr';

const { sdk, state, isInitialized, isStarted } = usePointrSdk(config);
const position = usePointrPosition(enabled);
const { pois, loading, error, refetch } = usePointrPois(siteId);
usePointrGeofence((event) => console.log('Geofence:', event));
usePointrBuildingClick((event) => console.log('Building:', event));
usePointrSiteClick((event) => console.log('Site:', event));

For the complete API see the API Reference.

5. Run the App

After completing the setup, start your app by running:

=== "iOS"

```
npx react-native run-ios
```

=== "Android"

```
npx react-native run-android
```

That’s it! Your package should now be installed and ready to use in your React Native project. For more details on usage and advanced configuration, refer to the API documentation.

6. Run the Example App

To explore the included demo app:

cd example/pointr_rn_demo
npm install

# iOS
cd ios && pod install && cd ..
npm run ios

# Android
npm run android