|
| 1 | +# HyperTrack Views for ReactJS |
| 2 | + |
| 3 | +A wrapper for views provided through the [HyperTrack dashboard](https://dashboard.hypertrack.com/). It allows you to integrate the same views into your own application. |
| 4 | + |
| 5 | +> Please check out the [Views Guide](https://docs.hypertrack.com/#views) for a closer look at the capabilities provided by HyperTrack Views. |
| 6 | +
|
| 7 | + |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | +- Set up a HyperTrack account and obtain your [Publishable Key from the Dashboard](https://dashboard.hypertrack.com/setup) |
| 12 | +- Integrate the HyperTrack SDK in your application ([iOS](https://github.com/hypertrack/quickstart-ios), [Android](https://github.com/hypertrack/quickstart-android), or [React Native](https://github.com/hypertrack/quickstart-react-native)) or use our sample app to send location data ([iOS](https://github.com/hypertrack/live-app-ios) or [Android](https://github.com/hypertrack/live-app-android)) |
| 13 | + |
| 14 | +## Explore sample app |
| 15 | + |
| 16 | +You can use the sample app provided to explore the capabilities and usage of this component. Please [visit this page to open the sample app](https://hypertrack.github.io/views-react/). |
| 17 | + |
| 18 | +To run the sample app on your own, follow these steps: |
| 19 | + |
| 20 | +Jump to the sample app folder: |
| 21 | + |
| 22 | +```shell |
| 23 | +cd sample |
| 24 | +``` |
| 25 | + |
| 26 | +Install all app dependencies: |
| 27 | + |
| 28 | +```shell |
| 29 | +npm i |
| 30 | + |
| 31 | +yarn |
| 32 | +``` |
| 33 | + |
| 34 | +> Note: Do not run the installation in the root folder. If that has been done before sample app dependecies were installed, NPM will use installed packages from the root node_modules, which might reason conflicts and break the build process |
| 35 | +
|
| 36 | +Run the sample app: |
| 37 | + |
| 38 | +```shell |
| 39 | +node run start |
| 40 | + |
| 41 | +yarn start |
| 42 | +``` |
| 43 | + |
| 44 | +The CLI will open up the locally hosted sample app (`http://localhost:3000/`) and should look like this: |
| 45 | + |
| 46 | + |
| 47 | +## Installation |
| 48 | + |
| 49 | +You can use either Yarn or NPM to add `hypertrack-views-react` to your project: |
| 50 | + |
| 51 | +```shell |
| 52 | +npm install --save hypertrack-views-react |
| 53 | + |
| 54 | +yarn add hypertrack-views-react |
| 55 | +``` |
| 56 | + |
| 57 | +## Usage |
| 58 | + |
| 59 | +```javascript |
| 60 | +import { LiveView } from "hypertrack-views-react"; |
| 61 | + |
| 62 | +const PUBLISHABLE_KEY = "<your_key>"; |
| 63 | + |
| 64 | +<LiveView |
| 65 | + publishableKey={PUBLISHABLE_KEY} |
| 66 | + showTooltips={true} |
| 67 | + showDeviceList={false} |
| 68 | + showDeviceCard={false} |
| 69 | + selectedDeviceId={"00112233-4455-6677-8899-AABBCCDDEEFF"} |
| 70 | + defaultLayer={"custom"} |
| 71 | + customLayerUrl={"http://mt2.google.com/vt/lyrs=s&x={x}&y={y}&z={z}"} |
| 72 | + assetsUrl={"https://abc-sdk-test-assets.s3-us-west-2.amazonaws.com/"} |
| 73 | +/>; |
| 74 | +``` |
| 75 | + |
| 76 | +## Configuration |
| 77 | + |
| 78 | +| Property | Type | Default | Description | |
| 79 | +| ---------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 80 | +| publishableKey | string | N/A | The publishable key of your account from the [Setup page on the Dashboard](https://dashboard.hypertrack.com/setup) | |
| 81 | +| showTooltips | boolean | `false` | Show the device ID right next to the location marker of a device | |
| 82 | +| showDeviceList | boolean | `true` | Show the list of all tracked devices, includes filter and search options. A click on a device will place zoom to the device location | |
| 83 | +| showDeviceCard | boolean | `true` | Show the device detail card on the single device view | |
| 84 | +| selectedDeviceId | string | `null` | ID of the device to be displayed (case sensistive). Can be obtained using the [Device API](https://docs.hypertrack.com/#api-devices). Adding this will change the view to a single device mode (including device data, activity, and more) | |
| 85 | +| defaultLayer | string | `base` | Can be either one of: [`base`](https://cloud.maptiler.com/maps/voyager/), [`street`](https://cloud.maptiler.com/maps/streets/), [`satellite`](https://cloud.maptiler.com/maps/hybrid/), or `custom`. Custom will only work if a customLayerUrl is provided. | |
| 86 | +| customLayerUrl | string | `null` | URL to a Leaflet-compatible [tiled web map](https://en.wikipedia.org/wiki/Tiled_web_map) in XYZ format. Only raster is supported and it needs to be public accessible. | |
| 87 | +| assetsUrl | string | `null` | URL to a public asset folder containig SVG files to replace default icons. The filenames need to match exactly. Missing icons will show the default versions. | |
| 88 | + |
| 89 | +> Note: The component passes along all additional properties, so you can use properties like `className`. |
| 90 | +
|
| 91 | +#### Showing a single device |
| 92 | + |
| 93 | +When provided with the `selectedDeviceId` property, the component will render a single device view as opposed to the device overview. You can find more details in the [Live device view documentation](https://docs.hypertrack.com/#live-device-view). |
| 94 | + |
| 95 | + |
| 96 | + |
| 97 | +> The device info card on the left side can be disabled by setting `showDeviceCard` to `false` |
| 98 | +
|
| 99 | +#### Adding a custom map layer |
| 100 | + |
| 101 | +With the `customLayerUrl` property, you can reference a raster tile to be added as a custom map layer. Users can select the custom view from the  button on the top right side of the view. The layer is pre-selected based on the `defaultLayer` property. After setting the `customLayerUrl`, you can set the `defaultLayer` property to `custom` to render this new tile by default. |
| 102 | + |
| 103 | +There are different ways to obtain and/or generate a custom layer. [OpenMapTiles](https://openmaptiles.org/) might be of interest. You can also generate/customize [MapBox maps and access them as raster tiles](https://docs.mapbox.com/api/maps/#raster-tiles). |
| 104 | + |
| 105 | +> Note: Please ensure you use the XYZ URL format, which looks something like this: `/tile-name/{z}/{x}/{y}.png` |
| 106 | +
|
| 107 | +Here are some sample layer tiles: |
| 108 | + |
| 109 | +| Layer | URL | Preview | |
| 110 | +| ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- | |
| 111 | +| Google Maps: Satellite | `http://mt0.google.com/vt/lyrs=s&x={x}&y={y}&z={z}` | <img src="public/satellite-map.png" alt="satellite preview" width="150"/> | |
| 112 | +| Google Maps: Roadmap/Streets | `http://mt0.google.com/vt/lyrs=m&hl=en&x={x}&y={y}&z={z}` | <img src="public/streets-map.png" alt="streets preview" width="150"/> | |
| 113 | +| Google Maps: Hybrid | `http://mt0.google.com/vt/lyrs=s,h&hl=en&x={x}&y={y}&z={z}` | <img src="public/hybrid-map.png" alt="hybrid preview" width="150"/> | |
| 114 | + |
| 115 | +#### Replacing default icons |
| 116 | + |
| 117 | +By default, the views display a set of icons to indicate status, activity, and more. You can replace each icon individually. Below is a list of all the replaceable icons. |
| 118 | + |
| 119 | +> **Original Icons**: You can use the [default icons](i) and make your modifications |
| 120 | +
|
| 121 | +| Filename | Default | Description | |
| 122 | +| -------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | |
| 123 | +| `live-direction.svg` | <img src="https://dashboard.hypertrack.com/assets/live-direction.svg" alt="live-direction.svg" width="20"/> | Dot indicated the live location and direction of a device | |
| 124 | +| `live.svg` | <img src="https://dashboard.hypertrack.com/assets/live.svg" alt="live.svg" width="20"/> | Dot indicated the live location of a device | |
| 125 | +| `offline.svg` | <img src="https://dashboard.hypertrack.com/assets/offline.svg" alt="offline.svg" width="20"/> | Dot indicated the last known location of a device | |
| 126 | +| `walk.svg` | <img src="https://dashboard.hypertrack.com/assets/walk.svg" alt="walk.svg" width="20"/> | Activity icon for walking activity | |
| 127 | +| `run.svg` | <img src="https://dashboard.hypertrack.com/assets/run.svg" alt="run.svg" width="20"/> | Activity icon for running activity | |
| 128 | +| `cycle.svg` | <img src="https://dashboard.hypertrack.com/assets/cycle.svg" alt="cycle.svg" width="20"/> | Activity icon for cycling activity | |
| 129 | +| `drive.svg` | <img src="https://dashboard.hypertrack.com/assets/drive.svg" alt="drive.svg" width="20"/> | Activity icon for driving activity | |
| 130 | +| `stop.svg` | <img src="https://dashboard.hypertrack.com/assets/stop.svg" alt="stop.svg" width="20"/> | Activity icon for stopping activity | |
| 131 | +| `unknown.svg` | <img src="https://dashboard.hypertrack.com/assets/unknown.svg" alt="unknown.svg" width="20"/> | Activity icon for unknown activity | |
| 132 | +| `inactive.svg` | <img src="https://dashboard.hypertrack.com/assets/inactive.svg" alt="inactive.svg" width="20"/> | Status icon for inactive device | |
| 133 | +| `disconnected.svg` | <img src="https://dashboard.hypertrack.com/assets/disconnected.svg" alt="disconnected.svg" width="20"/> | Status icon for disconnected device | |
| 134 | + |
| 135 | +## Versioning |
| 136 | + |
| 137 | +We use [Semantic Versioning](http://semver.org/). For the versions available, see the [tags on this repository](https://github.com/hypertrack/views-react/tags). |
| 138 | + |
| 139 | +## License |
| 140 | + |
| 141 | +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details |
0 commit comments