@situm/react-native 3.15.20 → 3.16.1-beta.0

package/src/wayfinding/components/MapView.tsx

@@ -4,6 +4,7 @@ import React, {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useMemo,
   useRef,
   useState,
 } from "react";
@@ -19,8 +20,16 @@ import type {
   WebViewErrorEvent,
   WebViewMessageEvent,
 } from "react-native-webview/lib/WebViewTypes";
+
 import SitumPlugin from "../../sdk";
 import useSitum from "../hooks";
+import {
+  selectApiDomain,
+  selectUser,
+  setError,
+  setLocationStatus,
+} from "../store";
+import { useSelector } from "../store/utils";
 import {
   type CartographySelectionOptions,
   type MapViewDirectionsOptions,
@@ -40,7 +49,6 @@ import {
 import { ErrorName } from "../types/constants";
 import { sendMessageToViewer } from "../utils";
 import ViewerMapper from "../utils/mapper";
-import { setError, setLocationStatus } from "../store";
 const SITUM_BASE_DOMAIN = "https://maps.situm.com";
 
 const NETWORK_ERROR_CODE = {
@@ -64,10 +72,14 @@ export type MapViewConfiguration = {
    */
   viewerDomain?: string;
   /**
-   * ** Required **
-   * Your Situm API key. Find your API key at your [situm profile](https://dashboard.situm.com/accounts/profile)
+   * Your Situm API key. Find your API key at your [Situm dashboard's profile](https://dashboard.situm.com/accounts/profile)
+   *
+   * Since X.YY.ZZ version this parameter is not required. Instead, you should specify your apiKey
+   * at the root of your app with `SitumProvider.apiKey` for the correct usage of the plugin.
+   * If {@param situmApiKey} is specified, `SitumProvider.apiKey` will be ignored.
    */
-  situmApiKey: string;
+  // TODO: set the version on the doc right before releasing this version.
+  situmApiKey?: string;
   /**
    * @deprecated Use `profile` instead.
    * A String identifier that allows you to remotely configure all map settings.
@@ -168,6 +180,9 @@ const MapView = React.forwardRef<MapViewRef, MapViewProps>(
     const [buildingIdentifier, setBuildingIdentifier] = useState<string>(
       configuration.buildingIdentifier,
     );
+
+    const user = useSelector(selectUser);
+    const apiDomain = useSelector(selectApiDomain);
     const {
       init,
       location,
@@ -496,6 +511,8 @@ const MapView = React.forwardRef<MapViewRef, MapViewProps>(
           webViewRef.current,
           ViewerMapper.initialConfiguration(style),
         );
+
+        _disableInternalWebViewTTSEngine();
       }
     }, [webViewRef, mapLoaded, style]);
 
@@ -556,6 +573,9 @@ const MapView = React.forwardRef<MapViewRef, MapViewProps>(
         case "viewer.navigation.stopped":
           SitumPlugin.updateNavigationState(eventParsed.payload);
           break;
+        case "ui.speak_aloud_text":
+          SitumPlugin.speakAloudText(eventParsed.payload);
+          break;
         default:
           break;
       }
@@ -580,8 +600,31 @@ const MapView = React.forwardRef<MapViewRef, MapViewProps>(
       return true;
     };
 
-    const _effectiveProfile = () => {
-      let effectiveProfile = configuration.profile;
+    const _effectiveApiKey = useMemo(() => {
+      const internalApiKey = user?.apiKey;
+      const configApiKey = configuration.situmApiKey;
+
+      if (!configApiKey && !internalApiKey) {
+        console.error(
+          "No apiKey was specified. Make sure to be authenticated either by specifying the SitumProvider.apiKey or by specifying the MapViewConfiguration.situmApiKey.",
+        );
+      }
+
+      return configApiKey ?? internalApiKey;
+    }, [user?.apiKey, configuration.situmApiKey]);
+
+    const _effectiveProfile = useMemo(() => {
+      let effectiveProfile: any = "";
+
+      if (
+        configuration.profile?.length === 0 &&
+        configuration.remoteIdentifier?.length === 0
+      ) {
+        effectiveProfile = "";
+      }
+
+      effectiveProfile = configuration.profile;
+
       if (
         configuration.remoteIdentifier &&
         configuration.remoteIdentifier.length > 0
@@ -589,26 +632,52 @@ const MapView = React.forwardRef<MapViewRef, MapViewProps>(
         console.warn(
           'Situm> MapView> [!] "remoteIdentifier" is deprecated. Use "profile" instead.',
         );
-        if (!configuration.profile || configuration.profile.length == 0) {
+        if (!configuration.profile || configuration.profile.length === 0) {
           effectiveProfile = configuration.remoteIdentifier;
         }
       }
+
       return effectiveProfile;
+    }, [configuration.profile, configuration.remoteIdentifier]);
+
+    const _effectiveApiDomain = useMemo(() => {
+      let finalApiDomain = configuration.apiDomain ?? apiDomain;
+
+      if (!finalApiDomain) return "";
+
+      finalApiDomain = finalApiDomain.replace("https://", "");
+      finalApiDomain = finalApiDomain.replace("/", "");
+
+      return `&domain=${finalApiDomain}`;
+    }, [apiDomain, configuration.apiDomain]);
+
+    const _effectiveBuildingId = useMemo(() => {
+      let finalBuildingIdentifier = "";
+      const buildingId = configuration.buildingIdentifier;
+
+      if (buildingId && buildingId.length > 0) {
+        finalBuildingIdentifier = `&buildingid=${buildingId}`;
+      }
+
+      return finalBuildingIdentifier;
+    }, [configuration.buildingIdentifier]);
+
+    const _disableInternalWebViewTTSEngine = () => {
+      sendMessageToViewer(
+        webViewRef.current,
+        ViewerMapper.setConfigItems([
+          { key: "internal.tts.engine", value: "mobile" },
+        ]),
+      );
     };
 
     return (
       <WebView
         ref={webViewRef}
         source={{
-          uri: `${configuration.viewerDomain || SITUM_BASE_DOMAIN}/${
-            _effectiveProfile() ? `id/${_effectiveProfile()}` : ""
-          }?&apikey=${
-            configuration.situmApiKey
-          }&wl=true&global=true&mode=embed${
-            configuration.buildingIdentifier
-              ? `&buildingid=${configuration.buildingIdentifier}`
-              : ""
-          }&show=rts`,
+          uri: `${configuration.viewerDomain || SITUM_BASE_DOMAIN}/${_effectiveProfile}?apikey=${
+            _effectiveApiKey
+          }${_effectiveApiDomain}${_effectiveBuildingId}&mode=embed`,
         }}
         style={StyleSheet.flatten([viewerStyles.webview, style])}
         limitsNavigationsToAppBoundDomains={true}

package/src/wayfinding/hooks/index.ts

@@ -1,3 +1,4 @@
+/* eslint-disable no-case-declarations */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { useContext, useState } from "react";
 
@@ -66,15 +67,15 @@ export const useSitumInternal = () => {
       (internalCall: InternalCall) => {
         switch (internalCall.type) {
           case InternalCallType.LOCATION:
-            let location = internalCall.get<Location>();
+            const receivedLocation = internalCall.get<Location>();
             dispatch(
               setLocation({
-                ...location,
+                ...receivedLocation,
               }),
             );
             break;
           case InternalCallType.LOCATION_STATUS:
-            let statusName = internalCall.get<string>();
+            const statusName = internalCall.get<string>();
             if (statusName in LocationStatusName) {
               dispatch(setLocationStatus(statusName));
             }
@@ -84,8 +85,8 @@ export const useSitumInternal = () => {
             dispatch(resetLocation());
             break;
           case InternalCallType.LOCATION_ERROR:
-            let error = internalCall.get<Error>();
-            dispatch(setError(error));
+            const receivedError = internalCall.get<Error>();
+            dispatch(setError(receivedError));
             break;
           case InternalCallType.NAVIGATION_START:
             dispatch(
@@ -104,7 +105,7 @@ export const useSitumInternal = () => {
             );
             break;
           case InternalCallType.NAVIGATION_PROGRESS:
-            let progress = internalCall.get<NavigationProgress>();
+            const progress = internalCall.get<NavigationProgress>();
             dispatch(
               setNavigation({
                 currentIndication: progress?.currentIndication,

package/src/wayfinding/store/index.tsx

@@ -1,6 +1,13 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import React, { createContext, type MutableRefObject, useReducer } from "react";
+import React, {
+  createContext,
+  type MutableRefObject,
+  useEffect,
+  useReducer,
+  useState,
+} from "react";
 
+import SitumPlugin from "../../sdk";
 import {
   type Building,
   type Directions,
@@ -22,6 +29,7 @@ export interface State {
   webViewRef: MutableRefObject<undefined> | undefined;
   sdkInitialized: boolean;
   user?: User;
+  apiDomain?: string;
   location?: Location;
   locationStatus?: LocationStatusName;
   buildings: Building[] | null;
@@ -38,6 +46,7 @@ export const initialState: State = {
   webViewRef: undefined,
   sdkInitialized: false,
   user: undefined,
+  apiDomain: undefined,
   location: undefined,
   locationStatus: undefined,
   buildings: null,
@@ -101,7 +110,7 @@ const store = createStore<State>({
     },
     setBuildingIdentifier: (
       state: State,
-      payload: State["buildingIdentifier"]
+      payload: State["buildingIdentifier"],
     ) => {
       return { ...state, buildingIdentifier: payload };
     },
@@ -120,6 +129,10 @@ export const selectUser = (state: State) => {
   return state.user;
 };
 
+export const selectApiDomain = (state: State) => {
+  return state.apiDomain;
+};
+
 export const selectLocation = (state: State) => {
   return state.location;
 };
@@ -181,7 +194,7 @@ export const {
  * Context specifically to store the only instance of our hook.
  */
 export const UseSitumContext = createContext<{ useSitum: any } | undefined>(
-  undefined
+  undefined,
 );
 
 const UseSitumProvider: React.FC<{ children: React.ReactNode }> = ({
@@ -199,19 +212,56 @@ const UseSitumProvider: React.FC<{ children: React.ReactNode }> = ({
 };
 
 /**
- * Main context of the application, stores the plugins' state.
+ * Main context of the application, stores the plugin's state.
  */
 const SitumProvider: React.FC<
   React.PropsWithChildren<{
+    /**
+     * Your Situm email account.
+     */
     email?: string;
-    apiKey?: string;
+    /**
+     * Your Situm API key. Find your API key at your [Situm dashboard's profile](https://dashboard.situm.com/accounts/profile)
+     *
+     * When specifying a valid situm API key in this parameter, you won't need to call later on the `SitumPlugin.init()` & `SitumPlugin.setApiKey()` methods,
+     * and also you won't need to specify `MapViewConfiguration.situmApiKey` when configuring your MapView.
+     */
+    apiKey: string;
+    /**
+     * Set the API domain that will be used by the native SDKs and MapView to obtain the situm's data.
+     *
+     * When specifying a valid domain in this parameter, you won't need to call later on the `SitumPlugin.setDashboardURL()` method,
+     * and also you won't need to specify `MapViewConfiguration.apiDomain` when configuring your MapView.
+     *
+     * Defaults to "api.situm.com"
+     */
+    apiDomain?: string;
   }>
-> = ({ email, apiKey, children }) => {
+> = ({ email, apiKey, apiDomain, children }) => {
   const [state, dispatch] = useReducer(store.reducer, {
     ...store.initialState,
     user: { email, apiKey },
+    apiDomain: apiDomain,
   });
 
+  const [isInitialized, setIsInitialized] = useState(false);
+
+  useEffect(() => {
+    try {
+      SitumPlugin.init();
+      apiDomain && SitumPlugin.setDashboardURL(apiDomain);
+      if (!apiKey) {
+        throw new Error(
+          "Please specify SitumProvider.apiKey to be able to successfully use SitumPlugin and MapView.",
+        );
+      }
+      SitumPlugin.setApiKey(apiKey);
+    } catch (e) {
+      console.error(`SitumProvider > Could not initialize ${e}`);
+    }
+    setIsInitialized(true);
+  }, [apiKey, apiDomain]);
+
   return (
     <SitumContext.Provider
       value={{
@@ -219,7 +269,14 @@ const SitumProvider: React.FC<
         dispatch,
       }}
     >
-      <UseSitumProvider>{children}</UseSitumProvider>
+      {/**
+       * Make sure to execute first SitumProvider's initialization & authentication useEffect(),
+       * before letting children components rendering MapView or calling SitumPlugin methods.
+       *
+       * If we directly let the `children` render, the children's useEffect() will execute before SitumProvider's useEffect().
+       * This causes a crash when the children wants to access SitumPlugin before it is initialized.
+       */}
+      <UseSitumProvider>{isInitialized ? children : <></>}</UseSitumProvider>
     </SitumContext.Provider>
   );
 };

package/src/wayfinding/types/index.ts

@@ -1,6 +1,5 @@
-import { AccessibilityMode } from "../../sdk/types/constants";
-
 import type { DirectionsRequest, Point } from "../../sdk/types";
+import { AccessibilityMode } from "../../sdk/types/constants";
 export type { MapViewConfiguration, MapViewProps } from "../components/MapView";
 import { ErrorName } from "./constants";
 
@@ -33,7 +32,7 @@ export interface MapViewRef {
    */
   selectFloor: (
     floorIdentifier: number,
-    options?: CartographySelectionOptions
+    options?: CartographySelectionOptions,
   ) => void;
   /**
    * Define the {@link MapViewDirectionsOptions} that the routes calculated by the MapView will use.
@@ -221,3 +220,15 @@ export interface SearchFilter {
 export interface CartographySelectionOptions {
   fitCamera?: boolean;
 }
+
+export interface ViewerConfigItem {
+  /**
+   * A dot notation key referring to all the keys related to internal ConfigState of the viewer.
+   */
+  key: string;
+
+  /**
+   * The value that we want to set for the corresponding ConfigState key.
+   */
+  value: any;
+}

package/src/wayfinding/utils/index.ts

@@ -1,6 +1,9 @@
 import WebView from "react-native-webview";
 
-export const sendMessageToViewer = (viewer: WebView | null, message: string) => {
+export const sendMessageToViewer = (
+  viewer: WebView | null,
+  message: string,
+) => {
   if (!viewer) return;
   viewer.injectJavaScript(`window.postMessage(${message})`);
 };

package/src/wayfinding/utils/mapper.ts

@@ -18,6 +18,7 @@ import type {
   Navigation,
   OnNavigationResult,
   SearchFilter,
+  ViewerConfigItem,
 } from "../types";
 
 export const createPoint = (payload: any): Point => {
@@ -72,8 +73,8 @@ export const createNavigationRequest = (payload: any): NavigationRequest => {
 
   return Object.fromEntries(
     Object.entries(navigationRequest || {}).filter(
-      ([_, value]) => value !== undefined
-    )
+      ([_, value]) => value !== undefined,
+    ),
   );
 };
 
@@ -113,7 +114,7 @@ const ViewerMapper = {
   },
   selectFloor: (
     floorIdentifier: number,
-    options?: CartographySelectionOptions
+    options?: CartographySelectionOptions,
   ) => {
     return mapperWrapper(`cartography.select_floor`, {
       identifier: floorIdentifier,
@@ -213,6 +214,9 @@ const ViewerMapper = {
       poiCategoryIdentifier: searchFilter.poiCategoryIdentifier,
     });
   },
+  setConfigItems: (configItems: ViewerConfigItem[]) => {
+    return mapperWrapper(`app.set_config_item`, configItems);
+  },
 };
 
 export default ViewerMapper;