# HyperTrack Docs > Guides and API reference for HyperTrack — location intelligence for shift work. ## Guides - [Android SDK FAQ](https://www.hypertrack.com/docs/android-sdk-faq.md) - [Nearby Search](https://www.hypertrack.com/docs/assign-orders-to-nearby-drivers.md) - [Backfill Last-minute Cancellations](https://www.hypertrack.com/docs/backfill-last-minute-cancellations.md) - [Basic Visibility](https://www.hypertrack.com/docs/basic-visibility.md): Track orders using Geotags or Geofences to get basic visibility - [Location timesheet for payout & invoicing](https://www.hypertrack.com/docs/billing-payouts.md) - [Breaks & Overtime](https://www.hypertrack.com/docs/breaks-overtime.md) - [Build Your App](https://www.hypertrack.com/docs/build-your-app.md) - [Clock-in / Clock-out](https://www.hypertrack.com/docs/clock-in-clock-out.md) - [Distribute Orders App](https://www.hypertrack.com/docs/distribute-orders-app.md) - [Distribute Visits App](https://www.hypertrack.com/docs/distribute-visits-app.md) - [Worker App Setup](https://www.hypertrack.com/docs/driver-app-setup.md) - [Embed Views into Ops Dashboard](https://www.hypertrack.com/docs/embed-views-into-ops-dashboard.md) - [Facility Manager View](https://www.hypertrack.com/docs/facility-manager-view.md) - [FAQ](https://www.hypertrack.com/docs/faq.md) - [Getting Google Service account key for Firebase](https://www.hypertrack.com/docs/fcm-service-account.md) - [Clock-in/Clock-out Geotags](https://www.hypertrack.com/docs/geofenced-clock-in-out.md) - [Track Orders using Geofences](https://www.hypertrack.com/docs/guidestrack-visits-to-geofences-1.md) - [HubSpot-HyperTrack integration](https://www.hypertrack.com/docs/hubspot-hypertrack-integration.md): Schedule, track, and improve performance and efficiency of your fleet with workflow automations. - [HyperTrack SDK FAQ](https://www.hypertrack.com/docs/hypertrack-sdk-faq.md) - [HyperTrack Tracking Start Flow: Technical Deep Dive](https://www.hypertrack.com/docs/hypertrack-tracking-start-flow-technical-deep-dive.md) - [Android](https://www.hypertrack.com/docs/install-sdk-android.md) - [Cordova](https://www.hypertrack.com/docs/install-sdk-cordova.md) - [Expo](https://www.hypertrack.com/docs/install-sdk-expo.md) - [Flutter](https://www.hypertrack.com/docs/install-sdk-flutter.md) - [Ionic Capacitor](https://www.hypertrack.com/docs/install-sdk-ionic-capacitor.md) - [iOS](https://www.hypertrack.com/docs/install-sdk-ios.md) - [.NET MAUI](https://www.hypertrack.com/docs/install-sdk-maui.md) - [React Native](https://www.hypertrack.com/docs/install-sdk-react-native.md) - [Install SDK](https://www.hypertrack.com/docs/install-sdk.md) - [Instant Pay](https://www.hypertrack.com/docs/instant-pay.md) - [Introduction](https://www.hypertrack.com/docs/introduction.md): Location AI for Shift Work Automation - [iOS SDK FAQ](https://www.hypertrack.com/docs/ios-sdk-faq.md) - [List of Outages](https://www.hypertrack.com/docs/list-of-outages.md) - [Locate the Worker](https://www.hypertrack.com/docs/locate.md) - [Location Timeline](https://www.hypertrack.com/docs/location-timeline.md) - [Manage Tracking Permissions and Outages](https://www.hypertrack.com/docs/manage-tracking-permissions.md) - [Manage Worker Availability](https://www.hypertrack.com/docs/manage-worker-availability.md) - [Android SDK 7.X](https://www.hypertrack.com/docs/migrate-to-android-sdk-7x.md) - [iOS SDK 5.X](https://www.hypertrack.com/docs/migrate-to-ios-sdk-5x.md) - [Mileage Reimbursement](https://www.hypertrack.com/docs/mileage-reimbursement.md) - [ML based NCNS Score](https://www.hypertrack.com/docs/ml-ncns-product-description-and-usage.md) - [Test with mock locations](https://www.hypertrack.com/docs/mock-location.md) - [Multi-Device Workers](https://www.hypertrack.com/docs/multi-device-workers.md): Track workers across multiple devices - [No Show Detection](https://www.hypertrack.com/docs/ncns-detection.md) - [On-Demand Assignment](https://www.hypertrack.com/docs/on-demand-assignment.md) - [Order Ops Views](https://www.hypertrack.com/docs/order-ops-views.md) - [Places Ops Views](https://www.hypertrack.com/docs/places-ops-views.md) - [Places Intelligence](https://www.hypertrack.com/docs/places.md) - [Self-improving routes](https://www.hypertrack.com/docs/plan-scheduled-orders.md) - [Plugins](https://www.hypertrack.com/docs/plugins.md) - [Prepare for App Store Submission](https://www.hypertrack.com/docs/prepare-for-app-store-submission.md) - [Prepare for Google Play Submission](https://www.hypertrack.com/docs/prepare-for-google-play-submission.md) - [Configuration](https://www.hypertrack.com/docs/sdk-config.md) - [SDK Migration Guide](https://www.hypertrack.com/docs/sdk-migration-guide.md) - [Pre-shift and On-shift tracking](https://www.hypertrack.com/docs/shift-tracking.md) - [Stream Order Activity Markers via Webhooks](https://www.hypertrack.com/docs/stream-order-activity-markers-via-webhooks.md) - [Submit your App to Stores](https://www.hypertrack.com/docs/submitting-app-to-stores.md) - [Integration Overview](https://www.hypertrack.com/docs/technical-integration-2.md): This infographic describes the general technical integration. To get your customer integration diagram, [Sign up](https://dashboard.hypertrack.com/signup) and generate your integration solution [here](https://dashboard.hypertrack.com/workflow/use-case). - [Time & Attendance](https://www.hypertrack.com/docs/time-attendance.md) - [Track Orders using Geotags](https://www.hypertrack.com/docs/track-orders-with-geotags.md) - [Track Work](https://www.hypertrack.com/docs/track-work.md): How to start tracking work with Orders and other ways to manage tracking intent. - [End Customer View](https://www.hypertrack.com/docs/trckat-view.md) - [Whitelisting](https://www.hypertrack.com/docs/whitelisting.md) - [Legacy Worker Device Linking](https://www.hypertrack.com/docs/worker-device-linking.md) - [Worker Setup](https://www.hypertrack.com/docs/worker-setup.md) - [Worker Ops Views](https://www.hypertrack.com/docs/workers-ops-views.md) ## API Reference - [OpenAPI specification](https://www.hypertrack.com/reference/openapi.yaml): full machine-readable API definition --- # Full guide content ## Android SDK FAQ # Android SDK FAQ ### Why starting tracking from the server fails? HyperTrack relies on Firebase Cloud Messaging to deliver the tracking intent to the app, and to wake up the app if it is killed at that moment. This mechanism is generally reliable, but sometimes may fail or delay due to various reasons. We recommend to check the following frequent issues: * Check if you added FCM key properly as described in [Set up silent push notifications](https://hypertrack.com/docs/install-sdk-android#set-up-silent-push-notifications). * Check if you have matching app package and project ID for the key above and for the app. * Check if you mistakenly use wrong environment (production vs development) for the app. * Check if you have your app signature properly added to the Firebase project (may fail on debug builds). * If you want to simulate waking the app up, make sure you don't use `Force stop` to kill the app (this feature disables push notifications for that app until the next launch). Kill the app with phone reboot, with simulated crash, or by manually stopping the activities and the services instead. Killing the app from Android Studio or `adb` also counts as Force stopping and blocks the push notifications. * Check the push notification delivery with Firebase debug menu: call `*#*#426#*#*` in the device dialpad and press `Events` button. Reopen the debug app to update the logs. ### Why do I have persistent notification in my app? HyperTrack SDK by default runs as a foreground service. This is needed to ensure that the location tracking works reliably even when your app is in background. A foreground service is a service that the user is actively aware of and isn't a candidate for the system to kill when it is low on memory. Android requires foreground service to have a persistent notification in the status bar. The notification text should clearly describe that the location is being tracked. > User perceptible means that the user should be aware that a foreground service task is running on their device. Users can be considered aware if they initiate the action themselves; for example, the user might play a song or track a run. Your app can also make users aware of an ongoing foreground service by presenting a clear and accurate notification in the task bar on the device. [Source ("What does user perceptible mean?" section)](https://support.google.com/googleplay/android-developer/answer/13392821?hl=en\&utm_source=chatgpt.com#zippy=%2Cwhat-does-user-perceptible-mean) #### Can I customize the foreground service notification? Yes, check the `HyperTrackForegroundNotificationTitle` and `HyperTrackForegroundNotificationText` parameters in [SDK configuration](doc:sdk-config) doc. You can also check the code example in [Quickstart Android](https://github.com/hypertrack/quickstart-android/blob/master/quickstart-kotlin/app/src/main/AndroidManifest.xml) ### How do I handle battery saver killing my app? Check the [Whitelisting](doc:whitelisting) doc to learn how to handle the battery saver killing your app. ### How does tracking work in Doze mode? Doze mode requires device [to be stationary](https://developer.android.com/training/monitoring-device-state/doze-standby.html#understand_doze), so before OS starts imposing power management restrictions, exact device location is obtained. When device starts moving, Android leaves Doze mode and works regularly, so no special handling of Doze mode required with respect to location tracking. ### Why doesn't setting device metadata and name work in SDK? Devices API take precedence over SDK methods in setting device name and metadata. If you used it, the SDK methods will not modify device metadata and name. ### What runtime permissions are required for the SDK to work? Chech the [Grant permissions](https://hypertrack.com/docs/install-sdk-android#grant-the-permissions-to-the-app) section ### Why in the dashboard I can see `SDK killed by ...` outage reason? SDK killed can be a result of some kind of battery saving settings. Check [How do I handle system battery saver killing my app?](#how-do-i-handle-system-battery-saver-killing-my-app) ### Can I test the tracking without actual movement? Yes, please check the [Test the workflow with mock locations](doc:mock-location) doc. ### How to fix `Google Api Error: Invalid request - You must let us know whether your app uses any Foreground Service permissions.` when uploading the app to Google Play with API? This error can appear if you have `targetSDK` 34+. HyperTrack SDK have to use Foreground service, and starting Android 14 it requires declaring the Foreground service permission. If your app has this permission, you can't upload the update with API and need to do a manual release to fill in the `Foreground service permissions` form. Check our [Guide](doc:preparing-for-google-play-review#submit-foreground-service-permissions-form) if you have any issues with submitting the form. ### How to fix device not getting any location events and not showing any outages? This can ocassionally happen if the OS doesn't provide location updates despite the SDK requesting it. That can be caused by various reasons, like the device being in the area with bad GPS satellite visibility. Another case is if you have the same issue on multiple devices, and none of them can get any location. This usually indicates that the SDK had the undelying exception when requesting location update with the message like this: ``` AndroidRuntime: java.lang.IncompatibleClassChangeError: Found interface com.google.android.gms.location.FusedLocationProviderClient, but class was expected ``` This error is caused by the dependency conflict: your app has older Google Play Services Location dependency, and HyperTrack SDK depends on the newer version. The breaking change was added in version [21.0.0](https://developers.google.com/android/guides/releases#october_13_2022), and if your app depend on version 19.0.1 or older, and some other dependency (e.g. HyperTrack SDK) depend on 21.0.0 or newer, this exception is thrown. You can check which dependency version you are using with Gradle dependency graph command: ```bash Mac / Linux ./gradlew app:dependencies | grep 'com.google.android.gms:play-services-location' ``` ```cmd Windows gradlew app:dependencies ``` Check for lines containing `com.google.android.gms:play-services-location`. If any of them have version `19.0.1` or older, you should update the parent dependency to the newer version and check the graph again. If updating the dependency is not possible there is a special Location services plugin in HyperTrack SDK to overcome this issue. Use it instead of `implementation 'com.hypertrack:location-services-google:`: ```groovy build.gradle dependencies { ... implementation 'com.hypertrack:location-services-google-19-0-1:' ... } ``` ```kotlin build.gradle.kts dependencies { ... implementation('com.hypertrack:location-services-google-19-0-1:') ... } ``` If you are using framework like Flutter or React Native, check the [Plugins](doc:plugins) doc for according plugin dependencies. ### How to resolve the `You must let us know whether your app includes any health features.` Google Play Store submission issue This issue has come up in our own and customers' apps. For the app use case select `Other` and use a description like this: > The app doesn't have any Health features, we use Activity recognition to check when the user is walking, driving or not moving to enhance work tracking experience Once you do that your app should pass the review with flying colors:crossed_fingers: ![](/img/readme/aff8c6f555c00976954510f03661122e7602d040f5a3300d0f7331e7143e607c-image.png) --- ## Nearby Search # Nearby Search ## Introduction Live location is an important input to any on-demand dispatch, assignment and routing system. On-demand work may be assigned to drivers that are out and about fulfilling other work, or are physically distributed in a region. Assignment systems use a number of factors to allocate work to a driver. Knowing the live location of available drivers, and ranking them as nearest first from the first point of fulfillment (pickup, visit, delivery or gig location), becomes a critical input to dispatch systems. HyperTrack's 'Nearby Search' enables you to find nearby drivers based on live location to assign orders. The figure below provides an overview of how the feature works and the guide walks you through how you can implement it: [https://hypertrack.com/animations/infographic-ns](https://hypertrack.com/animations/infographic-ns) To learn how to setup your account use the feature, please refer to the guide below. ## Worker availability To ensure your drivers are included in Nearby Search results they need to be [made available](doc:manage-worker-availability) . If you have already completed this step proceed to the next step. ## Nearby search To help with on-demand assignment use cases, HyperTrack provides [Nearby API](/reference/post-nearby-v3). Nearby search locates drivers, figures out which ones are nearest to the order destination, and returns them as a sorted list with nearest first. The API supports two types of searches: a) Region-based nearby searches: which returns nearest drivers sorted by Haversine distance from the order destination. This is generally used to find potential candidate drivers closest to an order destination. b) ETA-based nearby searches: which returns the nearest drivers to an order destination by drive-time using live traffic data. This is generally used to find a highly targeted list of drivers sorted on actual drive times in order to assign an order and know when the driver is likely to actually arrive at the destination. Use this POST [Nearby API](/reference/post-nearby-v3) request to find available app users near work location. > POST   `https://v3.api.hypertrack.com/nearby` The POST request contains the following parameters: * `order` represents the order for which the search is being conducted. The order object includes the order destination and optional parameters like the order\_id & any metadata; * `search_type` this indicates the type of Nearby search to be conducted and can be either "region" or "eta"; * `search_filter` filters nearby search results by app users with matching. You can use this parameter to provide different types of filters such as a maximum search radius, driver profile based filters, specific driver lists, etc; Sample Nearby payloads for the different types of searches are provided in the [documentation](/reference/post-nearby-v3). Please review working code examples written in different languages to copy and re-use to make requests via Nearby API. As always, please to us at [help@hypertrack.com](mailto:help@hypertrack.com) if you would like support in any other programming language you would like to use. --- ## Backfill Last-minute Cancellations # Backfill Last-minute Cancellations ## Introduction Field service and Shift-based work are often impacted by last-minute cancellations. Even when workers accept shifts in advance, unforeseen issues on the day of the job can prevent them from reaching the customer location. This leaves your team scrambling to find a qualified replacement on short notice—someone with the right skills who can still meet your customer promise. Location data plays a critical role in solving this challenge. HyperTrack offers a simple, powerful set of APIs that allow workers to share real-time availability and location. This enables your system to quickly identify and match the nearest qualified worker, ensuring the job gets done on time and at the right place. ## Prerequisite - **Required** 1. Onboard Workers to the HyperTrack platform by following the [Worker App Setup](https://hypertrack.com/docs/driver-app-setup) guide - Optional 1. Set up known Work Places where searches often happen by following the [Places](https://hypertrack.com/docs/places) guide ## Step by step solution To solve for last minute cancellations, there are 2 simple steps that you can follow. ### 1. Set Worker Availability Workers can be marked as available either through the server-side API or via an on-device method using the SDK. The choice depends on your operating model—whether you’re managing an on-demand workforce with dynamic availability or a shift-based workforce that works designated hours each day. To learn more on how to implement your preferred option, use the guides below: - [Server-side controlled worker availability](/reference/post-workers-worker_handle-work_status) - [Worker App controlled availability](https://hypertrack.github.io/mobile/sdk-android/latest/-hyper-track%20-s-d-k%20for%20-android/com.hypertrack.sdk.android/-hyper-track/index.html#-1044064712%2FProperties%2F165651098) Set availability only when necessary to ensure Worker privacy is respected. ### 2. Invoke Nearby API Once your Workers are marked as available, they become discoverable via the [Nearby API](/reference/post-nearby-v4). Based on your integration, the API can use an order_handle, place_handle, or raw coordinates to define the location for the search. The API supports powerful filtering options to return a refined list of Workers, delivering up to 10 results sorted by proximity—from closest to farthest from the specified location. For implementation details, refer to the [Nearby API reference](/reference/post-nearby-v4). ## Cookbook Here is an implementation cookbook to get started with solving your last minute cancellation issues and ensuring a high fill-rate.
## FAQ - Does setting the availability mean the Worker is always tracked?
No, while the HyperTrack SDK requires “always-on” location permission, the availability feature uses a lightweight tracking configuration. It retrieves the Worker’s location only when a Nearby API request is made. HyperTrack manages the process of reaching the Worker’s device in real time, ensuring minimal impact on battery life. --- ## Basic Visibility # Basic Visibility > Track orders using Geotags or Geofences to get basic visibility Best for workflows where workers go about visiting places without setting a plan or prior intent, and the business will benefit from tracking their location timelines with drive distances and stops.
--- ## Location timesheet for payout & invoicing # Location timesheet for payout & invoicing _Content coming soon._ --- ## Breaks & Overtime # Breaks & Overtime --- ## Build Your App # Build Your App ## Introduction In case if you do not have one, the quickest way create and deploy your own app and play around with HyperTrack SDK is to clone one of the Quickstarts, run it on your mobile device and start tracking the app. ## Quickstarts Choose your favorite platform and framework option and clone the HyperTrack Quickstart app from Github. Follow README instructions in each repository to get started. * [iOS](https://github.com/hypertrack/quickstart-ios) * [Android](https://github.com/hypertrack/quickstart-android) * [React Native](https://github.com/hypertrack/quickstart-react-native) * [Expo](https://github.com/hypertrack/quickstart-expo) * [Flutter](https://github.com/hypertrack/quickstart-flutter) * [Ionic Capacitor](https://github.com/hypertrack/quickstart-ionic-capacitor) * [.NET MAUI](https://github.com/hypertrack/quickstart-maui) ## Sample apps Additionally, you get started with open sourced started applications by cloning their repositories. Pick one that matches best your use case: * Visits (Android or iOS): best for workforce automation, logistics and fleet automation applications * Live Location Sharing (Android or iOS): best for sharing live location with ETA to customers * Ridesharing (Android or iOS): best for ridesharing, gig economy and on-demand delivery applications --- ## Clock-in / Clock-out # Clock-in / Clock-out ## Introduction Field service and shift-based workers are often paid per Work Order. As demand grows, location-powered workflows can automate and accelerate payments by providing ground truth to close out Work Orders. What once took weeks to reconcile can now happen the moment the order is completed and the worker walks out of the customer’s door. A key signal for triggering payment is the time the worker spends at the work site. HyperTrack provides a lightweight, location-aware signal that captures when a worker starts and ends their shift at the job site. One common challenge businesses face is workers clocking in or out from outside the work site to avoid penalties for punctuality. The HyperTrack SDK solves this by validating—directly on the device—whether the worker is within the predefined geofence of the work location. This ensures accountability and helps workers build trust with your business and your customers by upholding the promise of the Work Order. ## Highlights - Speed up Payouts: Accurately capture Work times for payout - Improve Compliance: Verify workers are on-site before they clock in (or clock out). - Reduce Disputes: Minimize no-show disputes by making sure work starts on destination. - Works offline: No network, no problem, the SDK syncs the signal as soon as the device is back online ## Prerequisite - **Required** - Onboard Workers to the HyperTrack platform by following the [Worker App Setup](https://hypertrack.com/docs/driver-app-setup) guide - [Set up Places](/docs/places) to let HyperTrack know the geofences for your customer work sites - **Optional** - If you also want to get signals around breaks, overtime and so on, you should use [Orders](/docs/shift-tracking) ## Step by Step Solution 1. **Invoke the geotag method in the SDK to capture the clock-in/clock-out** Once the app in integrated with the HyperTrack SDK, you can call the following method to capture the Clock-in/Clock-out signal. ``` addGeotag(order_handle, order_status, metadata) ``` Resources for different Mobile platforms - [iOS](https://hypertrack.github.io/mobile/sdk-ios/latest/documentation/hypertrack/hypertrack/addgeotag(orderhandle:orderstatus:metadata:)/), [Android](https://hypertrack.github.io/mobile/sdk-android/latest/-hyper-track%20-s-d-k%20for%20-android/com.hypertrack.sdk.android/-hyper-track/add-geotag.html), [React Native](https://hypertrack.github.io/sdk-react-native/classes/HyperTrack.html#addGeotag), [Flutter](https://hypertrack.github.io/sdk-flutter/hypertrack/HyperTrack/addGeotag.html), [Ionic](https://hypertrack.github.io/sdk-ionic-capacitor/classes/HyperTrack.html#addGeotag), [Cordova](https://github.com/hypertrack/cordova-plugin-hypertrack/blob/master/API-DOCUMENTATION.md#addgeotag), [Web](https://github.com/hypertrack/sdk-webview/blob/main/android/API_REFERENCE.md#addgeotag) While HyperTrack also provides the Arrival and Exit location and timestamps, **the clock-in/clock-out signals act more as a definitive signal for when work actually started and ended for a Work Order**. 2. **Check if the Worker is inside the Geofenced Work Location to control Clock-in/Clock-out** HyperTrack SDK supports on-device geofencing via isInsideGeofence property on your orders or places. Use the orders method when you are looking for more signals around duration spent at work site, breaks, overtime etc. > 🚧 Orders or Places integration > > This feature requires Orders API or Places API integration > > To use this feature, make sure you're tracking work with the Orders API. > > The isInsideGeofence status is calculated based on the order.destination geometry, which is provided when creating the order with the Orders API or the places.geometry provided when the place was created. > > Local geofencing works offline once any active orders have been received or Places have been defined. 3. **Consume the events to trigger workflows in real time** If you've added your webhook endpoint to your HyperTrack account, you will receive a webhook about the clock-in/clock-out event that you can use to trigger workflows in your systems. The details of the webhook payload can be found [here](/reference/webhooks#geotag-payload). ## Cookbook ## FAQ 1. What happens when the Worker is offline? The Clock-in/Clock-out feature works in offline mode where the Geofence check and the Clock-in/Clock-out signals are stored on device and sync with the HyperTrack platform once network is established. --- ## Distribute Orders App # Distribute Orders App ## Introduction The HyperTrack Orders App lets you assign work to you workers without having to build your own worker app. Workers can receive orders that need to be fulfilled, start on their route to fulfill them. Once they started work, they generate live location streams for live-order tracking, then complete orders and provide proof of completion as needed by your business. After orders in a route are completed, live tracking of the worker is stopped to ensure they are only tracked while they work. HyperTrack supports two ways of inviting workers to use the Orders App - via API and via our HyperTrack Dashboard UI. ## Invite Workers via API HyperTrack provides an [Invite Workers API](/reference/post-workers-worker_handle-invite) for you to generate personalized deep links for your worker to install the Orders App. Here's an example to get started quickly. Use your own worker **unique** identifier as the `worker_handle` to generate a unique invitation link payload in the request below: To generate a deep link you can make a request as follows: > POST   `[https://v3.api.hypertrack.com/{worker_handle}/invite](/reference/post-workers-worker_handle-invite)` If the `worker_handle` provided was `worker_foo_1` it will generate a response as shown below with the `invite_link` which is a deep link URL that can be shared with the worker via Email, SMS or your preferred communication channel. ```shell script [ { "worker_handle": "worker_foo_1", "invite_link": "https://hypertrack-orders.app.link/wqepoifv8f34c" } ] ``` When the worker clicks the deep link URL it will take them to the Android or iOS app stores depending on their device and let them install the Orders App. When the app is installed, the HyperTrack SDK will generate a `device_id` that is automatically associated with the unique `worker_handle` that is submitted in the payload above. ## Invite Workers via HyperTrack Dashboard Operations managers can go to HyperTrack Dashboard, [navigate to `Workers` section](https://dashboard.hypertrack.com/drivers?view=devices) in the lefthand side panel, then select workers to send the email with an app install link. ![](/img/readme/176f48a2a3bd8bc90b7b350809c9324b17b8543ecdd1371c2d64a6b04e6783ae-image.png) --- ## Distribute Visits App # Distribute Visits App ## Introduction Use the ready to deploy HyperTrack Visits App to automate visit capture without having to spend time building your own app. Invite users one at a time or in bulk by using either CSV import or API. Once unique links are generated, your app users will be able to install Visits App without having to perform login and immediately start tracking. Visits app users can perform visits at destinations shown in the app. Each destination in the app can be created by creating a corresponding HyperTrack Place. ## Distribute Visits App to your users ### Send email invitations to your app users from the dashboard Operations managers can go to [HyperTrack Worker Ops View,](https://dashboard.hypertrack.com/workers) to create a Workers and then invite them to the HyperTrack Visits App. The invitation is sent via email to the individual Workers to onboard them to the Visits App. Steps: 1. Navigate to click the right most icon with a "plus" on the top right. 2. Create an entry for the worker if not present already 3. Once the worker's entry appears in the list, selecting it and clicking at the invite icon to enter the invitation workflow ![](/img/readme/bafa4794ec8b8cd953b1b3fe330374e488c76dedfba26265e886f81d337443b2-image.png)
### Import in bulk with CSV file You can use the CSV import feature to bulk import your app users and at once invite all imported users to install the app. ## Distribute Visits App to your app users with API HyperTrack provides an Generate invitation links API for you to generate personalized deep links for your user to install Visits App. Use your own app user **unique** identifier to generate a unique invitation link payload. For example, to generate a unique invitation for the user `0053t000007wsZPAAY` you create deep link URLs with the following payload: ```shell script payload='{ "metadata": [ {"driver_id": "0053t000007wsZPAAY"} ] }' ``` with a result like this: ```shell script [ { "url": "https://hypertrack-logistics.app.link/1peqNytrWab", "metadata": {"driver_id": "0053t000007wsZPAAY"}} ] ``` After you obtain the link, you can choose your preferred communication method. You can send this link to your mobile app user via email, SMS, or WhatsApp, for example. Once your user installs Visits App with `https://hypertrack-logistics.app.link/1peqNytrWab` URL from above, the user's new `device_id` becomes automatically associated with the unique user record identifier that is submitted in the payload above. Once the app installs and loads, it will process deep link data from the invitation and connect your user's identifier as primary identity to the device in your HyperTrack account. In some cases, this may take time before screens below are loaded. --- ## Worker App Setup # Worker App Setup Choose from one of the following setup guides to set up the Worker app that you will use to manage assigning orders to workers and live tracking them. * **[Distribute Orders App](/docs/guides/distribute-orders-app)**: To plan, assign and track orders you can use the Orders App to get your fleet up and running without any mobile development effort. * **[Distribute Visits App](/docs/guides/distribute-visits-app)**: If you only need to track worker visits to places of interest and do not require estimating order ETAs, delays etc, you can use the Visits App to get your fleet up and running without any mobile development effort. * **[Install SDK](/docs/install-sdk)**: If you already have an app deployed in the field, add the HyperTrack SDK that is appropriate for your native or hybrid app. * **[Build new app](/docs/guides/build-your-app-with-quickstarts)**: To build a new app, start with our quickstarts or open source samples for logistics, ridesharing and live location sharing. --- ## Embed Views into Ops Dashboard # Embed Views into Ops Dashboard As team members are tracked throughout the day, operations managers need tools to monitor their teams in real-time and review detailed historical reports. As the number of assets on the move increases, these managers require scalable dashboards that allow for quick assessment of their teams’ locations, organized by criteria such as team names, categories, or geographic regions. They must have the ability to see where their team members are at any given moment, review their location history, activity, and tracking status, both currently and historically. For reporting and auditing purposes, they also need to export detailed worker history data and generate aggregated reports tailored to their preferences. To simplify the management of large, mobile teams, HyperTrack offers restricted view functionality that automatically organizes devices based on metadata set through the SDK or API. ## Embed our Views All HyperTrack Ops views are embeddable in an iframe (inline frames). This section provides an overview and methods to use the iframe. ### Inline Frames In order to embed a dashboard into your web application, you can add embeddable views implemented with HTML inline frames. An iframe has important properties to be considered during implementation. * Iframe size: By default, an iframe is sized with 200 pixels height and 300 pixels width and it is recommended to implement responsiveness using CSS. [Here is a sample implementation](https://jsfiddle.net/agraebe/kwd1795b/) * Responsive views: All embeddable views are responsive and the mobile views will be displayed when the iframe size is below 500 pixels * Security: When you activate the `sandbox` property for the iframe, please include `allow-scripts allow-same-origin` to ensure successful execution of the JavaScript present in the Views * Compatibility: Please review [browser compatibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#Browser_compatibility) of iframe properties you want to use * Loading times: In order to improve speed, it's recommended to set the iframe's src attribute with JavaScript after the main content is done with loading > 📘 Avoid Using `Referrer-Policy: same-origin` for Embedded Inline Frames > > Setting `Referrer-Policy: same-origin` can cause significant issues when embedding content in inline frames. This policy prevents the `Referrer` header from being sent on cross-origin requests, breaking functionality for embedded iframes that depend on it for authentication, resource loading, or API calls. > > **Why`same-origin` Causes Problems** > > * The `Referrer` header is omitted for cross-origin iframe requests, leading to authentication failures or missing context. > * Some browsers, like Safari, enforce stricter privacy settings (e.g., "Prevent Cross-Site Tracking"), which can exacerbate this issue. > * This breaks cross-origin iframes even when other headers (e.g., CORS) are properly configured. > > **Avoid using`Referrer-Policy: same-origin` for inline frame content.** Instead, use a more permissive policy that allows the `Referrer` header to be included for cross-origin requests ### Embed views with a secure access token Use the [Secure Embed View API](/reference/post-oauth-embed-token) to obtain a limited use token for secure access to the embeddable views. This token would be unique, short-lived, and restricted. ```shell curl -X POST https://v3.api.hypertrack.com/oauth/token \ -d "{ "client_id": "{AccountId}:", "client_secret": "{SecretKey}", "grant_type": "client_credentials", "scope": "*" }" ``` Once this token is obtained, you can use it as follows: ``` https://embed.hypertrack.com/views/orders?token= ``` ### Safely and securely embed views with restricted URL based scope You can use this API to create restricted scope URL views. For example, you want to create a limited scope view that only allows to see worker's location near or inside the shift destination geofence. To achieve this, you may compose the following url with these parameters: `https://embed.hypertrack.com/orders/your_order_handle?show-visits-only=true` To achieve this, you use this API to create a secure embed URL as shown in the API reference above. The `secure_embed_url` value shared in the API response provides a secure way of creating a URL string that can be safely shared with your customers while ensuring worker's home location privacy. ### Securely restrict views with access token scope Use scopes to restrict access to certain pages or assets whenever necessary. A scope value can be composed as follows: ``` [read|write|*].[api|embed].[orders|trips|devices].[order_id|trip_id|device_id] ``` Scope can be defined as `*` as in `access everything allowed`but can also be composed as follows: * `read.embed.orders` allows you to embed views where you can retrieve and display all orders * `read.embed.drivers` allows you to embed views where you can retrieve and display all drivers * `read.embed.orders.96f7ec96-402c-47a7-b0a1-eb6b91640a58` allows you only to display only this order To obtain a restricted token to only access a given order `order_122`, you can use the following example with a limited scope: ```shell curl -X POST https://v3.api.hypertrack.com/oauth/token \ -d "{ "client_id": "{AccountId}:", "client_secret": "{SecretKey}", "grant_type": "client_credentials", "scope": "read.embed.orders.order_122" }" ``` > 📘 Support for scopes with `write` and `api` values will be available in future releases. ### 2. Embed views using Publishable Key You can embed the HyperTrack Ops views using your publishable key found in the Setup page on your HyperTrack dashboard. ```shell ## Coding view instructions const baseUrl = "https://embed.hypertrack.com/views/orders" ## This is an example Publishable Key. Please replace it with the key you obtain from the Setup page. const publishableKey = "rYd51pSVlZkhisUkcQCncp-c5CVxQeRi6s6bAXM6T76bWwUlaUMlQ" ## Embeddable widget for Get Devices Status by metadata