Skip to main content

​
Configuration Types

This page documents the interfaces and types used for configuring apps in the MentraOS SDK.

​
AppConfig

Represents the structure of the app_config.json file, defining metadata and settings for an app. 
interface AppConfig {
  /** The human-readable name of the app. */
  name: string;

  /** A brief description of the app's functionality. */
  description: string;

  /** An array defining the configurable settings for the app. */
  settings: (AppSetting | GroupSetting)[];
}
Example: 
const appConfig: AppConfig = {
  name: "Weather App",
  description: "Displays real-time weather information for your current location",
  settings: [
    {
      type: "group",
      title: "General Settings"
    },
    {
      key: "useCelsius",
      type: AppSettingType.TOGGLE,
      label: "Use Celsius",
      defaultValue: false
    },
    {
      key: "updateFrequency",
      type: AppSettingType.SELECT,
      label: "Update Frequency",
      defaultValue: "hourly",
      options: [
        { label: "Hourly", value: "hourly" },
        { label: "Every 3 hours", value: "3hours" },
        { label: "Daily", value: "daily" }
      ]
    }
  ]
};

​
AppSetting

Union type representing a specific, configurable application setting. Used in AppConfig and AppSettings. 
type AppSetting =
  | (BaseAppSetting & {
      type: AppSettingType.TOGGLE;
      defaultValue: boolean;
      value?: boolean
    })
  | (BaseAppSetting & {
      type: AppSettingType.TEXT;
      defaultValue?: string;
      value?: string
    })
  | (BaseAppSetting & {
      type: AppSettingType.SELECT;
      options: { label: string; value: any }[];
      defaultValue?: any;
      value?: any;
    });

interface BaseAppSetting {
  /** The unique identifier for this setting (used programmatically). */
  key: string;

  /** The human-readable label displayed in the settings UI. */
  label: string;

  /** The current value set by the user (provided by the cloud at runtime). */
  value?: any;

  /** The default value for this setting if the user hasn't set one. */
  defaultValue?: any;
}
The AppSettingType enum defines the available types of settings:

​
Toggle Setting Example

const toggleSetting: AppSetting = {
  key: "enableNotifications",
  type: AppSettingType.TOGGLE,
  label: "Enable Notifications",
  defaultValue: true,
  value: true
};

​
Text Setting Example

const textSetting: AppSetting = {
  key: "username",
  type: AppSettingType.TEXT,
  label: "Username",
  defaultValue: ""
};

​
Select Setting Example

const selectSetting: AppSetting = {
  key: "theme",
  type: AppSettingType.SELECT,
  label: "Theme",
  options: [
    { label: "Light", value: "light" },
    { label: "Dark", value: "dark" },
    { label: "System Default", value: "system" }
  ],
  defaultValue: "system"
};

​
GroupSetting

A pseudo-setting used in AppConfig to group related settings visually in the UI. It doesn’t hold a value. 
interface GroupSetting {
  /** Must be 'group'. */
  type: 'group';

  /** The title displayed for the group header in the settings UI. */
  title: string;
}
Example: 
const groupSetting: GroupSetting = {
  type: "group",
  title: "Display Preferences"
};

​
AppSettings

An array of AppSetting objects, representing the complete set of settings for an app instance, including current user values. 
type AppSettings = AppSetting[];
Example: 
const settings: AppSettings = [
  {
    key: "enableNotifications",
    type: AppSettingType.TOGGLE,
    label: "Enable Notifications",
    defaultValue: true,
    value: false // User has changed from default
  },
  {
    key: "refreshInterval",
    type: AppSettingType.SELECT,
    label: "Refresh Interval",
    options: [
      { label: "1 minute", value: 60 },
      { label: "5 minutes", value: 300 },
      { label: "15 minutes", value: 900 }
    ],
    defaultValue: 300,
    value: 60 // User has selected 1 minute
  }
];

​
Working with Settings

​
Accessing Setting Values

To access a specific setting’s value: 
// Using AppSession.getSetting()
const enableNotifications = appSession.getSetting<boolean>("enableNotifications");
if (enableNotifications) {
  // Notifications are enabled
}

// Using AppSession.getSettings() with manual lookup
const allSettings = appSession.getSettings();
const refreshInterval = allSettings.find(s => s.key === "refreshInterval")?.value;
The getSetting() and getSettings() methods are available on the AppSession class.

​
Reacting to Setting Changes

// Listen for changes to all settings
appSession.events.onSettingsUpdate((settings) => {
  // Handle updated settings
  console.log("Settings updated:", settings);
});

// Listen for changes to a specific setting
appSession.events.onSettingChange<number>("refreshInterval", (newValue, oldValue) => {
  console.log(`Refresh interval changed from ${oldValue} to ${newValue}`);
  // Update refresh logic based on new interval
});
The onSettingsUpdate() and onSettingChange() methods are available on the EventManager class, accessed via appSession.events.

​
Automatic Subscription Management Based on Settings

appSession.setSubscriptionSettings({
  // Update subscriptions when these settings change
  updateOnChange: ["enableTranscription", "enableHeadTracking"],

  // Determine active subscriptions based on current settings
  handler: (settings) => {
    const subscriptions: StreamType[] = [];

    // Find settings by key
    const enableTranscription = settings.find(s => s.key === "enableTranscription")?.value === true;
    const enableHeadTracking = settings.find(s => s.key === "enableHeadTracking")?.value === true;

    // Add subscriptions based on settings
    if (enableTranscription) {
      subscriptions.push(StreamType.TRANSCRIPTION);
    }

    if (enableHeadTracking) {
      subscriptions.push(StreamType.HEAD_POSITION);
    }

    return subscriptions;
  }
});
The setSubscriptionSettings() method is available on the AppSession class. It allows automatic management of StreamType subscriptions based on setting changes.
⌘I