react-native-pointr 9.2.0 → 9.5.0

package/README.md

@@ -12,6 +12,8 @@ Ensure you have the following set up before proceeding:
 
 ## 1. Install the Package
 
+### From npm Registry
+
 Run the following command to install the package using npm:
 
 ```
@@ -24,6 +26,32 @@ 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`:
+
+```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"
@@ -128,156 +156,217 @@ yarn add react-native-pointr
 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:
 
 ```typescript
-...
-import React, { useEffect, useRef } from 'react';
+import React, { useRef } from 'react';
 import {
   requireNativeComponent,
-  UIManager,
   findNodeHandle,
   Button,
   SafeAreaView,
   View,
   ScrollView,
-  Dimensions,
-  StyleSheet,
+  NativeSyntheticEvent,
+  NativeEventEmitter,
   NativeModules
 } from 'react-native';
-import { PTRSiteCommand, PTRBuildingCommand, PTRLevelCommand, PTRPoiCommand, PTRPathCommand, PTRStaticPathCommand, PTRCommand, PTRCommandType } from 'react-native-pointr/src/PTRCommand';
+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';
 ```
 
-Initialize and start Pointr instance before doing any operation.
+Define the `PTRMapWidget` component interface and create the component using `requireNativeComponent`:
 
 ```typescript
+interface PTRMapWidgetProps {
+  style?: any;
+  onMapWidgetDidEndLoading?: (event: NativeSyntheticEvent<any>) => void;
+}
 
-// 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}`);
-});
+const PTRMapWidget = requireNativeComponent<PTRMapWidgetProps>('PTRMapWidget');
 ```
 
-Define the `PTRMapWidget` component using `requireNativeComponent`:
+Initialize and start Pointr instance before doing any operation:
 
 ```typescript
-interface PTRMapWidgetProps {
-  onMapDidEndLoading?: (event: NativeSyntheticEvent<object>) => void;
-}
+// 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}`);
+});
 
