# react-native-ctp-odp

React Native ODP Components

## Installation

```sh
npm install react-native-ctp-odp
```

## Usage

1. Install the required packages

```sh
npm install react-native-ctp-odp
npm install react-native-webview
```

2. Import JMapView object (and types)

```js
import {
  // types
  MAP_TAP_EVENT_TYPE,
  // Objects
  JMapView,
  Utilities,
} from 'react-native-ctp-odp';
```

3. Add a JMapView

```js
const mapRef = useRef<MAP_VIEW_REFERENCE_TYPE>(null);

<JMapView
    style={{ width: "100%", height: "100%" }}
    ref={mapRef}
    onMapMessage={{
        callbacks...
    }}
/>
```

## JMapView Methods

Map methods can be called by adding a refence to the JMapView object. All of the available methods should be visible and typed through typescript.

```js
const mapRef = useRef < MAP_VIEW_REFERENCE_TYPE > null;
<JMapView ref={mapRef} />;

if (mapRef.current) mapRef.current.clearWayfindingPath();
```

- setMapVenue(credentials: MAP_CREDENTIALS, mapOptions?: MAP_OPTIONS)
  - Initialize map with credentials and options. The credentials needs to include a venue id.
- setMapOptions(options: MAP_OPTIONS)
  - Set map options
- centerMapOnUser: (orientation: number, zoom?: number, animationDuration?: number)
  - Center map on map user and set map orientation, zoom, and animationDuration
- setFollowBlueDot: (enabled: boolean, rotate: boolean = false, interval: number = 500)
  - Tell map to continually center on blue dot. Options for a rotation angle and an update interval (in milliseconds)
- setUserPosition: (lat: number, long: number, heading: number)
  - Update blue dot location on map, by lat/long
- setUserPositionXY: (x: number, y: number, heading: number)
  - Update blue dot location on map, by x/y
- clearWayfindingPath: ()
  - lear drawn wayfinding path
- wayfindToWaypoint: (waypointId: number)
  - Generate path and directions from blue dot to waypoint. Waypoint IDs can be retrieved from the onSearchDestinationsGenerated or onDestinationSelected callbacks
- wayfindBetweenWaypoints: (originId: number, destinationId: number)
  - Generate a path between two waypoints, by id. Waypoint IDs can be retrieved from the onSearchDestinationsGenerated or onDestinationSelected callbacks
- drawNavigationPath: (pathId: string, shouldFocus?: boolean, style?: JIBESTREAM_STYLE = {stroke: '#ffc956', strokeWidth: 3}, originIcon?: Image, destinationIcon?: Image)
  - Render navigation path with set style. Requires pathId, which can be retrieved from a path, returned by the onNavigationPathGenerated callback.
- styleUnitsForDestination: (destinationId: number, style?: JIBESTREAM_STYLE)
  - Set unit style for destination ID. Used with layer interaction.

## JMapView Callbacks

Map callback methods are specified through the onMapMessage property.

```js
<JMapView
  onMapMessage={{
    onMapTappedGeneric: (event: MAP_TAP_EVENT) => {
      console.log(event.localPoint);
    },
  }}
/>;

if (mapRef.current) mapRef.current.clearWayfindingPath();
```

- onDestinationSelected: (destination JIBESTREAM_DESTINATION)
  - Triggered when a destination is selected within the in-app search bar. Returns a JIBESTREAM_DESTINATION object
- onNavigationPathGenerated: ({pathId: string, instructions: INSTRUCTION[], start: JIBESTREAM_WAYPOINT, end: JIBESTREAM_WAYPOINT, jibestreamPath: JIBESTREAM_PATH[], path: GEOJSON_PATH})
  - Triggered when a navigation path and instructions are generated by the GUI, most likely from the wayfindToWaypoint or wayfindBetweenWaypoints methods. Returns a pathID (used to render path), instructions (used to display to user), start point, end point, and path object
