Merge pull request #3645 from Shopify/20646-camera-api-docs

20646: Add camera API docs

Author: andy-chhuon

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/camera-api.doc.ts

@@ -0,0 +1,71 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {generateJsxCodeBlock} from '../helpers/generateCodeBlock';
+
+const generateJsxCodeBlockForCameraApi = (title: string, fileName: string) =>
+  generateJsxCodeBlock(title, 'camera-api', fileName);
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Camera API',
+  description:
+    "The Camera API provides access to the device's camera, enabling photo capture directly within POS UI extensions. The API requests camera permissions if not already enabled, opens the native camera interface, and returns the image data including dimensions, file size, and base64 string for immediate display or server upload.",
+  isVisualComponent: false,
+  type: 'APIs',
+  definitions: [
+    {
+      title: 'CameraApi',
+      description:
+        'The `CameraApi` object provides methods for capturing photos using the device camera. Access these methods through `shopify.camera` to take photos and retrieve image data with metadata.',
+      type: 'CameraApiContent',
+    },
+  ],
+  category: 'Target APIs',
+  subCategory: 'Standard APIs',
+  subSections: [
+    {
+      type: 'Generic',
+      anchorLink: 'best-practices',
+      title: 'Best practices',
+      sectionContent: `
+- **Optimize image quality:** Use appropriate quality and size settings to balance image quality with file size and upload performance.
+- **Provide feedback:** Show loading states while processing images and clear success/error messages after capture.
+- **Handle errors gracefully:** Account for scenarios where users cancel, camera is unavailable, or permissions are denied.
+`,
+    },
+    {
+      type: 'Generic',
+      anchorLink: 'limitations',
+      title: 'Limitations',
+      sectionContent: `
+- Camera functionality requires the device to have a camera and appropriate permissions granted by the user.
+- Only one camera operation can be in progress at a time. Attempting to call \`takePhoto()\` while a capture is already in progress will result in a rejected promise.
+- Base64 strings can be memory-intensive for large images. Use appropriate \`maxWidth\`, \`maxHeight\`, and \`quality\` settings to optimize performance.
+- The \`facingMode\` parameter may not behave consistently on all Android devices, because camera-facing behavior varies across manufacturers. If a requested mode isn't supported, the rear-facing camera is used by default, and users can still manually switch cameras from the camera interface.
+`,
+    },
+  ],
+  related: [],
+  examples: {
+    description:
+      'Learn how to capture photos using the device camera and handle the resulting image data.',
+    examples: [
+      {
+        codeblock: generateJsxCodeBlockForCameraApi(
+          'Capture and upload photo to server',
+          'take-photo-upload',
+        ),
+        description:
+          'This example demonstrates capturing a photo using `shopify.camera.takePhoto()` and uploading it to a backend server for further processing. It shows loading states during capture and upload, handles errors appropriately, and confirms successful upload with toast notifications.',
+      },
+      {
+        codeblock: generateJsxCodeBlockForCameraApi(
+          'Capture and display a photo',
+          'take-photo-display',
+        ),
+        description:
+          'This example demonstrates using `shopify.camera.takePhoto()` to capture an image with the device camera and displaying it immediately using the `image` component.',
+      },
+    ],
+  },
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/camera-api/take-photo-display.jsx

@@ -0,0 +1,55 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+const Extension = () => {
+  const [imageData, setImageData] = useState(null);
+  const [isCapturing, setIsCapturing] = useState(false);
+
+  const handleTakePhoto = async () => {
+    setIsCapturing(true);
+    try {
+      const photo = await shopify.camera.takePhoto();
+      setImageData(photo);
+      shopify.toast.show('Photo captured successfully!');
+    } catch (error) {
+      // skip showing errors when the user cancels the photo capture.
+      if (!error.message.includes('User cancelled')) {
+        shopify.toast.show(`Error: ${error.message}`);
+      }
+    } finally {
+      setIsCapturing(false);
+    }
+  };
+
+  return (
+    <s-page heading="Camera Capture">
+      <s-scroll-box>
+        <s-stack>
+          <s-button onClick={handleTakePhoto} disabled={isCapturing}>
+            {isCapturing ? 'Capturing...' : 'Take Photo'}
+          </s-button>
+
+          {imageData && (
+            <>
+              <s-image
+                src={`data:${imageData.type};base64,${imageData.base64}`}
+              />
+              <s-section heading="Image Details">
+                <s-text>Width: {imageData.width}px</s-text>
+                <s-text>Height: {imageData.height}px</s-text>
+                <s-text>
+                  File Size: {(imageData.fileSize / 1024).toFixed(2)} KB
+                </s-text>
+                <s-text>Type: {imageData.type}</s-text>
+              </s-section>
+            </>
+          )}
+        </s-stack>
+      </s-scroll-box>
+    </s-page>
+  );
+};

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/camera-api/take-photo-upload.jsx

@@ -0,0 +1,46 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+const Extension = () => {
+  const [isProcessing, setIsProcessing] = useState(false);
+
+  const handleCaptureAndUpload = async () => {
+    setIsProcessing(true);
+    try {
+      const photo = await shopify.camera.takePhoto({
+        quality: 0.8,
+        maxWidth: 1520,
+        maxHeight: 1520,
+      });
+
+      // Upload the image to your backend server
+      // (Replace with your actual backend endpoint)
+      await fetch('https://your-backend.com/api/upload', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({
+          image: photo.base64,
+          mimeType: photo.type,
+        }),
+      });
+
+      shopify.toast.show('Photo uploaded successfully!');
+    } catch (error) {
+      shopify.toast.show(`Error: ${error.message}`);
+    } finally {
+      setIsProcessing(false);
+    }
+  };
+
+  return (
+    <s-tile
+      heading="Upload Photo"
+      onClick={handleCaptureAndUpload}
+      disabled={isProcessing}
+    />
+  );
+};

packages/ui-extensions/src/surfaces/point-of-sale/api/camera-api/camera-api.ts

@@ -1,3 +1,6 @@
+/**
+ * Specifies configuration options for capturing photos using the device camera.
+ */
 export interface CameraMediaOptions {
   /**
    * The camera that will be active when the camera interface first opens.
@@ -24,6 +27,9 @@ export interface CameraMediaOptions {
   quality?: number;
 }
 
+/**
+ * Represents the captured image and associated metadata returned by `shopify.camera.takePhoto()`.
+ */
 export interface CameraMediaResponse {
   /** The image data as base64 string. */
   base64: string;
@@ -37,6 +43,9 @@ export interface CameraMediaResponse {
   type: string;
 }
 
+/**
+ * Provides camera capabilities for the POS device.
+ */
 export interface CameraApiContent {
   /**
    * Launch the device's camera to take a photo.
@@ -51,6 +60,10 @@ export interface CameraApiContent {
   takePhoto: (options?: CameraMediaOptions) => Promise<CameraMediaResponse>;
 }
 
+/**
+ * The `CameraApi` object provides access to device camera functionality for capturing photos.
+ * Access these properties through `shopify.camera`.
+ */
 export interface CameraApi {
   camera: CameraApiContent;
 }