Privileges

Privileges are the basic unit of access control for privacy and security in Lumin OS. Users can choose which privilege to grant your app, although some privileges are auto-granted and cannot be revoked. Similar privileges are bundled into categories that can be revoked or granted in Device Settings.

Lumin OS has three privilege types:

  • Auto-granted - These privileges are automatically granted to apps when added to the app's manifest.

  • Sensitive - These privileges require user consent on first use. They must be added to the app's manifest and requested at runtime.

  • Reality - These privileges require user consent for each active session. They must be added to the app's manifest and requested at runtime. You should re-request these privileges when returning from the paused state. When a privileged function is in use, the OS displays an indicator.

See Privileges for more information about privileges and how they're used.

Determine Required Privileges

First determine which privileges your app requires in the MagicScript API reference. Each method lists any required privileges.

Add Privileges to the Manifest

All privileges that your app can request over its lifetime must be added to the manifest. Reality and Sensitive privileges must also be requested at runtime.

Manually add privileges to the manifest. Remove the 'k' in front of the privilege ID when adding them to the manifest. See Declaring your Manifest for more information.

Note: If you submit your app to the Magic Leap World store, your app can be rejected if you request privileges your app doesn't use. See MR-201 for more information.

Requesting Privileges in MagicScript

Sensitive and Reality privileges require an entry in your app's manifest and a request at runtime.

On the first request at runtime, the OS prompts the user to grant the privilege. If the user does not grant the privilege when prompted, they must either enable the privilege in Settings > Privacy > Privileges or uninstall and reinstall the app.

You can implement your own dialog if the privilege is denied to prompt the user to grant the privilege through Settings.

  1. Import PrivilegeID from lumin.LanscapeApp or lumin.ImmersiveApp file.

    import {PrivilegeId } from "lumin";
  2. Request the privileges your app requires. The API provides two different calls:

    • Blocking - blocks all other processes.

      var result =
      app.requestPrivilegeBlocking(PrivilegeId.kLocalAreaNetwork);
      print("privilege response", result);
      node.setText("Request Again");
      text.setText("Privilege " + ((result == 1) ? "Granted" : "Not Granted"));
    • Asynchronous - does not block app while the privileges is being processed. The result is returned on the main thread as a privilege event.

      app.requestPrivilege(PrivilegeId.kLocalAreaNetwork);
  3. Verify the privilege results and handle errors or denied privileges.

  4. For Reality privileges, when an app resumes, verify that the privileges are still granted.

For a complete working sample, view the MagicScript Privilege sample on github here: MagicScript Privilege Sample

Troubleshooting

If an auto-granted privilege is denied:

  • Verify that your manifest includes the privilege.
  • Verify that the privilege is granted on your device
    • Globally in Settings > Privacy > Privileges.
    • Per app in Settings > Apps > Privileges.

If your app does not perform a privileged function:

  • Add more error checking to determine if the function is called.

  • Verify that the privilege is granted on your device

    • Globally in Settings > Privacy > Privileges.
    • Per app in Settings > Apps > Privileges.
  • Completely uninstall the app and reinstall. The privilege might have been denied on the first install.