- onUserPositionUpdated: (userPosition: number[])
  - Triggered when the blue dot location is updated on the map. Used to hold the user location in the front end. This is not the same as saving the ODP output, as snapToPath and snapToGrid alter the user/blue dot's location. Returns the x/y location of the blue dot
- onSearchDestinationsGenerated: (destinations: JIBESTREAM_DESTINATION_SET[])
  - Triggered when the map generates a set of search destinations, this is triggered on map initialization (setMapVenue). Returns a list of destination objects, with corresponding waypoints.
- onError: (errorMsg: string)
  - Receive error messages from package
- onMapTappedGeneric: (event: MAP_TAP_EVENT)
  - Triggered when the user taps the map (jibestream map enableGenericTapHandler). Returns an event object which contains the clicked location (and other metadata)
- onGeofencesChanged: (entered: boolean, geofences: JIBESTREAM_GEOFENCE_TYPE[])
  - Triggered when the user position moves into or out of a geofence, entered indicates if the user entered or exited, the event contains information about the geofence that was entered.
- onRerouteNavigationPathGenerated: ({pathId: string, instructions: INSTRUCTION[], start: JIBESTREAM_WAYPOINT, end: JIBESTREAM_WAYPOINT, jibestreamPath: JIBESTREAM_PATH[], path: GEOJSON_PATH})
  - Triggered when the user strays more than the mapOptions.navigation.autoRerouteThreshold distance (in meters) from the path. When this is triggered, know that the drawNagivationPath method is also internally triggered.

## JOdpViewModule Methods

The JODPView module can be used to get a users location from the navigation beacons. This module can be initialized as shown below:

```js
const odpRef = useRef < ODP_VIEW_REFERENCE_TYPE > null;
<JOdpViewModule ref={odpRef} />;

if (odpRef.current) odpRef.current.startOdp('key', 'host');
```

- startOdp(key: string, host: string)
  - Start ODP module. Requires a license key and host address. If not started, no events will be emitted.
- stopOdp()
  - Stop ODP Module. After this is called, no more events will be emitted.
- uploadLogs()
  - Upload ODP Logs to CXApp Team

## JOdpViewModule Callbacks

The JOdpView module can be used to get a users location from the navigation beacons. This module can be subscribed to as shown below:

```js
<JOdpViewModule
  ref={odpRef}
  onOdpEvent={{
    onReady: (event) => console.log('ODP onReady', event),
    onKeyValidation: (event) => console.log('ODP onKeyValidation', event),
    onNavigationUpdate: (event) => console.log('ODP onNavigationUpdate', event),
    onFacilityUpdate: (event) => console.log('ODP onFacilityUpdate', event),
  }}
/>
```

- onReady(event: ODP_ON_READY_TYPE), this callback function will be called when the ODP module is ready to operate
- onKeyValidation(event: ODP_KEY_VALIDATION_TYPE), this callback function will be called when the ODP module has properly authenticated with the mapping server. If this function is not called, an invalid key or host has likely been passed to the client.
- onNavigationUpdate(event: ODP_ON_NAVIGATION_UPDATE_TYPE), this callback is called when the ODP has computed a new user position within the app.
- onFacilityUpdate(event: ODP_ON_FACILITY_UPDATE), this callback is called when the ODP has activated due to arrival at a new facility.

## Utilities Object

The Utilities object, imported alongside the JMapView, enalbles proessing of instructions.

- preProcessPath(path: JIBESTREAM_PATH[], instructions: INSTRUCTION[])
  - Add start and end points to instructions from path. This will enable easy generation of current instruction and distance remaining
- getCurrentInstruction(userLocation: number[], instructions: INSTRUCTION[])
  - Get current instruction from user location and processed instructions.

4. Implement callbacks and call methods from the map reference!

See [JMapView Methods](#jmapview-methods) and [JMapView Callbacks](#jmapview-callbacks) sections

## Contributing

See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

## License

MIT

---

Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
