react-native-pointr 9.6.0 → 9.7.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.7.0] - 2026-04-02
+
+### Changed
+- Mobile SDK 9.7.0 integration.
+
+
 ## [9.6.0] - 2026-03-26
 
 ### Changed

package/README.md

@@ -153,243 +153,87 @@ Then run `npm install` or `yarn install` to install the 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 the package exports and render the map widget:
 
 ```typescript
-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';
+import { PTRMapWidget, PTRSiteCommand } from 'react-native-pointr';
+import type { PTRConfiguration, PTRMapWidgetConfiguration } from 'react-native-pointr';
 ```
 
-Define the `PTRMapWidget` component interface and create the component using `requireNativeComponent`:
+The simplest integration passes `sdkConfig`, `mapWidgetConfig`, and `command` as props directly — the widget handles initialization automatically:
 
-```typescript
-interface PTRMapWidgetProps {
-  style?: any;
-  onMapWidgetDidEndLoading?: (event: NativeSyntheticEvent<any>) => void;
-}
-
-const PTRMapWidget = requireNativeComponent<PTRMapWidgetProps>('PTRMapWidget');
-```
+```tsx
+const SDK_CONFIG: PTRConfiguration = {
+  clientId: '<CLIENT_ID>',
+  licenseKey: '<LICENSE_KEY>',
+  baseUrl: 'https://<your-instance>.pointr.cloud',
+};
 
-Initialize and start Pointr instance before doing any operation:
+const MAP_CONFIG: PTRMapWidgetConfiguration = {
+  isLevelSelectorEnabled: true,
+  isExitButtonEnabled: false,
+};
 
-```typescript
-// 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);
+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)}
+    />
+  );
+}
 ```
 
-Implement the map widget in your React Native component:
-
-```typescript
-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");
-    }
-  };
+To manage the SDK lifecycle and position updates at the app level, use the `usePointrSdk` hook:
 
-  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");
-    }
-  };
+```tsx
+import { usePointrSdk, usePointrPosition } from 'react-native-pointr';
 
-  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");
-    }
-  };
+function App() {
+  const { sdk, isStarted, state } = usePointrSdk(SDK_CONFIG);
 
-  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 position = usePointrPosition(isStarted);
 
-  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");
-    }
+  const checkPosition = async () => {
+    const loc = await sdk.getCurrentLocation();
+    if (loc) console.log(loc.latitude, loc.longitude, loc.levelIndex);
   };
-
-  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:
+```typescript
+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
 
