react-native-mdd-locate-sdk

React Native wrapper for MDD SDK

Installation

npm install react-native-mdd-locate-sdk

Android

You don't need to do anything to deal with library requirements, those will be handled automatically for you.

Permissions

You will need to set up permissions in order to make this work, and which ones you need will be dependent on the react-native versions you are trying to support. Please make sure that you have the following permissions granted in order to use the library propery:

Legacy (<= 30)

• BLUETOOTH
• BLUETOOTH_ADMIN

Modern (> 30)

• BLUETOOTH_SCAN
• ACCESS_COARSE_LOCATION
• ACCESS_FINE_LOCATION
• INTERNET
• POST_NOTIFICATIONS

iOS

1. Setting Up Required Permissions

To ensure your app functions correctly with the MddLocateSDK:

1. Open your app's Info.plist.

2. Add a new entry with the key NSLocationWhenInUseUsageDescription.

3. Set the value to a string describing why your app needs location access. For instance:

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

2. Enabling Required Capabilities

1. Open your project settings by clicking on the project name in the Project Navigator.

2. Select the app target from the list of targets.

3. Navigate to the "Signing & Capabilities" tab.

4. Click the + Capability button and add Background Modes.

5. In the "Background Modes" section, check the boxes for Location updates and Uses Bluetooth LE accessories.

Usage

This SDK provides a React Native interface for the MDD SDK, allowing you to interact with MDD services on both Android and iOS platforms.

Tag Tracking

import { startTrackingTags, stopTrackingTags, addReadHandler } from 'react-native-mdd-locate-sdk';

// Start tracking tags for a user
await startTrackingTags('your-api-key', 'username');

// Add a handler for read events
addReadHandler((event) => {
  console.log('Read event:', event);
});

// Get the current API key
const apiKey = await getApiKey();
console.log('Current API key:', apiKey);

// Stop tracking tags
const stopped = await stopTrackingTags();
console.log('Tracking stopped:', stopped);

Setting this up will allow the SDK to track tags that are available in bluetooth range of the phone and report them automatically to the MDD API.

Tag Detection

import { startDetecting, stopDetecting, addProximityUpdateHandler } from 'react-native-mdd-locate-sdk';

// Start detecting a specific tracking tag
const started = await startDetecting('tracking-tag-id');
console.log('Detection started:', started);

// Add a handler for proximity updates
addProximityUpdateHandler((event) => {
  console.log('Proximity update:', event.proximity);
});

// Stop detecting a specific tracking tag
const stopped = await stopDetecting('tracking-tag-id');
console.log('Detection stopped:', stopped);

This does not actually report to the API, but allows you to find a tag by indicating how close the tag is to a phone. Possible proximity values are: 'unknown', 'near', 'immediate', 'far'.

API Reference

getApiKey(): Promise<string>

Gets the currently configured API key.

• Returns: A promise that resolves to the current API key

startTrackingTags(apiKey: string, username: string): Promise<void>

Starts tracking tags for the specified username using the provided API key.

• Parameters:
  • apiKey - Your MDD SDK API key
  • username - The username to associate with tag tracking
• Returns: A promise that resolves when tracking has started

stopTrackingTags(): Promise<boolean>

Stops tracking tags.

• Returns: A promise that resolves to true if tracking was successfully stopped

addReadHandler(fn: (event: any) => void): void

Adds a handler for read events.

• Parameters: fn - A function that will be called with read events

startDetecting(trackingTagId: string): Promise<boolean>

Starts detecting the specified tracking tag.

• Parameters: trackingTagId - The ID of the tracking tag to detect
• Returns: A promise that resolves to true if detection was successfully started

stopDetecting(trackingTagId: string): Promise<boolean>

Stops detecting the specified tracking tag.

• Parameters: trackingTagId - The ID of the tracking tag to stop detecting
• Returns: A promise that resolves to true if detection was successfully stopped

addProximityUpdateHandler(fn: (event: { proximity: 'unknown' | 'near' | 'immediate' | 'far' }) => void): void

Adds a handler for proximity updates.

• Parameters: fn - A function that will be called with proximity update events

Error Handling

The SDK includes built-in error handling for common issues such as missing native modules. If you encounter a linking error, ensure that:

• You have run 'pod install' (for iOS)
• You have rebuilt the app after installing the package