nomnom-utilities-plugin

NomNom Utilities Plugin

A Capacitor plugin providing utility functions for the NomNom app.

Installation

npm install nomnom-utilities-plugin
npx cap sync

Configuration

iOS Configuration

Add the following to your app's Info.plist:

<!-- Always include these permissions -->
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to provide location-based services when the app is in use.</string>

<!-- Include this only if you need background location -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need your location to provide location-based services even when the app is in the background.</string>

<!-- For iOS 10 and earlier -->
<key>NSLocationAlwaysUsageDescription</key>
<string>We need your location to provide location-based services even when the app is in the background.</string>

<!-- For background mode -->
<key>UIBackgroundModes</key>
<array>
    <string>location</string>
</array>

Android Configuration

Add the following permissions to your AndroidManifest.xml if they're not already there:

<!-- Location permissions -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

Register the plugin in your MainActivity.java:

// Other imports...
import com.nomnom.plugins.utilities.NomnomUtilitiesPlugin;

public class MainActivity extends BridgeActivity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Initializes the Bridge
    this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
      // Add other plugins...
      add(NomnomUtilitiesPlugin.class);
    }});
  }
}

Usage

Always-On Location Tracking

The plugin handles permission requests automatically and gracefully degrades functionality if full permissions aren't granted:

• Requests appropriate permissions based on the options provided
• Falls back to foreground-only tracking if background permissions are denied
• Provides status information through events and return values

import { NomnomUtilities } from 'nomnom-utilities-plugin';

// Start location tracking (foreground only)
await NomnomUtilities.enableAlwaysOnLocation({
  enable: true,
  accuracy: 10, // meters for iOS, priority constant for Android
  distanceFilter: 5 // minimum distance (meters) before updates are sent
});

// Start location tracking with background updates
await NomnomUtilities.enableAlwaysOnLocation({
  enable: true,
  accuracy: 10,
  distanceFilter: 5,
  background: true,
  notificationTitle: "Location Tracking", // Android only
  notificationText: "NomNom is tracking your location" // Android only
});

// Stop location tracking
await NomnomUtilities.enableAlwaysOnLocation({
  enable: false
});

// Listen for location updates
NomnomUtilities.addListener('locationUpdate', (location) => {
  console.log('New location:', location);
  // location object contains:
  // - latitude
  // - longitude
  // - altitude
  // - accuracy
  // - altitudeAccuracy
  // - heading
  // - speed
  // - timestamp
});

// Listen for location errors
NomnomUtilities.addListener('locationError', (error) => {
  console.error('Location error:', error);
});

// Listen for authorization status changes
NomnomUtilities.addListener('authorizationStatusChange', (status) => {
  console.log('Authorization status changed:', status);
});

// Remove listeners when done
const locationListener = await NomnomUtilities.addListener('locationUpdate', ...);
locationListener.remove();

API

enableAlwaysOnLocation(options: LocationOptions): Promise

Enables or disables always-on location tracking.

LocationOptions

Property	Type	Default	Description
enable	boolean	-	Whether to start location updates (true) or stop them (false)
accuracy	number	iOS: kCLLocationAccuracyBest, Android: PRIORITY_HIGH_ACCURACY	Desired accuracy of the location data
distanceFilter	number	0	Minimum distance (meters) a device must move before an update event is generated (Note: On newer Android versions, this is handled internally based on the priority setting)
background	boolean	false	Whether to allow background location updates
notificationTitle	string	"Location Tracking"	Title for the background location notification (Android only)
notificationText	string	"NomNom is tracking your location"	Text for the background location notification (Android only)

getLocationPermissionStatus(): Promise

Gets the current location permission status from the device.

Returns: LocationPermissionStatus

Property	Type	Description
status	string	One of: 'notDetermined', 'restricted', 'denied', 'authorizedAlways', 'authorizedWhenInUse', 'unknown'
canUseLocation	boolean	Whether the app can use location services
canUseBackgroundLocation	boolean	Whether the app can use background location services

Example

// Check current permission status
const permissionStatus = await NomnomUtilities.getLocationPermissionStatus();
console.log('Current permission status:', permissionStatus.status);

if (permissionStatus.canUseLocation) {
  console.log('App can use location services');
  
  if (permissionStatus.canUseBackgroundLocation) {
    console.log('App can use background location services');
  } else {
    console.log('App cannot use background location services');
  }
} else {
  console.log('App cannot use location services');
}

Events

Event	Description	Data
locationUpdate	Emitted when a new location is available	Location object with coordinates and metadata
locationError	Emitted when a location error occurs	Error object with message
authorizationStatusChange	Emitted when location permission status changes	Status object

License

MIT