react-native-pointr 9.2.0 → 9.5.0

package/API_REFERENCE.md

@@ -0,0 +1,887 @@
+# React Native Pointr - API Reference
+
+> **Platform Compatibility:** This API reference is identical for both Android and iOS platforms. All methods, parameters, and behaviors are consistent across platforms.
+
+## Table of Contents
+- [Native Module API](#native-module-api)
+- [Map Widget Component](#map-widget-component)
+- [Command Types](#command-types)
+- [Utility Functions](#utility-functions)
+- [Event Listeners](#event-listeners)
+
+---
+
+## Native Module API
+
+### `PTRNativePointrLibrary`
+
+The main native module for interacting with the Pointr SDK.
+
+#### Methods
+
+##### `initialize(clientId, licenseKey, baseUrl, logLevel)`
+
+Initializes the Pointr SDK with credentials.
+
+**Parameters:**
+- `clientId` (string): Your Pointr client identifier
+- `licenseKey` (string): Your Pointr license key
+- `baseUrl` (string): The Pointr cloud base URL
+- `logLevel` (number): Log level (0-4)
+  - `0`: Verbose
+  - `1`: Debug
+  - `2`: Info
+  - `3`: Warning
+  - `4`: Error
+
+**Example:**
+```typescript
+import { NativeModules } from 'react-native';
+
+NativeModules.PTRNativePointrLibrary.initialize(
+  "client-id",
+  "license-key",
+  "https://your-instance.pointr.cloud",
+  3
+);
+```
+
+---
+
+##### `start(callback)`
+
+Starts the Pointr SDK.
+
+**Parameters:**
+- `callback` (function): Callback function that receives the Pointr state as a string
+
+**Example:**
+```typescript
+NativeModules.PTRNativePointrLibrary.start((state: string) => {
+  console.log(`Pointr state: ${state}`);
+});
+```
+
+**Possible States:**
+- `"running"` - SDK is running successfully
+- `"failed registration"` - Registration failed
+- `"failed validation"` - Validation failed
+- `"failed invalid deep link url"` - Invalid deep link URL
+- `"failed no internet"` - No internet connection
+- `"off"` - SDK is off
+
+---
+
+##### `stop()`
+
+Stops the Pointr SDK.
+
+**Example:**
+```typescript
+NativeModules.PTRNativePointrLibrary.stop();
+```
+
+---
+
+##### `requestPermissions()`
+
+Requests necessary permissions (location, bluetooth, etc.).
+
+**Example:**
+```typescript
+NativeModules.PTRNativePointrLibrary.requestPermissions();
+```
+
+---
+
+##### `shouldRequestPermissionsAtStartup(shouldRequest)`
+
+Sets whether permissions should be requested automatically at startup.
+
+**Parameters:**
+- `shouldRequest` (boolean): True to request permissions automatically
+
+**Example:**
+```typescript
+NativeModules.PTRNativePointrLibrary.shouldRequestPermissionsAtStartup(true);
+```
+
+---
+
+##### `getCurrentLocation(callback)`
+
+Gets the current calculated position.
+
+**Parameters:**
+- `callback` (function): Callback function that receives location data or null
+
+**Example:**
+```typescript
+NativeModules.PTRNativePointrLibrary.getCurrentLocation((location) => {
+  if (location) {
+    console.log('Site:', location.siteExternalIdentifier);
+    console.log('Building:', location.buildingExternalIdentifier);
+    console.log('Level:', location.levelIndex);
+    console.log('Coordinates:', location.latitude, location.longitude);
+  }
+});
+```
+
+**Location Object:**
+- `siteInternalIdentifier` (string)
+- `siteExternalIdentifier` (string)
+- `buildingInternalIdentifier` (string)
+- `buildingExternalIdentifier` (string)
+- `levelIndex` (number)
+- `latitude` (number)
+- `longitude` (number)
+- `accuracy` (number)
+- `heading` (number) - Only present if heading accuracy is high
+
+---
+
+##### `isMyCarMarked(callback)`
+
+Checks if a "My Car" location has been saved.
+
+**Parameters:**
+- `callback` (function): Callback with no arguments if marked, error message if not
+
+**Example:**
+```typescript
+NativeModules.PTRNativePointrLibrary.isMyCarMarked((error) => {
+  if (!error) {
+    console.log('My car location is marked');
+  } else {
+    console.log('No saved location:', error);
+  }
+});
+```
+
+---
+
+##### `setPointrMapWidgetConfiguration(configJson)`
+
+Sets the map widget configuration.
+
+**Parameters:**
+- `configJson` (string): JSON string with configuration options
+
+**Example:**
+```typescript
+NativeModules.PTRNativePointrLibrary.setPointrMapWidgetConfiguration(
+  JSON.stringify({
+    isExitButtonEnabled: false,
+    isCompassEnabled: true,
+    isSearchBarEnabled: true,
+    isLevelSelectorEnabled: true,
+    isMyCarButtonEnabled: true
+  })
+);
+```
+
+**Configuration Options:**
+- `isExitButtonEnabled` (boolean): Show/hide exit button
+- `isCompassEnabled` (boolean): Show/hide compass
+- `isSearchBarEnabled` (boolean): Show/hide search bar
+- `isLevelSelectorEnabled` (boolean): Show/hide level selector
+- `isMyCarButtonEnabled` (boolean): Show/hide my car button
+- `isRouteFooterViewEnabled` (boolean): Show/hide route footer
+
+---
+
+##### `getPois(siteId)`
+
+Retrieves all Points of Interest (POIs) for a specific site.
+
+**Parameters:**
+- `siteId` (string): Site external identifier
+
+**Returns:** Promise<PTRPoi[]> - Array of POI objects
+
+**Example:**
+```typescript
+import { getPois } from 'react-native-pointr';
+
+try {
+  const pois = await getPois('site-external-id');
+  console.log(`Found ${pois.length} POIs`);
+  
+  pois.forEach(poi => {
+    console.log(`${poi.name} (${poi.typeCode})`);
+    console.log(`  Location: ${poi.position.lat}, ${poi.position.lon}`);
+    console.log(`  Level: ${poi.position.lvl}`);
+  });
+} catch (error) {
+  console.error('Failed to get POIs:', error);
+}
+```
+
+**POI Object Structure:**
+```typescript
+interface PTRPoi {
+  identifier: string;              // Internal ID
+  externalIdentifier: string;      // External ID
+  name: string;                    // Display name
+  typeCode: string;                // POI type code
+  position: PTRPosition;           // Geographic position
+  geometry: PTRGeometry;           // Shape data
+  attributes: PTRPoiAttributes;    // Metadata
+}
+
+interface PTRPosition {
+  lat: number;                     // Latitude
+  lon: number;                     // Longitude
+  isValid: boolean;                // Position validity
+  sid: string;                     // Site ID
+  bid: string;                     // Building ID
+  lvl: number;                     // Level index
+}
+
+interface PTRPoiAttributes {
+  logo?: string;                   // Logo URL
+  images?: string[];               // Image URLs
+  description?: string;            // Description text
+  extra?: Record<string, any>;     // Custom data
+  [key: string]: any;              // Other attributes
+}
+```
+
+---
+
+## Map Widget Component
+
+### `PTRMapWidget`
+
+A native UI component that displays the Pointr map.
+
+**Props:**
+- `style` (ViewStyle): Component styling
+- `onMapWidgetDidEndLoading` (function): Callback when map finishes loading with a command
+- `ref` (ref): Reference to the component for sending commands
+
+**Example:**
+```typescript
+import { requireNativeComponent } from 'react-native';
+
+interface PTRMapWidgetProps {
+  style?: any;
+  onMapWidgetDidEndLoading?: (event: NativeSyntheticEvent<any>) => void;
+}
+
+const PTRMapWidget = requireNativeComponent<PTRMapWidgetProps>('PTRMapWidget');
+
+function MyComponent() {
+  const ref = useRef(null);
+
+  const handleLoadingComplete = (event) => {
+    const { command, siteExternalIdentifier, error } = event.nativeEvent;
+    console.log('Map loaded:', command, siteExternalIdentifier, error);
+  };
+
+  return (
+    <PTRMapWidget 
+      ref={ref}
+      style={{ flex: 1 }}
+      onMapWidgetDidEndLoading={handleLoadingComplete}
+    />
+  );
+}
+```
+
+---
+
+## Command Types
+
+### `PTRCommandType`
+
+Enum of supported command types.
+
+```typescript
+enum PTRCommandType {
+  SITE = "site",
+  BUILDING = "building",
+  LEVEL = "level",
+  POI = "poi",
+  PATH = "path",
+  STATIC_PATH = "staticPath",
+  MARK_MY_CAR_LEVEL = "markMyCarForLevel",
+  MARK_MY_CAR_SITE = "markMyCarForSite",
+  SHOW_MY_CAR_SITE = "showMyCarForSite",
+  START_AND_FOCUS = "startAndFocus"
+}
+```
+
+---
+
+### Command Classes
+
+#### `PTRSiteCommand`
+
+Shows a specific site on the map.
+
+**Constructor:**
+```typescript
+new PTRSiteCommand(site: string)
+```
+
+**Parameters:**
+- `site` (string): Site external identifier
+
+**Example:**
+```typescript
+import { PTRSiteCommand } from 'react-native-pointr/src/PTRCommand';
+import { showMapWidget } from 'react-native-pointr/src/PTRMapWidgetUtils';
+
+const command = new PTRSiteCommand("site-external-id");
+showMapWidget(reactTag, command);
+```
+
+---
+
+#### `PTRBuildingCommand`
+
+Shows a specific building within a site.
+
+**Constructor:**
+```typescript
+new PTRBuildingCommand(site: string, building: string)
+```
+
+**Parameters:**
+- `site` (string): Site external identifier
+- `building` (string): Building external identifier
+
+**Example:**
+```typescript
+const command = new PTRBuildingCommand("site-id", "building-id");
+showMapWidget(reactTag, command);
+```
+
+---
+
+#### `PTRLevelCommand`
+
+Shows a specific level within a building.
+
+**Constructor:**
+```typescript
+new PTRLevelCommand(site: string, building: string, level: number)
+```
+
+**Parameters:**
+- `site` (string): Site external identifier
+- `building` (string): Building external identifier
+- `level` (number): Level index
+
+**Example:**
+```typescript
+const command = new PTRLevelCommand("site-id", "building-id", 1);
+showMapWidget(reactTag, command);
+```
+
+---
+
+#### `PTRPoiCommand`
+
+Shows and focuses on a specific POI (Point of Interest).
+
+**Constructor:**
+```typescript
+new PTRPoiCommand(site: string, poi: string)
+```
+
+**Parameters:**
+- `site` (string): Site external identifier
+- `poi` (string): POI external identifier or name
+
+**Example:**
+```typescript
+const command = new PTRPoiCommand("site-id", "Lobby");
+showMapWidget(reactTag, command);
+```
+
+---
+
+#### `PTRPathCommand`
+
+Shows navigation path from current location to a POI.
+
+**Constructor:**
+```typescript
+new PTRPathCommand(site: string, poi: string)
+```
+
+**Parameters:**
+- `site` (string): Site external identifier
+- `poi` (string): Destination POI external identifier
+
+**Example:**
+```typescript
+const command = new PTRPathCommand("site-id", "Lobby");
+showMapWidget(reactTag, command);
+```
+
+---
+
+#### `PTRStaticPathCommand`
+
+Shows a static path between two POIs.
+
+**Constructor:**
+```typescript
+new PTRStaticPathCommand(site: string, fromPoi: string, toPoi: string)
+```
+
+**Parameters:**
+- `site` (string): Site external identifier
+- `fromPoi` (string): Starting POI external identifier
+- `toPoi` (string): Destination POI external identifier
+
+**Example:**
+```typescript
+const command = new PTRStaticPathCommand("site-id", "Lobby", "Cafeteria");
+showMapWidget(reactTag, command);
+```
+
+---
+
+#### `PTRMarkMyCarLevelCommand`
+
+Marks "My Car" location on a specific level.
+
+**Constructor:**
+```typescript
+new PTRMarkMyCarLevelCommand(
+  site: string,
+  building: string,
+  level: number,
+  shouldShowPopup?: boolean,
+  animationType?: number
+)
+```
+
+**Parameters:**
+- `site` (string): Site external identifier
+- `building` (string): Building external identifier
+- `level` (number): Level index
+- `shouldShowPopup` (boolean): Show popup after marking (default: true)
+- `animationType` (number): Animation type (default: 1)
+  - `0`: None
+  - `1`: Standard
+  - `2`: Fly over
+
+**Example:**
+```typescript
+const command = new PTRMarkMyCarLevelCommand("site-id", "building-id", 1, true, 1);
+showMapWidget(reactTag, command);
+```
+
+---
+
+#### `PTRMarkMyCarSiteCommand`
+
+Marks "My Car" location at the current position within a site.
+
+**Constructor:**
+```typescript
+new PTRMarkMyCarSiteCommand(
+  site: string,
+  shouldShowPopup?: boolean,
+  animationType?: number
+)
+```
+
+**Parameters:**
+- `site` (string): Site external identifier
+- `shouldShowPopup` (boolean): Show popup after marking (default: true)
+- `animationType` (number): Animation type (default: 1)
+
+**Example:**
+```typescript
+const command = new PTRMarkMyCarSiteCommand("site-id", true, 1);
+showMapWidget(reactTag, command);
+```
+
+---
+
+#### `PTRShowMyCarSiteCommand`
+
+Shows the saved "My Car" location.
+
+**Constructor:**
+```typescript
+new PTRShowMyCarSiteCommand(
+  site: string,
+  shouldShowPopup?: boolean,
+  animationType?: number
+)
+```
+
+**Parameters:**
+- `site` (string): Site external identifier
+- `shouldShowPopup` (boolean): Show popup (default: true)
+- `animationType` (number): Animation type (default: 1)
+
+**Example:**
+```typescript
+const command = new PTRShowMyCarSiteCommand("site-id", true, 1);
+showMapWidget(reactTag, command);
+```
+
+---
+
+#### `PTRStartAndFocusCommand`
+
+Initializes the SDK and focuses on a location in a single command.
+
+**Constructor:**
+```typescript
+new PTRStartAndFocusCommand(
+  clientId: string,
+  licenseKey: string,
+  baseUrl: string,
+  logLevel: number,
+  command: PTRSiteCommand | PTRBuildingCommand | PTRLevelCommand | PTRPoiCommand
+)
+```
+
+**Parameters:**
+- `clientId` (string): Client identifier
+- `licenseKey` (string): License key
+- `baseUrl` (string): Base URL
+- `logLevel` (number): Log level (0-4)
+- `command` (PTRCommand): Focus command to execute after initialization
+
+**Example:**
+```typescript
+const focusCommand = new PTRSiteCommand("site-id");
+const command = new PTRStartAndFocusCommand(
+  "client-id",
+  "license-key",
+  "https://your-instance.pointr.cloud",
+  3,
+  focusCommand
+);
+showMapWidget(reactTag, command);
+```
+
+---
+
+## Utility Functions
+
+### `showMapWidget(reactTag, command)`
+
+Sends a command to the map widget.
+
+**Parameters:**
+- `reactTag` (number): The native view tag obtained from `findNodeHandle()`
+- `command` (PTRCommand | PTRStartAndFocusCommand): The command to execute
+
+**Example:**
+```typescript
+import { findNodeHandle } from 'react-native';
+import { showMapWidget } from 'react-native-pointr/src/PTRMapWidgetUtils';
+import { PTRSiteCommand } from 'react-native-pointr/src/PTRCommand';
+
+const showSite = () => {
+  const reactTag = findNodeHandle(mapWidgetRef.current);
+  if (reactTag) {
+    const command = new PTRSiteCommand("site-id");
+    showMapWidget(reactTag, command);
+  }
+};
+```
+
+---
+
+## Event Listeners
+
+### Position Manager Events
+
+Subscribe to position updates using the native event emitter.
+
+**Events:**
+- `OnPositionManagerCalculatedLocation`: Fired when a new position is calculated
+- `OnBuildingClicked`: Fired when a building is tapped on the map
+- `OnSiteClicked`: Fired when a site is tapped on the map
+- `OnGeofenceEvent`: Fired when a geofence enter/exit event occurs
+
+**Example:**
+```typescript
+import { NativeEventEmitter, NativeModules } from 'react-native';
+
+const PTREventEmitter = NativeModules.PTRNativePointrLibrary;
+const eventEmitter = new NativeEventEmitter(PTREventEmitter);
+
+// Listen to position updates
+const subscription = eventEmitter.addListener(
+  'OnPositionManagerCalculatedLocation',
+  (location) => {
+    console.log('New position:', location);
+  }
+);
+
+// Listen to building clicks
+const buildingSubscription = eventEmitter.addListener(
+  'OnBuildingClicked',
+  (building) => {
+    console.log('Building clicked:', building);
+  }
+);
+
+// Listen to geofence events
+const geofenceSubscription = eventEmitter.addListener(
+  'OnGeofenceEvent',
+  (geofenceEvent) => {
+    console.log('Geofence event:', geofenceEvent);
+  }
+);
+
+// Clean up
+subscription.remove();
+buildingSubscription.remove();
+geofenceSubscription.remove();
+```
+
+---
+
+### Geofence Events
+
+The `OnGeofenceEvent` is fired when the user enters or exits a geofence area. This feature requires the Pointr SDK to be running and geofence listeners are automatically registered when calling `start()`.
+
+**Event Structure:**
+```typescript
+{
+  eventType: 'enter' | 'exit',       // Event type
+  timestamp?: number,                // Unix timestamp in milliseconds (iOS only)
+  geofence: {
+    id: string,                      // Internal geofence ID
+    externalId: string,              // External geofence ID
+    name: string,                    // Geofence name
+    geofenceType: 'beacon' | 'gps',  // Type of geofence
+    position: {
+      latitude: number,              // Geofence latitude
+      longitude: number              // Geofence longitude
+    }
+  },
+  geofenceNotification?: {           // Optional notification data
+    id: string,
+    message: string,
+    timestamp: number                // Unix timestamp in milliseconds (Android)
+                                     // or milliseconds (iOS)
+  }
+}
+```
+
+**Platform Differences:**
+- iOS: Includes `timestamp` field at the root level with milliseconds since epoch
+- Android: Timestamp only available in `geofenceNotification` object
+- Both platforms support beacon and GPS geofence types
+
+**Example:**
+```typescript
+import React, { useEffect } from 'react';
+import { NativeEventEmitter, NativeModules } from 'react-native';
+
+function GeofenceMonitor() {
+  useEffect(() => {
+    const eventEmitter = new NativeEventEmitter(
+      NativeModules.PTRNativePointrLibrary
+    );
+    
+    const geofenceSubscription = eventEmitter.addListener(
+      'OnGeofenceEvent',
+      (geofenceEvent) => {
+        console.log(`Geofence ${geofenceEvent.eventType}: ${geofenceEvent.geofence.name}`);
+        console.log(`Type: ${geofenceEvent.geofence.geofenceType}`);
+        console.log(`Location: ${geofenceEvent.geofence.position.latitude}, ${geofenceEvent.geofence.position.longitude}`);
+        
+        if (geofenceEvent.geofenceNotification) {
+          console.log(`Notification: ${geofenceEvent.geofenceNotification.message}`);
+        }
+        
+        if (geofenceEvent.timestamp) {
+          console.log(`Timestamp: ${new Date(geofenceEvent.timestamp).toISOString()}`);
+        }
+      }
+    );
+    
+    return () => {
+      geofenceSubscription.remove();
+    };
+  }, []);
+  
+  return null;
+}
+```
+
+---
+
+### Map Widget Load Events
+
+The `onMapWidgetDidEndLoading` prop receives events when commands complete.
+
+**Event Object:**
+```typescript
+{
+  command: string,           // Command type that was executed
+  siteExternalIdentifier?: string,
+  buildingExternalIdentifier?: string,
+  levelIndex?: number,
+  poiExternalIdentifier?: string,
+  error?: string            // Error message if command failed
+}
+```
+
+**Example:**
+```typescript
+const handleMapWidgetDidEndLoading = (event) => {
+  const { command, siteExternalIdentifier, error } = event.nativeEvent;
+  
+  if (error) {
+    console.error(`Command ${command} failed:`, error);
+  } else {
+    console.log(`Command ${command} completed for site:`, siteExternalIdentifier);
+  }
+};
+
+<PTRMapWidget
+  ref={ref}
+  onMapWidgetDidEndLoading={handleMapWidgetDidEndLoading}
+/>
+```
+
+---
+
+## Complete Example
+
+```typescript
+import React, { useRef, useEffect } from 'react';
+import {
+  requireNativeComponent,
+  findNodeHandle,
+  NativeModules,
+  NativeEventEmitter,
+  View
+} from 'react-native';
+import { 
+  PTRSiteCommand,
+  showMapWidget,
+  getPois,
+  type PTRPoi
+} from 'react-native-pointr';
+
+const PTRMapWidget = requireNativeComponent('PTRMapWidget');
+
+function PointrMapExample() {
+  const mapRef = useRef(null);
+
+  useEffect(() => {
+    // Initialize SDK
+    NativeModules.PTRNativePointrLibrary.initialize(
+      "client-id",
+      "license-key",
+      "https://your-instance.pointr.cloud",
+      3
+    );
+
+    // Start SDK
+    NativeModules.PTRNativePointrLibrary.start((state) => {
+      console.log('Pointr state:', state);
+      
+      if (state === 'running') {
+        // Show site when SDK is running
+        const reactTag = findNodeHandle(mapRef.current);
+        if (reactTag) {
+          const command = new PTRSiteCommand("site-id");
+          showMapWidget(reactTag, command);
+        }
+        
+        // Fetch POIs for the site
+        fetchPOIs();
+      }
+    });
+
+    // Listen to position updates
+    const eventEmitter = new NativeEventEmitter(
+      NativeModules.PTRNativePointrLibrary
+    );
+    const subscription = eventEmitter.addListener(
+      'OnPositionManagerCalculatedLocation',
+      (location) => {
+        console.log('Position update:', location);
+      }
+    );
+    
+    // Listen to geofence events
+    const geofenceSubscription = eventEmitter.addListener(
+      'OnGeofenceEvent',
+      (event) => {
+        console.log(`Geofence ${event.eventType}: ${event.geofence.name}`);
+      }
+    );
+
+    return () => {
+      subscription.remove();
+      geofenceSubscription.remove();
+      NativeModules.PTRNativePointrLibrary.stop();
+    };
+  }, []);
+  
+  const fetchPOIs = async () => {
+    try {
+      const pois: PTRPoi[] = await getPois('site-id');
+      console.log(`Found ${pois.length} POIs`);
+      pois.forEach(poi => {
+        console.log(`${poi.name} at level ${poi.position.lvl}`);
+      });
+    } catch (error) {
+      console.error('Failed to fetch POIs:', error);
+    }
+  };
+
+  const handleMapLoaded = (event) => {
+    const { command, error } = event.nativeEvent;
+    console.log('Map command completed:', command, error);
+  };
+
+  return (
+    <View style={{ flex: 1 }}>
+      <PTRMapWidget
+        ref={mapRef}
+        style={{ flex: 1 }}
+        onMapWidgetDidEndLoading={handleMapLoaded}
+      />
+    </View>
+  );
+}
+
+export default PointrMapExample;
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+- **"Pointr is not initialized"**: Call `initialize()` before other methods
+- **"Pointr is not running"**: Call `start()` and wait for "running" state
+- **"Failed to find node handle for ref"**: Ensure ref is properly attached to component
+- **"No saved location"**: User hasn't marked a "My Car" location yet
+
+### Best Practices
+
+1. Always check the Pointr state before executing commands
+2. Handle errors in callbacks and event handlers
+3. Clean up event listeners when component unmounts
+4. Use `findNodeHandle()` to get the correct native view tag
+5. Initialize SDK before rendering the map widget
+6. Request permissions before starting SDK if needed
+
+---
+
+## License
+
+See the LICENSE file in the package root.