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

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

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, { useEffect, useRef } from 'react';
import {
  requireNativeComponent,
  UIManager,
  findNodeHandle,
  Button,
  SafeAreaView,
  View,
  ScrollView,
  Dimensions,
  StyleSheet,
  NativeModules
} from 'react-native';
import { PTRSiteCommand, PTRBuildingCommand, PTRLevelCommand, PTRPoiCommand, PTRPathCommand, PTRStaticPathCommand, PTRCommand, PTRCommandType } from 'react-native-pointr/src/PTRCommand';
import { showMapWidget } from 'react-native-pointr/src/PTRMapWidgetUtils';

Initialize and start Pointr instance before doing any operation.

// initialize Pointr instance with the provided credentials
NativeModules.PTRNativePointrLibrary.initialize("<LICENSE_KEY>", "<API_URL>", "<CLIEND_ID>", "<ENVIRONMENT>", <LOG_LEVEL>);
NativeModules.PTRNativePointrLibrary.start((state: string) => {
  console.log(`Pointr state: ${state}`);
});

Define the PTRMapWidget component using requireNativeComponent:

interface PTRMapWidgetProps {
  onMapDidEndLoading?: (event: NativeSyntheticEvent<object>) => void;
}

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

Implement the map widget in your React Native component:

function App(): React.JSX.Element {

  const ref = useRef(null);
  
  const handleMapWidgetDidEndLoading = (event: NativeSyntheticEvent<object>) => {
    const ptrCommand = event.nativeEvent;
    if (ptrCommand.command == "site") {
      console.log("Map did end loading with parameters:", ptrCommand.command, ptrCommand.siteExternalIdentifier, ptrCommand.error);
    } else if (ptrCommand.command == "building") {
      console.log("Map did end loading with parameters:", ptrCommand.command, ptrCommand.siteExternalIdentifier, ptrCommand.buildingExternalIdentifier, ptrCommand.error);
    } else if (ptrCommand.command == "level") {
      console.log("Map did end loading with parameters:", ptrCommand.command, ptrCommand.siteExternalIdentifier, ptrCommand.buildingExternalIdentifier, ptrCommand.levelIndex, ptrCommand.error);
    } else if (ptrCommand.command == "poi") {
      console.log("Map did end loading with parameters:", ptrCommand.command, ptrCommand.siteExternalIdentifier, ptrCommand.poiExternalIdentifier, ptrCommand.error);
    } else if (ptrCommand.command == "path") {
      console.log("Map did end loading with parameters:", ptrCommand.command, ptrCommand.siteExternalIdentifier, ptrCommand.poiExternalIdentifier, ptrCommand.error);
    } else if (ptrCommand.command == "staticPath") {
      console.log("Map did end loading with parameters:", ptrCommand.command, ptrCommand.siteExternalIdentifier, ptrCommand.fromPoiExternalIdentifier, ptrCommand.toPoiExternalIdentifier, ptrCommand.error);
    } else {
      console.log("Map did end loading with unknown parameters:", ptrCommand);
    }
  };

  return (
    <SafeAreaView style={{ flex: 1 }}>  
      <ScrollView contentInsetAdjustmentBehavior="automatic" style={{ flex: 1 }}>
        <Button
          title="Show Site"
          onPress={() => {
            const reactTag = findNodeHandle(ref.current);
            console.log(`React tag: "${reactTag}" to show site`);
            if (reactTag !== null) {
              let command = new PTRSiteCommand("officebuilding");
              showMapWidget(reactTag, command);
            } else {
              console.error("Failed to find node handle for ref");
            }
          }}
        />
        <Button 
        title="Show Building"
        onPress={() => {
          const reactTag = findNodeHandle(ref.current);
          console.log(`React tag: "${reactTag}" to show building`);
          if (reactTag !== null) {
            let command = new PTRBuildingCommand("officebuilding", "office2");
            showMapWidget(reactTag, command);
          } else {
            console.error("Failed to find node handle for ref");
          }
        }}
        />
        <Button 
        title="Show level"
        onPress={() => {
          const reactTag = findNodeHandle(ref.current);
          console.log(`React tag: "${reactTag}" to show level`);
          if (reactTag !== null) {
            let command = new PTRLevelCommand("officebuilding", "office2", 2);
            showMapWidget(reactTag, command);
          } else {
            console.error("Failed to find node handle for ref");
          }
        }}
        />
        <Button 
          title="Show Poi"
          onPress={() => {
            const reactTag = findNodeHandle(ref.current);
            console.log(`React tag: "${reactTag}" to show poi`);
            if (reactTag !== null) {
              let command = new PTRPoiCommand("officebuilding", "Accessories");
              showMapWidget(reactTag, command);
            } else {
              console.error("Failed to find node handle for ref");
            }
          }}
        />
        <Button 
          title="Show path"
          onPress={() => {
            const reactTag = findNodeHandle(ref.current);
            console.log(`React tag: "${reactTag}" to show poi`);
            if (reactTag !== null) {
              let command = new PTRPathCommand("officebuilding", "Accessories");
              showMapWidget(reactTag, command);
            } else {
              console.error("Failed to find node handle for ref");
            }
          }}
        />
        <Button
          title="Show Static Path"
          onPress={() => {
            const reactTag = findNodeHandle(ref.current);
            console.log(`React tag: "${reactTag}" to show site`);
            if (reactTag !== null) {
              let command = new PTRStaticPathCommand("officebuilding", "Accessories", "Lobby");
              showMapWidget(reactTag, command);
            } else {
              console.error("Failed to find node handle for ref");
            }
          }}
        />
      </ScrollView>
      <View style={{ flex: 5 }}>
        <PTRMapWidget ref={ref} style={{ flex: 1 }} onMapWidgetDidEndLoading={handleMapWidgetDidEndLoading} />
      </View>
    </SafeAreaView>
  );
}

export default App;

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.