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

Now you can start using the package in your React Native components. Here's a simple example of how to import on App.tsx file:

import React, { useRef } from 'react';
import {
  requireNativeComponent,
  findNodeHandle,
  Button,
  SafeAreaView,
  View,
  ScrollView,
  NativeSyntheticEvent,
  NativeEventEmitter,
  NativeModules
} from 'react-native';
import { 
  PTRSiteCommand, 
  PTRBuildingCommand, 
  PTRLevelCommand, 
  PTRPoiCommand, 
  PTRPathCommand, 
  PTRStaticPathCommand,
  PTRMarkMyCarLevelCommand,
  PTRMarkMyCarSiteCommand,
  PTRShowMyCarSiteCommand,
  PTRStartAndFocusCommand
} from 'react-native-pointr/src/PTRCommand';
import { showMapWidget } from 'react-native-pointr/src/PTRMapWidgetUtils';

Define the PTRMapWidget component interface and create the component using requireNativeComponent:

interface PTRMapWidgetProps {
  style?: any;
  onMapWidgetDidEndLoading?: (event: NativeSyntheticEvent<any>) => void;
}

const PTRMapWidget = requireNativeComponent<PTRMapWidgetProps>('PTRMapWidget');

Initialize and start Pointr instance before doing any operation:

// Initialize Pointr instance with the provided credentials
NativeModules.PTRNativePointrLibrary.initialize(
  "<CLIENT_ID>",
  "<LICENSE_KEY>",
  "<BASE_URL>",
  <LOG_LEVEL>  // 0=off, 1=error, 2=warn, 3=info, 4=debug
);

// Start the Pointr SDK
NativeModules.PTRNativePointrLibrary.start((state: string) => {
  console.log(`Pointr state: ${state}`);
});

// Create event emitter for Pointr events (optional)
const PTREventEmitter = NativeModules.PTRNativePointrLibrary;
const nativeEventEmitter = new NativeEventEmitter(PTREventEmitter);

Implement the map widget in your React Native component:

function App(): React.JSX.Element {
  const ref = useRef<any>(null);
  
  const handleMapWidgetDidEndLoading = (event: NativeSyntheticEvent<any>) => {
    const ptrCommandResponse = event.nativeEvent;
    if (ptrCommandResponse.command === "site") {
      console.log("Map did end loading:", ptrCommandResponse.command, ptrCommandResponse.siteExternalIdentifier, ptrCommandResponse.error);
    } else {
      console.log("Map did end loading with unknown parameters:", ptrCommandResponse);
    }
  };

  const showSite = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      let command = new PTRSiteCommand("your-site-id");
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  const showBuilding = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      let command = new PTRBuildingCommand("your-site-id", "your-building-id");
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  const showLevel = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      let command = new PTRLevelCommand("your-site-id", "your-building-id", 2);
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  const showPoi = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      let command = new PTRPoiCommand("your-site-id", "your-poi-id");
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  const showPath = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      let command = new PTRPathCommand("your-site-id", "your-poi-id");
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  const showStaticPath = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      let command = new PTRStaticPathCommand("your-site-id", "from-poi-id", "to-poi-id");
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  const markMyCarLevel = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      let command = new PTRMarkMyCarLevelCommand("your-site-id", "your-building-id", 1, true);
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  const markMyCarSite = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      let command = new PTRMarkMyCarSiteCommand("your-site-id", true);
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  const showMyCarSite = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      let command = new PTRShowMyCarSiteCommand("your-site-id", true);
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  const startAndFocusSite = () => {
    const reactTag = findNodeHandle(ref.current);
    if (reactTag) {
      const siteCommand = new PTRSiteCommand("your-site-id");
      const command = new PTRStartAndFocusCommand(
        "your-client-id",
        "your-license-key",
        "your-base-url",
        0,
        siteCommand
      );
      showMapWidget(reactTag, command);
    } else {
      console.error("Failed to find node handle for ref");
    }
  };

  return (
    <SafeAreaView style={{ flex: 1 }}>
      <View style={{ flex: 1 }}>
        <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16 }}>
          <Button title="Show Site" onPress={showSite} />
          <View style={{ height: 12 }} />
          <Button title="Show Building" onPress={showBuilding} />
          <View style={{ height: 12 }} />
          <Button title="Show Level" onPress={showLevel} />
          <View style={{ height: 12 }} />
          <Button title="Show POI" onPress={showPoi} />
          <View style={{ height: 12 }} />
          <Button title="Show Path" onPress={showPath} />
          <View style={{ height: 12 }} />
          <Button title="Show Static Path" onPress={showStaticPath} />
          <View style={{ height: 12 }} />
          <Button title="Mark My Car Level" onPress={markMyCarLevel} />
          <View style={{ height: 12 }} />
          <Button title="Mark My Car Site" onPress={markMyCarSite} />
          <View style={{ height: 12 }} />
          <Button title="Show My Car Site" onPress={showMyCarSite} />
          <View style={{ height: 12 }} />
          <Button title="Start & Focus Site" onPress={startAndFocusSite} />
        </ScrollView>
      </View>
      <PTRMapWidget 
        ref={ref} 
        style={{ flex: 4 }} 
        onMapWidgetDidEndLoading={handleMapWidgetDidEndLoading} 
      />
    </SafeAreaView>
  );
}

export default App;

Available Commands

The package provides several command types for interacting with the map:

• PTRSiteCommand: Display a specific site
• PTRBuildingCommand: Display a specific building within a site
• PTRLevelCommand: Display a specific level of a building
• PTRPoiCommand: Display and focus on a specific point of interest (POI)
• PTRPathCommand: Display a navigation path from the current location to a POI
• PTRStaticPathCommand: Display a navigation path between two POIs
• PTRMarkMyCarLevelCommand: Mark car location at a specific level
• PTRMarkMyCarSiteCommand: Mark car location at site level
• PTRShowMyCarSiteCommand: Show marked car location on the site
• PTRStartAndFocusCommand: Initialize SDK and focus on a location in one command

For more information about the available functionality, check the API documentation.

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.