-- **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
+```typescript
+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 more information about the available functionality, check the [API documentation](https://docs.pointr.tech/docs/8.x/Developer%20Portal/API%20Reference/api%20ref-mobile/).
+For the complete API see the [API Reference](./API_REFERENCE.md).
 
 ## 5. Run the App
 
@@ -408,3 +252,18 @@ After completing the setup, start your app by running:
     ```
 
 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](https://docs.pointr.tech/docs/8.x/Developer%20Portal/API%20Reference/api%20ref-mobile/).
+## 6. Run the Example App
+
+To explore the included demo app:
+
+```bash
+cd example/pointr_rn_demo
+npm install
+
+# iOS
+cd ios && pod install && cd ..
+npm run ios
+
+# Android
+npm run android
+```

package/android/build.gradle

@@ -93,7 +93,7 @@ dependencies {
   //noinspection GradleDynamicVersion
   implementation "com.facebook.react:react-android:0.82.1"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-  implementation("com.pointrlabs:pointr:9.6.0")
+  implementation("com.pointrlabs:pointr:9.7.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'

package/android/src/main/java/com/pointr/PTRMapWidgetManager.kt

@@ -12,6 +12,7 @@ import com.facebook.react.bridge.WritableMap
 import com.facebook.react.bridge.WritableNativeMap
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.ViewGroupManager
+import com.facebook.react.uimanager.annotations.ReactProp
 import com.facebook.react.uimanager.events.RCTEventEmitter
 import com.pointrlabs.core.management.DataManager
 import com.pointrlabs.core.management.Pointr
@@ -57,6 +58,151 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
 
     private var ptrMapWidgetFragment: PTRMapWidgetFragment? = null
 
+    // Declarative prop support -----------------------------------------------
+    // When a `command` JSON prop is passed on <PTRMapWidget />, the manager
+    // auto-executes it once the view is attached rather than requiring a JS
+    // imperative command dispatch.
+    //
+    // JSON shape: { "type": "site"|"building"|"level"|"poi"|"path"|"staticPath"|"staticWayfinding",
+    //               "site": String, "building"?: String, "level"?: Int,
+    //               "poi"?: String, "fromPoi"?: String, "toPoi"?: String,
+    //               "sourcePoi"?: String, "destinationPoi"?: String }
+    private var pendingCommandJson: String? = null
+    private var pendingSdkConfigJson: String? = null
+    private var commandDidExecute = false
+    // Reset per view instance in createViewInstance so re-navigation works.
+    private var commandTriggered = false
+
+    @ReactProp(name = "command")
+    fun setCommand(view: FrameLayout, commandJson: String?) {
+        pendingCommandJson = commandJson
+        commandDidExecute = false
+    }
+
+    @ReactProp(name = "sdkConfig")
+    fun setSdkConfig(view: FrameLayout, configJson: String?) {
+        pendingSdkConfigJson = configJson
+        applySdkConfigIfNeeded()
+    }
+
+    @ReactProp(name = "mapWidgetConfig")
+    fun setMapWidgetConfig(view: FrameLayout, configJson: String?) {
+        if (configJson == null) return
+        try {
+            val obj = org.json.JSONObject(configJson)
+            val cfg = PointrModule.mapWidgetConfiguration
+            cfg::class.members.filterIsInstance<kotlin.reflect.KMutableProperty1<*, *>>().forEach { prop ->
+                val jsonKey = if (prop.name == "isBuildingLevelSelectorEnabled") "isLevelSelectorEnabled" else prop.name
+                if (!obj.has(jsonKey)) return@forEach
+                try {
+                    val value = obj.getBoolean(jsonKey)
+                    @Suppress("UNCHECKED_CAST")
+                    (prop as kotlin.reflect.KMutableProperty1<Any, Boolean>).set(cfg, value)
+                } catch (_: Exception) {}
+            }
+        } catch (e: Exception) {
+            Log.e(name, "mapWidgetConfig parse error: ${e.message}")
+        }
+    }
+
+    private fun applySdkConfigIfNeeded() {
+        val json = pendingSdkConfigJson ?: return
+        try {
+            val obj = org.json.JSONObject(json)
+            val clientId = obj.optString("clientId")
+            val licenseKey = obj.optString("licenseKey")
+            val baseUrl = obj.optString("baseUrl")
+            if (clientId.isNotEmpty() && licenseKey.isNotEmpty() && baseUrl.isNotEmpty()) {
+                val params = PTRParams(clientId, licenseKey, baseUrl)
+                val logLevel = obj.optInt("logLevel", Plog.LogLevel.ERROR.ordinal)
+                params.logLevel = try {
+                    Plog.LogLevel.entries[logLevel]
+                } catch (_: Exception) {
+                    Plog.LogLevel.ERROR
+                }
+                PointrModule.mapWidgetConfiguration.sdkParams = params
+                // Initialize the Pointr SDK if it has not been initialized yet
+                // (covers the case where sdkConfig is used without a prior pointrSdk.initialize() call).
+                if (Pointr.getPointr() == null) {
+                    Pointr.with(reactContext, params)
+                }
+            }
+        } catch (e: Exception) {
+            Log.e(name, "sdkConfig parse error: ${e.message}")
+        }
+    }
+
+    private fun executePendingCommandIfNeeded() {
+        val json = pendingCommandJson ?: return
+        if (commandDidExecute) return
+        commandDidExecute = true
+        Thread {
+            // Block on background thread until Pointr is running (semaphore wait).
+            // If Pointr never reaches RUNNING (e.g. SDK not initialized), skip entirely
+            // so we never block the main thread inside getMapWidgetFragment.
+            if (!waitForPointrToRun()) {
+                Log.e(name, "Pointr did not reach RUNNING state — skipping declarative command")
+                return@Thread
+            }
+            // Fragment transactions must happen on the main thread.
+            android.os.Handler(android.os.Looper.getMainLooper()).post {
+                // Guard: activity may be null if the user navigated away while we were waiting.
+                if (reactContext.currentActivity == null) {
+                    Log.e(name, "No current activity — cannot execute declarative map command")
+                    return@post
+                }
+                try {
+                    val obj = org.json.JSONObject(json)
+                    val type = obj.optString("type")
+                    val site = obj.optString("site", "")
+                    val building = obj.optString("building", "")
+                    val level = obj.optInt("level", 0)
+                    val poi = obj.optString("poi", "")
+                    val fromPoi = obj.optString("fromPoi", "")
+                    val toPoi = obj.optString("toPoi", "")
+                    val sourcePoi = obj.optString("sourcePoi", "")
+                    val destinationPoi = obj.optString("destinationPoi", "")
+
+                    val args = com.facebook.react.bridge.Arguments.createArray()
+                    when (type) {
+                        PTRMapWidgetCommandType.SITE -> {
+                            args.pushString(site)
+                            executeCommand(PTRMapWidgetCommandType.SITE, args)
+                        }
+                        PTRMapWidgetCommandType.BUILDING -> {
+                            args.pushString(site); args.pushString(building)
+                            executeCommand(PTRMapWidgetCommandType.BUILDING, args)
+                        }
+                        PTRMapWidgetCommandType.LEVEL -> {
+                            args.pushString(site); args.pushString(building); args.pushInt(level)
+                            executeCommand(PTRMapWidgetCommandType.LEVEL, args)
+                        }
+                        PTRMapWidgetCommandType.POI -> {
+                            args.pushString(site); args.pushString(poi)
+                            executeCommand(PTRMapWidgetCommandType.POI, args)
+                        }
+                        PTRMapWidgetCommandType.PATH -> {
+                            args.pushString(site); args.pushString(poi)
+                            executeCommand(PTRMapWidgetCommandType.PATH, args)
+                        }
+                        PTRMapWidgetCommandType.STATIC_PATH -> {
+                            args.pushString(site); args.pushString(fromPoi); args.pushString(toPoi)
+                            executeCommand(PTRMapWidgetCommandType.STATIC_PATH, args)
+                        }
+                        PTRMapWidgetCommandType.STATIC_WAYFINDING -> {
+                            args.pushString(site); args.pushString(sourcePoi); args.pushString(destinationPoi)
+                            executeCommand(PTRMapWidgetCommandType.STATIC_WAYFINDING, args)
+                        }
+                        else -> Log.w(name, "Unknown command type in command prop: $type")
+                    }
+                } catch (e: Exception) {
+                    Log.e(name, "Failed to execute command prop: ${e.message}")
+                }
+            }
+        }.start()
+    }
+    // ------------------------------------------------------------------------
+
     private fun getMapWidgetFragment(action: PTRMapWidgetAction): PTRMapWidgetFragment {
         Log.i(name, "Creating map widget fragment with action: $action")
         waitForPointrToRun()
@@ -78,6 +224,11 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
      */
     override fun createViewInstance(reactContext: ThemedReactContext): FrameLayout {
         frameLayout = FrameLayout(reactContext)
+        commandDidExecute = false
+        commandTriggered = false  // reset so re-navigation triggers the command again
+        // Start the frame loop immediately so the declarative command prop can
+        // fire once the view has been measured and laid out by React Native.
+        Choreographer.getInstance().postFrameCallback(frameCallback)
         return frameLayout
     }
 
@@ -679,6 +830,11 @@ class PTRMapWidgetManager(private val reactContext: ReactApplicationContext) :
                 frameLayout.bottom
             )
             frameLayout.viewTreeObserver.dispatchOnGlobalLayout()
+            // Execute a declarative command prop once the view has non-zero dimensions.
+            if (!commandTriggered && frameLayout.width > 0 && frameLayout.height > 0) {
+                commandTriggered = true
+                executePendingCommandIfNeeded()
+            }
             Choreographer.getInstance().postFrameCallback(this)
         }
     }