@capgo/camera-preview 7.21.10 → 7.22.1

package/README.md

@@ -308,6 +308,8 @@ Documentation for the [uploader](https://github.com/Cap-go/capacitor-uploader)
 * [`getAspectRatio()`](#getaspectratio)
 * [`setGridMode(...)`](#setgridmode)
 * [`getGridMode()`](#getgridmode)
+* [`checkPermissions(...)`](#checkpermissions)
+* [`requestPermissions(...)`](#requestpermissions)
 * [`getHorizontalFov()`](#gethorizontalfov)
 * [`getSupportedPictureSizes()`](#getsupportedpicturesizes)
 * [`setFlashMode(...)`](#setflashmode)
@@ -503,6 +505,46 @@ Gets the current grid mode of the camera preview overlay.
 --------------------
 
 
+### checkPermissions(...)
+
+```typescript
+checkPermissions(options?: Pick<PermissionRequestOptions, "disableAudio"> | undefined) => Promise<CameraPermissionStatus>
+```
+
+Checks the current camera (and optionally microphone) permission status without prompting the system dialog.
+
+| Param         | Type                                                                                                                          | Description                                                                           |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| **`options`** | <code><a href="#pick">Pick</a>&lt;<a href="#permissionrequestoptions">PermissionRequestOptions</a>, 'disableAudio'&gt;</code> | Set `disableAudio` to `false` to also include microphone status (defaults to `true`). |
+
+**Returns:** <code>Promise&lt;<a href="#camerapermissionstatus">CameraPermissionStatus</a>&gt;</code>
+
+**Since:** 8.7.0
+
+--------------------
+
+
+### requestPermissions(...)
+
+```typescript
+requestPermissions(options?: PermissionRequestOptions | undefined) => Promise<CameraPermissionStatus>
+```
+
+Requests camera (and optional microphone) permissions. If permissions are already granted or denied,
+the current status is returned without prompting. When `showSettingsAlert` is true and permissions are denied,
+a platform specific alert guiding the user to the app settings will be presented.
+
+| Param         | Type                                                                          | Description                                           |
+| ------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------- |
+| **`options`** | <code><a href="#permissionrequestoptions">PermissionRequestOptions</a></code> | - Configuration for the permission request behaviour. |
+
+**Returns:** <code>Promise&lt;<a href="#camerapermissionstatus">CameraPermissionStatus</a>&gt;</code>
+
+**Since:** 8.7.0
+
+--------------------
+
+
 ### getHorizontalFov()
 
 ```typescript
@@ -1050,6 +1092,26 @@ Defines the options for capturing a sample frame from the camera preview.
 | **`quality`** | <code>number</code> | The quality of the captured sample, from 0 to 100. | <code>85</code> |
 
 
+#### CameraPermissionStatus
+
+| Prop             | Type                                                        |
+| ---------------- | ----------------------------------------------------------- |
+| **`camera`**     | <code><a href="#permissionstate">PermissionState</a></code> |
+| **`microphone`** | <code><a href="#permissionstate">PermissionState</a></code> |
+
+
+#### PermissionRequestOptions
+
+| Prop                          | Type                 |
+| ----------------------------- | -------------------- |
+| **`disableAudio`**            | <code>boolean</code> |
+| **`showSettingsAlert`**       | <code>boolean</code> |
+| **`title`**                   | <code>string</code>  |
+| **`message`**                 | <code>string</code>  |
+| **`openSettingsButtonTitle`** | <code>string</code>  |
+| **`cancelButtonTitle`**       | <code>string</code>  |
+
+
 #### SupportedPictureSizes
 
 Represents the supported picture sizes for a camera facing a certain direction.
@@ -1170,6 +1232,18 @@ The available flash modes for the camera.
 <code>"off" | "on" | "auto" | "torch"</code>
 
 
+#### PermissionState
+
+<code>'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'</code>
+
+
+#### Pick
+
+From T, pick a set of properties whose keys are in the union K
+
+<code>{
 [P in K]: T[P];
 }</code>
+
+
 #### FlashMode
 
 <code><a href="#camerapreviewflashmode">CameraPreviewFlashMode</a></code>

package/android/src/main/java/app/capgo/capacitor/camera/preview/CameraPreview.java

@@ -5,6 +5,8 @@ import static android.Manifest.permission.RECORD_AUDIO;
 
 import android.Manifest;
 import android.annotation.SuppressLint;
+import android.app.Activity;
+import android.content.Intent;
 import android.content.pm.ActivityInfo;
 import android.content.pm.PackageManager;
 import android.content.res.Configuration;
@@ -13,6 +15,7 @@ import android.graphics.drawable.ColorDrawable;
 import android.graphics.drawable.Drawable;
 import android.location.Location;
 import android.net.Uri;
+import android.provider.Settings;
 import android.util.DisplayMetrics;
 import android.util.Log;
 import android.util.Size;
@@ -21,6 +24,7 @@ import android.view.View;
 import android.view.ViewGroup;
 import android.webkit.WebView;
 import androidx.annotation.RequiresPermission;
+import androidx.appcompat.app.AlertDialog;
 import androidx.core.app.ActivityCompat;
 import androidx.core.graphics.Insets;
 import androidx.core.view.ViewCompat;
@@ -63,6 +67,10 @@ import org.json.JSONObject;
       },
       alias = CameraPreview.CAMERA_WITH_LOCATION_PERMISSION_ALIAS
     ),
+    @Permission(
+      strings = { RECORD_AUDIO },
+      alias = CameraPreview.MICROPHONE_ONLY_PERMISSION_ALIAS
+    ),
   }
 )
 public class CameraPreview
@@ -110,6 +118,7 @@ public class CameraPreview
   static final String CAMERA_ONLY_PERMISSION_ALIAS = "cameraOnly";
   static final String CAMERA_WITH_LOCATION_PERMISSION_ALIAS =
     "cameraWithLocation";
+  static final String MICROPHONE_ONLY_PERMISSION_ALIAS = "microphoneOnly";
 
   private String captureCallbackId = "";
   private String sampleCallbackId = "";
@@ -127,6 +136,7 @@ public class CameraPreview
   private String lastOrientationStr = "unknown";
   private boolean lastDisableAudio = true;
   private Drawable originalWindowBackground;
+  private boolean isCameraPermissionDialogShowing = false;
 
   @PluginMethod
   public void getExposureModes(PluginCall call) {
@@ -738,6 +748,207 @@ public class CameraPreview
     call.resolve(jsObject);
   }
 
+  private void showCameraPermissionDialog(
+    String title,
+    String message,
+    String openSettingsText,
+    String cancelText,
+    Runnable completion
+  ) {
+    Activity activity = getActivity();
+    if (activity == null) {
+      if (completion != null) {
+        completion.run();
+      }
+      return;
+    }
+
+    activity.runOnUiThread(() -> {
+      if (activity.isFinishing()) {
+        if (completion != null) {
+          completion.run();
+        }
+        return;
+      }
+
+      if (isCameraPermissionDialogShowing) {
+        if (completion != null) {
+          completion.run();
+        }
+        return;
+      }
+
+      AlertDialog dialog = new AlertDialog.Builder(activity)
+        .setTitle(title)
+        .setMessage(message)
+        .setNegativeButton(cancelText, (d, which) -> {
+          d.dismiss();
+          isCameraPermissionDialogShowing = false;
+        })
+        .setPositiveButton(openSettingsText, (d, which) -> {
+          Intent intent = new Intent(
+            Settings.ACTION_APPLICATION_DETAILS_SETTINGS
+          );
+          Uri uri = Uri.fromParts("package", activity.getPackageName(), null);
+          intent.setData(uri);
+          activity.startActivity(intent);
+          isCameraPermissionDialogShowing = false;
+        })
+        .setOnDismissListener(d -> isCameraPermissionDialogShowing = false)
+        .create();
+
+      isCameraPermissionDialogShowing = true;
+      dialog.show();
+      if (completion != null) {
+        completion.run();
+      }
+    });
+  }
+
+  private String mapPermissionState(PermissionState state) {
+    if (state == null) {
+      return PermissionState.PROMPT.toString();
+    }
+
+    return state.toString();
+  }
+
+  @PluginMethod
+  public void checkPermissions(PluginCall call) {
+    boolean disableAudio = call.getBoolean("disableAudio") != null
+      ? Boolean.TRUE.equals(call.getBoolean("disableAudio"))
+      : true;
+
+    PermissionState cameraState = getPermissionState(
+      CAMERA_ONLY_PERMISSION_ALIAS
+    );
+
+    JSObject result = new JSObject();
+    result.put("camera", mapPermissionState(cameraState));
+
+    if (!disableAudio) {
+      PermissionState audioState = getPermissionState(
+        MICROPHONE_ONLY_PERMISSION_ALIAS
+      );
+      result.put("microphone", mapPermissionState(audioState));
+    }
+
+    call.resolve(result);
+  }
+
+  @Override
+  @PluginMethod
+  public void requestPermissions(PluginCall call) {
+    Boolean disableAudioOption = call.getBoolean("disableAudio");
+    boolean disableAudio = disableAudioOption == null
+      ? true
+      : Boolean.TRUE.equals(disableAudioOption);
+    this.lastDisableAudio = disableAudio;
+
+    String permissionAlias = disableAudio
+      ? CAMERA_ONLY_PERMISSION_ALIAS
+      : CAMERA_WITH_AUDIO_PERMISSION_ALIAS;
+
+    boolean cameraGranted = PermissionState.GRANTED.equals(
+      getPermissionState(CAMERA_ONLY_PERMISSION_ALIAS)
+    );
+    boolean audioGranted =
+      disableAudio ||
+      PermissionState.GRANTED.equals(
+        getPermissionState(MICROPHONE_ONLY_PERMISSION_ALIAS)
+      );
+
+    if (cameraGranted && audioGranted) {
+      JSObject result = new JSObject();
+      result.put("camera", mapPermissionState(PermissionState.GRANTED));
+      if (!disableAudio) {
+        result.put("microphone", mapPermissionState(PermissionState.GRANTED));
+      }
+      call.resolve(result);
+      return;
+    }
+
+    requestPermissionForAlias(
+      permissionAlias,
+      call,
+      "handleRequestPermissionsResult"
+    );
+  }
+
+  @PermissionCallback
+  private void handleRequestPermissionsResult(PluginCall call) {
+    Boolean disableAudioOption = call.getBoolean("disableAudio");
+    boolean disableAudio = disableAudioOption == null
+      ? true
+      : Boolean.TRUE.equals(disableAudioOption);
+    this.lastDisableAudio = disableAudio;
+
+    PermissionState cameraState = getPermissionState(
+      CAMERA_ONLY_PERMISSION_ALIAS
+    );
+    JSObject result = new JSObject();
+    result.put("camera", mapPermissionState(cameraState));
+
+    if (!disableAudio) {
+      PermissionState audioState = getPermissionState(
+        CAMERA_WITH_AUDIO_PERMISSION_ALIAS
+      );
+      result.put("microphone", mapPermissionState(audioState));
+    }
+
+    boolean showSettingsAlert = call.getBoolean("showSettingsAlert") != null
+      ? Boolean.TRUE.equals(call.getBoolean("showSettingsAlert"))
+      : false;
+
+    String cameraStateString = result.getString("camera");
+    boolean cameraNeedsSettings =
+      "denied".equals(cameraStateString) ||
+      "prompt-with-rationale".equals(cameraStateString);
+
+    boolean microphoneNeedsSettings = false;
+    if (result.has("microphone")) {
+      String micStateString = result.getString("microphone");
+      microphoneNeedsSettings =
+        "denied".equals(micStateString) ||
+        "prompt-with-rationale".equals(micStateString);
+    }
+
+    boolean shouldShowAlert =
+      showSettingsAlert && (cameraNeedsSettings || microphoneNeedsSettings);
+
+    if (shouldShowAlert) {
+      Activity activity = getActivity();
+      if (activity == null) {
+        call.resolve(result);
+        return;
+      }
+
+      String title = call.getString("title", "Camera Permission Needed");
+      String message = call.getString(
+        "message",
+        "Enable camera access in Settings to use the preview."
+      );
+      String openSettingsText = call.getString(
+        "openSettingsButtonTitle",
+        "Open Settings"
+      );
+      String cancelText = call.getString(
+        "cancelButtonTitle",
+        activity.getString(android.R.string.cancel)
+      );
+
+      showCameraPermissionDialog(
+        title,
+        message,
+        openSettingsText,
+        cancelText,
+        () -> call.resolve(result)
+      );
+    } else {
+      call.resolve(result);
+    }
+  }
+
   @PermissionCallback
   private void handleCameraPermissionResult(PluginCall call) {
     if (
@@ -750,7 +961,10 @@ public class CameraPreview
     ) {
       startCamera(call);
     } else {
-      call.reject("Permission failed");
+      call.reject(
+        "camera permission denied. enable camera access in Settings.",
+        "cameraPermissionDenied"
+      );
     }
   }
 
@@ -2016,6 +2230,7 @@ public class CameraPreview
     boolean disableAudio = call.getBoolean("disableAudio") != null
       ? Boolean.TRUE.equals(call.getBoolean("disableAudio"))
       : this.lastDisableAudio;
+    this.lastDisableAudio = disableAudio;
     String permissionAlias = disableAudio
       ? CAMERA_ONLY_PERMISSION_ALIAS
       : CAMERA_WITH_AUDIO_PERMISSION_ALIAS;
@@ -2097,7 +2312,10 @@ public class CameraPreview
         call.reject("Failed to start video recording: " + e.getMessage());
       }
     } else {
-      call.reject("Permission denied for video recording");
+      call.reject(
+        "camera permission denied. enable camera access in Settings.",
+        "cameraPermissionDenied"
+      );
     }
   }
 

package/dist/docs.json

@@ -247,6 +247,71 @@
         ],
         "slug": "getgridmode"
       },
+      {
+        "name": "checkPermissions",
+        "signature": "(options?: Pick<PermissionRequestOptions, \"disableAudio\"> | undefined) => Promise<CameraPermissionStatus>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "Set `disableAudio` to `false` to also include microphone status (defaults to `true`).",
+            "type": "Pick<PermissionRequestOptions, 'disableAudio'> | undefined"
+          }
+        ],
+        "returns": "Promise<CameraPermissionStatus>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options Set `disableAudio` to `false` to also include microphone status (defaults to `true`)."
+          },
+          {
+            "name": "returns",
+            "text": "A promise resolving to the current authorization states."
+          },
+          {
+            "name": "since",
+            "text": "8.7.0"
+          }
+        ],
+        "docs": "Checks the current camera (and optionally microphone) permission status without prompting the system dialog.",
+        "complexTypes": [
+          "CameraPermissionStatus",
+          "Pick",
+          "PermissionRequestOptions"
+        ],
+        "slug": "checkpermissions"
+      },
+      {
+        "name": "requestPermissions",
+        "signature": "(options?: PermissionRequestOptions | undefined) => Promise<CameraPermissionStatus>",
+        "parameters": [
+          {
+            "name": "options",
+            "docs": "- Configuration for the permission request behaviour.",
+            "type": "PermissionRequestOptions | undefined"
+          }
+        ],
+        "returns": "Promise<CameraPermissionStatus>",
+        "tags": [
+          {
+            "name": "param",
+            "text": "options - Configuration for the permission request behaviour."
+          },
+          {
+            "name": "returns",
+            "text": "A promise resolving to the final authorization states."
+          },
+          {
+            "name": "since",
+            "text": "8.7.0"
+          }
+        ],
+        "docs": "Requests camera (and optional microphone) permissions. If permissions are already granted or denied,\nthe current status is returned without prompting. When `showSettingsAlert` is true and permissions are denied,\na platform specific alert guiding the user to the app settings will be presented.",
+        "complexTypes": [
+          "CameraPermissionStatus",
+          "PermissionRequestOptions"
+        ],
+        "slug": "requestpermissions"
+      },
       {
         "name": "getHorizontalFov",
         "signature": "() => Promise<{ result: number; }>",
@@ -1504,6 +1569,84 @@
         }
       ]
     },
+    {
+      "name": "CameraPermissionStatus",
+      "slug": "camerapermissionstatus",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "camera",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [
+            "PermissionState"
+          ],
+          "type": "PermissionState"
+        },
+        {
+          "name": "microphone",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [
+            "PermissionState"
+          ],
+          "type": "PermissionState"
+        }
+      ]
+    },
+    {
+      "name": "PermissionRequestOptions",
+      "slug": "permissionrequestoptions",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "disableAudio",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
+        {
+          "name": "showSettingsAlert",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
+        {
+          "name": "title",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "message",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "openSettingsButtonTitle",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string | undefined"
+        },
+        {
+          "name": "cancelButtonTitle",
+          "tags": [],
+          "docs": "",
+          "complexTypes": [],
+          "type": "string | undefined"
+        }
+      ]
+    },
     {
       "name": "SupportedPictureSizes",
       "slug": "supportedpicturesizes",
@@ -1909,6 +2052,44 @@
         }
       ]
     },
+    {
+      "name": "PermissionState",
+      "slug": "permissionstate",
+      "docs": "",
+      "types": [
+        {
+          "text": "'prompt'",
+          "complexTypes": []
+        },
+        {
+          "text": "'prompt-with-rationale'",
+          "complexTypes": []
+        },
+        {
+          "text": "'granted'",
+          "complexTypes": []
+        },
+        {
+          "text": "'denied'",
+          "complexTypes": []
+        }
+      ]
+    },
+    {
+      "name": "Pick",
+      "slug": "pick",
+      "docs": "From T, pick a set of properties whose keys are in the union K",
+      "types": [
+        {
+          "text": "{\r\n    [P in K]: T[P];\r\n}",
+          "complexTypes": [
+            "K",
+            "T",
+            "P"
+          ]
+        }
+      ]
+    },
     {
       "name": "FlashMode",
       "slug": "flashmode",

package/dist/esm/definitions.d.ts

@@ -1,8 +1,20 @@
-import type { PluginListenerHandle } from "@capacitor/core";
+import type { PermissionState, PluginListenerHandle } from "@capacitor/core";
 export type CameraPosition = "rear" | "front";
 export type FlashMode = CameraPreviewFlashMode;
 export type GridMode = "none" | "3x3" | "4x4";
 export type CameraPositioning = "center" | "top" | "bottom";
+export interface CameraPermissionStatus {
+    camera: PermissionState;
+    microphone?: PermissionState;
+}
+export interface PermissionRequestOptions {
+    disableAudio?: boolean;
+    showSettingsAlert?: boolean;
+    title?: string;
+    message?: string;
+    openSettingsButtonTitle?: string;
+    cancelButtonTitle?: string;
+}
 export declare enum DeviceType {
     ULTRA_WIDE = "ultraWide",
     WIDE_ANGLE = "wideAngle",
@@ -443,6 +455,24 @@ export interface CameraPreviewPlugin {
     getGridMode(): Promise<{
         gridMode: GridMode;
     }>;
+    /**
+     * Checks the current camera (and optionally microphone) permission status without prompting the system dialog.
+     *
+     * @param options Set `disableAudio` to `false` to also include microphone status (defaults to `true`).
+     * @returns {Promise<CameraPermissionStatus>} A promise resolving to the current authorization states.
+     * @since 8.7.0
+     */
+    checkPermissions(options?: Pick<PermissionRequestOptions, "disableAudio">): Promise<CameraPermissionStatus>;
+    /**
+     * Requests camera (and optional microphone) permissions. If permissions are already granted or denied,
+     * the current status is returned without prompting. When `showSettingsAlert` is true and permissions are denied,
+     * a platform specific alert guiding the user to the app settings will be presented.
+     *
+     * @param {PermissionRequestOptions} options - Configuration for the permission request behaviour.
+     * @returns {Promise<CameraPermissionStatus>} A promise resolving to the final authorization states.
+     * @since 8.7.0
+     */
+    requestPermissions(options?: PermissionRequestOptions): Promise<CameraPermissionStatus>;
     /**
      * Gets the horizontal field of view (FoV) for the active camera.
      * Note: This can be an estimate on some devices.