react-native-mdd-locate-sdk

react-native-mdd-locate-sdk is a React Native wrapper for the MddLocateSDK, providing asset tracking capabilities for React Native apps. This SDK allows you to integrate the Mobile Dealer Data asset tracking platform into your React Native projects, enabling tracking tag asset functionality in your app.

Installation

To install the package, follow these steps:

1. Install the NPM Package

Run the following command in the root of your React Native project:

npm install react-native-mdd-locate-sdk

2. Link the iOS Native Module

Navigate to the ios/ directory of your React Native project and install the CocoaPods dependencies:

cd ios
pod install

3. Swift Package Manager Integration

The MddLocateSDK is distributed via Swift Package Manager. Ensure that your iOS project includes the MddLocateSDK as a Swift package:

1. Open your project in Xcode.
2. Navigate to File → Add Packages....
3. Enter the repository URL: https://github.com/Mobile-Dealer/mdd-locate-swift.
4. Select the appropriate version and add the package.

Permissions

To ensure your app functions correctly with the MddLocateSDK, you'll need to add the following permissions to your Info.plist:

Location Permission

Add the following entry to request location access:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to provide beacon scanning functionality related to vehicles in your vicinity.</string>

Bluetooth Permission

Add the following entries to request Bluetooth access:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to connect to tracking devices.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to connect to tracking devices.</string>

Usage

Below is an example of how to use the react-native-mdd-locate-sdk in your React Native components.

1. Import the SDK

First, import the package in your React Native component:

import MddLocateSDK from 'react-native-mdd-locate-sdk';

2. Configure the SDK

Before using any tracking functionality, you need to configure the SDK with your API key:

MddLocateSDK.configure('YOUR_API_KEY');

3. Start Tracking Tags

Start background tracking for a specific user:

MddLocateSDK.startTrackingTags('USERNAME');

4. Start Detecting a Tracking Tag

To start detecting a specific tracking tag:

MddLocateSDK.startDetecting('TRACKING_TAG_ID');

5. Stop Detecting a Tracking Tag

To stop detecting a specific tracking tag:

MddLocateSDK.stopDetecting('TRACKING_TAG_ID');

6. Get RSSI for a Detected Tracking Tag

To get the Received Signal Strength Indication (RSSI) for a detected tracking tag:

const rssi = await MddLocateSDK.getDetectedRssi('TRACKING_TAG_ID');
console.log('RSSI:', rssi);

Example Component

Here is a complete example of a React Native component that uses the react-native-mdd-locate-sdk:

import React, { useState, useEffect } from 'react';
import { View, Text, TextInput, Button } from 'react-native';
import MddLocateSDK from 'react-native-mdd-locate-sdk';

const App = () => {
  const [trackingTagId, setTrackingTagId] = useState('');
  const [rssi, setRssi] = useState(null);
  const [detecting, setDetecting] = useState(false);

  useEffect(() => {
    MddLocateSDK.configure('YOUR_API_KEY');
    MddLocateSDK.startTrackingTags('USERNAME');
  }, []);

  const handleDetectToggle = async () => {
    if (!detecting) {
      MddLocateSDK.startDetecting(trackingTagId);
      setDetecting(true);
    } else {
      MddLocateSDK.stopDetecting(trackingTagId);
      setDetecting(false);
    }
  };

  const getRssi = async () => {
    const rssiValue = await MddLocateSDK.getDetectedRssi(trackingTagId);
    setRssi(rssiValue);
  };

  return (
    <View style={{ padding: 20 }}>
      <Text>RSSI: {rssi}</Text>
      <TextInput
        value={trackingTagId}
        onChangeText={setTrackingTagId}
        placeholder="Enter Tracking Tag ID"
        style={{ height: 40, borderColor: 'gray', borderWidth: 1, marginBottom: 20 }}
      />
      <Button
        title={detecting ? 'Stop Detecting' : 'Start Detecting'}
        onPress={handleDetectToggle}
      />
      <Button title="Get RSSI" onPress={getRssi} />
    </View>
  );
};

export default App;

API Reference

MddLocateSDK.configure(apiKey: string)

Configures the MddLocateSDK with the provided API key. This method must be called before using any other SDK functions.

Parameters:

• apiKey: The API key string required to authenticate with the MddLocateSDK.

MddLocateSDK.startTrackingTags(username: string)

Starts background tracking for the specified user.

Parameters:

• username: The username associated with the tracking session.

MddLocateSDK.startDetecting(trackingTagId: string)

Starts detecting a specific tracking tag by its ID.

Parameters:

• trackingTagId: The ID of the tracking tag you want to detect.

MddLocateSDK.stopDetecting(trackingTagId: string)

Stops detecting the specified tracking tag.

Parameters:

• trackingTagId: The ID of the tracking tag you want to stop detecting.

MddLocateSDK.getDetectedRssi(trackingTagId: string)

Returns the Received Signal Strength Indication (RSSI) for a detected tracking tag.

Parameters:

• trackingTagId: The ID of the tracking tag for which you want to get the RSSI.

Returns:

• Promise<number>: A promise that resolves to the RSSI value.

Error Handling

When using getDetectedRssi, ensure you handle errors appropriately, as it may throw an error if the tracking tag ID is invalid or if the RSSI cannot be retrieved.

Example:

try {
  const rssi = await MddLocateSDK.getDetectedRssi('TRACKING_TAG_ID');
  console.log('RSSI:', rssi);
} catch (error) {
  console.error('Failed to get RSSI:', error);
}

Changelog

All notable changes to this project will be documented in this section.

1.0.0 - Initial Release

• Initial release of the react-native-mdd-locate-sdk.
• Supports basic configuration, tracking, detection, and RSSI retrieval.

License

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

Support

If you have any questions or need support, please contact us at [email protected].