sdk-telemetry v1.0.4

SDK Telemetry

SDK Telemetry is a library designed for real-time location tracking and telemetry data collection. It helps developers capture, process, and analyze device location data efficiently, providing both current location and real-time tracking capabilities.

📦 Installation

Install the SDK via npm or yarn:

Using yarn

npm install sdk-telemetry

Using npm

yarn add sdk-telemetry

🚀 Features

Current Location: Fetch the current GPS coordinates of the device (latitude, longitude, altitude, speed, and heading). Real-Time Tracking: Continuously track device movement with a customizable distance filter to optimize performance and reduce Geocoding/Directions: Convert geographic coordinates into human-readable addresses and retrieve coordinates for a given addressnoise. Geofencing: Monitor specific geographic areas and trigger events when entering or exiting these zones. Offline Tracking: Track locations when offline and sync them once the connection is restored.

🛠️ Usage

1. Initialize the SDK Before using any functionality, initialize the SDK:

import { TelemetrySDK } from "sdk-telemetry";

TelemetrySDK.initialize({
  geocodingApiKey: "YOUR_API_KEY", // Required for geocoding features
});

2. Get Current Location Fetch the device's current location:

TelemetrySDK.getCurrentLocation()
  .then((location) => {
    console.log("Current location:", location);
  })
  .catch((error) => {
    console.error("Error fetching location:", error.message);
  });

3. Start Real-Time Tracking Start tracking the device's movement in real-time. You can specify a distance filter to ignore updates for insignificant movements.

TelemetrySDK.startRealTimeTracking(
  (location) => {
    console.log("New location captured:", location);
  },
  50, // Minimum distance in meters to record a new location
  (error) => {
    console.error("Tracking error:", error.message);
  }
);

To stop tracking:

TelemetrySDK.stopRealTimeTracking();
console.log("Tracking stopped.");

4. Geocoding/Directions

• 4.1 Get Address from Coordinates Convert latitude and longitude into a human-readable address:

TelemetrySDK.getAddressFromCoordinates(40.712776, -74.005974)
  .then((address) => {
    console.log("Address:", address);
  })
  .catch((error) => {
    console.error("Error fetching address:", error.message);
  });

• 4.2 Get Coordinates from Address Retrieve latitude and longitude for a given address:

TelemetrySDK.getCoordinatesFromAddress("1600 Amphitheatre Parkway, Mountain View, CA")
  .then(({ latitude, longitude }) => {
    console.log("Coordinates:", { latitude, longitude });
  })
  .catch((error) => {
    console.error("Error fetching coordinates:", error.message);
  });

5. Geofencing

• 5.1 Add a Geofence Define a geofence by specifying a unique identifier, a central location (latitude and longitude), and a radius (in meters):

TelemetrySDK.addGeoFence("home", { latitude: 40.712776, longitude: -74.005974 }, 100);
TelemetrySDK.addGeoFence("office", { latitude: 37.774929, longitude: -122.419418 }, 200);
console.log("Geofences added.");

• 5.2 Remove a Geofence Remove a geofence using its unique identifier:

TelemetrySDK.removeGeoFence("home");
console.log("Geofence removed.");

• 5.3 Monitor Geofences Combine with real-time tracking to detect when the device enters or exits a geofence:

TelemetrySDK.startRealTimeTracking(
  (location) => {
    TelemetrySDK.checkGeoFences(location, (event, fenceId) => {
      console.log(`Geofence event: ${event} - ${fenceId}`);
    });
  },
  50, // Minimum distance in meters to register a new location
  (error) => {
    console.error("Error during real-time tracking:", error.message);
  }
);

5. Offline Tracking Track user locations automatically when offline and sync them when back online.

• 6.1 Start Offline Tracking

TelemetrySDK.startOfflineTracking(TelemetrySDK.getCurrentLocation, 5000);
console.log("Offline tracking started.");

• 6.2 Stop Offline Tracking

TelemetrySDK.stopOfflineTracking();
console.log("Offline tracking stopped.");

• 6.3 Sync Offline Locations Combine with real-time tracking to detect when the device enters or exits a geofence:

TelemetrySDK.syncOfflineLocations(async (locations) => {
  console.log("Syncing offline locations:", locations);

  // Example: Send locations to server
  await fetch("https://your-api.com/sync-locations", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ locations }),
  });
});

⚙️ Configuration Options

Real-Time Tracking

• distanceFilter:
  • Minimum distance (in meters) required to record a new location update.
  • Helps reduce noise in the data and improve battery efficiency.
  • Default: No default (you must specify it).

Geocoding

• geocodingApiKey:
  • Required for using geocoding features (e.g., converting coordinates to addresses).
  • Obtain an API key from services like OpenCage Geocoder or Google Maps.

Geofencing

• id: Unique identifier for the geofence.
• center: Central location of the geofence (latitude and longitude).
• radius: Radius of the geofence in meters.

🧪 Testing

Jest Tests Run the included unit tests to ensure the SDK functions correctly:

npm test

🛡️ Compatibility

• React Native: Fully supported.
• Web Browsers: Compatible via standard Geolocation API.

📚 Roadmap

Planned features:

• Local Storage: Save locations locally for offline usage..
• Sync with Backend: Synchronize location data with a backend server.
• Geofencing: Trigger events when entering or exiting predefined geographic areas.
• Movement Analysis: Analyze user patterns (e.g., walking, running, driving).

❓ FAQ

1. What happens if GPS is disabled?** If the device's GPS is disabled, the SDK will return an error message indicating that location data is unavailable.

2. How does the distanceFilter work? The distanceFilter ensures that only location updates with a significant distance change (e.g., 50 meters) are captured. This reduces unnecessary updates and optimizes battery consumption.

3. Do I need an API key for geocoding? Yes, geocoding functionality requires an API key from a geocoding service like OpenCage or Google Maps. Make sure to initialize the SDK with the key before using these features.

4. Can I track locations offline? Yes, use the offline tracking functionality to store locations when there’s no internet connection and sync them when back online.

📝 License

This project is licensed under the MIT License. See the LICENSE file for details.

### Summary of Changes
1. Added Geocoding/Directions and GeoFencing to the Features section.
2. Included usage examples for geocoding (getAddressFromCoordinates and getCoordinatesFromAddress).
3. Highlighted the need for the geocodingApiKey in the configuration options.
4. Updated the FAQ to clarify geocoding-specific requirements.