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