-export const PTRMapWidget = requireNativeComponent<PTRMapWidgetProps>('PTRMapWidget');
+// 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:
 
 ```typescript
 function App(): React.JSX.Element {
-
-  const ref = useRef(null);
+  const ref = useRef<any>(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);
+  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:", ptrCommand);
+      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 }}>  
-      <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} />
+    <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>
   );
 }
@@ -285,6 +374,21 @@ function App(): React.JSX.Element {
 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](https://docs.pointr.tech/docs/8.x/Developer%20Portal/API%20Reference/api%20ref-mobile/).
 
 ## 5. Run the App

package/WAYFINDING_EVENTS.md

@@ -0,0 +1,243 @@
+# Wayfinding Events
+
+This document describes how to use the `onWayfindingEvent` callback to track wayfinding navigation events in the Pointr Map Widget.
+
+## Overview
+
+The `onWayfindingEvent` callback is triggered during wayfinding operations, providing information about the navigation state and destination. This allows you to track when users start, cancel, or complete navigation to a Point of Interest (POI).
+
+## Event Structure
+
+The `PTRWayfindingEvent` type is exported from the `react-native-pointr` package and contains the following data:
+
+```typescript
+import { type PTRWayfindingEvent } from 'react-native-pointr';
+
+// PTRWayfindingEvent structure:
+{
+  type: number;  // Event type indicator (-1, 0, or 1)
+  poi: PTRPoi;   // Destination POI information
+}
+```
+
+For the complete type definition, see [PTRWayfindingEvent.ts](./src/types/PTRWayfindingEvent.ts).
+
+### Event Types
+
+| Type | Value | Description |
+|------|-------|-------------|
+| Cancelled | `-1` | User cancelled the wayfinding navigation |
+| Started | `0` | Wayfinding navigation has started |
+| Ended | `1` | User completed or closed the wayfinding navigation |
+
+### POI Object
+
+The `poi` field is a `PTRPoi` object that contains complete information about the destination:
+
+```typescript
+import { type PTRPoi } from 'react-native-pointr';
+
+// PTRPoi structure:
+{
+  identifier: string;           // Internal unique identifier
+  externalIdentifier: string;   // External API reference ID
+  name: string;                 // Display name
+  typeCode: string;            // POI type (e.g., "lobby", "room")
+  position: PTRPosition;       // Geographic position
+  geometry: PTRGeometry;       // Shape data
+  attributes: PTRPoiAttributes; // Additional metadata
+}
+```
+
+For the complete type definition, see [PTRPoi.ts](./src/types/PTRPoi.ts).
+
+## Usage
+
+### 1. Import Required Types
+
+First, import the necessary types from the package:
+
+```typescript
+import { type PTRPoi, type PTRWayfindingEvent } from 'react-native-pointr';
+```
+
+### 2. Create Event Handler
+
+Implement the handler function to process wayfinding events:
+
+```typescript
+const handleWayfindingEvent = (event: NativeSyntheticEvent<PTRWayfindingEvent>) => {
+  const wayfindingEvent = event.nativeEvent;
+  
+  // Determine event type
+  let eventTypeName: string;
+  switch (wayfindingEvent.type) {
+    case -1:
+      eventTypeName = 'Cancelled';
+      // Handle cancellation (e.g., update UI, analytics)
+      break;
+    case 0:
+      eventTypeName = 'Started';
+      // Handle start (e.g., show navigation UI)
+      break;
+    case 1:
+      eventTypeName = 'Ended';
+      // Handle completion (e.g., hide navigation UI, show success)
+      break;
+    default:
+      eventTypeName = 'Unknown';
+  }
+  
+  // Access destination POI information
+  console.log(`Navigation ${eventTypeName} to: ${wayfindingEvent.poi.name}`);
+  console.log(`POI Type: ${wayfindingEvent.poi.typeCode}`);
+  console.log(`Location: Level ${wayfindingEvent.poi.position.lvl}`);
+};
+```
+
+### 3. Attach to Map Widget
+
+Attach the handler to the PTRMapWidget component:
+
+```typescript
+<PTRMapWidget 
+  ref={mapWidgetRef}
+  style={{ flex: 1 }}
+  onWayfindingEvent={handleWayfindingEvent}
+/>
+```
+
+## Complete Example
+
+```typescript
+import React, { useRef } from 'react';
+import {
+  requireNativeComponent,
+  NativeSyntheticEvent,
+  View,
+} from 'react-native';
+import { type PTRPoi, type PTRWayfindingEvent } from 'react-native-pointr';
+
+interface PTRMapWidgetProps {
+  style?: any;
+  onWayfindingEvent?: (event: NativeSyntheticEvent<PTRWayfindingEvent>) => void;
+}
+
+const PTRMapWidget = requireNativeComponent<PTRMapWidgetProps>('PTRMapWidget');
+
+function MapScreen() {
+  const mapWidgetRef = useRef<any>(null);
+  
+  const handleWayfindingEvent = (event: NativeSyntheticEvent<PTRWayfindingEvent>) => {
+    const { type, poi } = event.nativeEvent;
+    
+    switch (type) {
+      case -1:
+        console.log(`User cancelled navigation to ${poi.name}`);
+        // Update your app state - navigation was cancelled
+        break;
+      case 0:
+        console.log(`Started navigation to ${poi.name} at level ${poi.position.lvl}`);
+        // Update your app state - show navigation in progress
+        break;
+      case 1:
+        console.log(`Completed navigation to ${poi.name}`);
+        // Update your app state - navigation finished
+        break;
+    }
+  };
+  
+  return (
+    <View style={{ flex: 1 }}>
+      <PTRMapWidget 
+        ref={mapWidgetRef}
+        style={{ flex: 1 }}
+        onWayfindingEvent={handleWayfindingEvent}
+      />
+    </View>
+  );
+}
+
+export default MapScreen;
+```
+
+## Use Cases
+
+### Analytics Tracking
+
+Track navigation patterns and popular destinations:
+
+```typescript
+const handleWayfindingEvent = (event: NativeSyntheticEvent<PTRWayfindingEvent>) => {
+  const { type, poi } = event.nativeEvent;
+  
+  // Log to analytics service
+  analytics.track('Wayfinding Event', {
+    eventType: type === -1 ? 'cancelled' : type === 0 ? 'started' : 'ended',
+    destinationName: poi.name,
+    destinationType: poi.typeCode,
+    destinationId: poi.externalIdentifier,
+  });
+};
+```
+
+### UI State Management
+
+Update your UI based on navigation state:
+
+```typescript
+const [isNavigating, setIsNavigating] = useState(false);
+const [currentDestination, setCurrentDestination] = useState<string | null>(null);
+
+const handleWayfindingEvent = (event: NativeSyntheticEvent<PTRWayfindingEvent>) => {
+  const { type, poi } = event.nativeEvent;
+  
+  switch (type) {
+    case 0: // Started
+      setIsNavigating(true);
+      setCurrentDestination(poi.name);
+      break;
+    case -1: // Cancelled
+    case 1:  // Ended
+      setIsNavigating(false);
+      setCurrentDestination(null);
+      break;
+  }
+};
+```
+
+### Custom Notifications
+
+Show custom notifications based on events:
+
+```typescript
+import { Alert } from 'react-native';
+
+const handleWayfindingEvent = (event: NativeSyntheticEvent<PTRWayfindingEvent>) => {
+  const { type, poi } = event.nativeEvent;
+  
+  if (type === 1) { // Ended
+    Alert.alert(
+      'Navigation Complete',
+      `You have arrived at ${poi.name}`,
+      [{ text: 'OK' }]
+    );
+  }
+};
+```
+
+## Notes
+
+- The event is fired automatically by the native map widget during wayfinding operations
+- The POI object contains complete destination information including position, geometry, and custom attributes
+- Event types are consistent across both iOS and Android platforms
+- The event fires regardless of how wayfinding was initiated (tap, programmatic command, etc.)
+
+## Related Documentation
+
+- [PTRWayfindingEvent Type Definition](./src/types/PTRWayfindingEvent.ts)
+- [PTRPoi Type Definition](./src/types/PTRPoi.ts)
+- [PTRPosition Type Definition](./src/types/PTRPosition.ts)
+- [PTRGeometry Type Definition](./src/types/PTRGeometry.ts)
+- [PTR Commands](./src/PTRCommand.ts)
+- [API Reference](./API_REFERENCE.md)

package/android/build.gradle

@@ -1,6 +1,6 @@
 buildscript {
   // Buildscript is evaluated before everything else so we can't use getExtOrDefault
-  def kotlin_version = rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : "1.9.24"
+  def kotlin_version = rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : "2.2.21"
 
   repositories {
     google()
@@ -8,7 +8,6 @@ buildscript {
   }
 
   dependencies {
-    classpath "com.android.tools.build:gradle:8.10.1"
     classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
   }
 }
@@ -86,15 +85,15 @@ repositories {
   google()
 }
 
-def kotlin_version = rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : "1.9.24"
+def kotlin_version = rootProject.ext.has("kotlinVersion") ? rootProject.ext.get("kotlinVersion") : "2.2.21"
 
 dependencies {
   // For < 0.71, this will be from the local maven repo
   // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
   //noinspection GradleDynamicVersion
-  implementation "com.facebook.react:react-native:+"
+  implementation "com.facebook.react:react-android:0.82.1"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-  implementation("com.pointrlabs:pointr:9.2.0")
+  implementation("com.pointrlabs:pointr:9.5.0")
   implementation ("org.jetbrains.kotlin:kotlin-reflect:$kotlin_version")
   implementation 'com.google.android.material:material:1.12.0'
   implementation 'androidx.constraintlayout:constraintlayout:2.2.1'