Scanner API

Examples

• Description

  Build a scan-and-verify workflow. Open the camera on mount, send scanned data to a backend for validation, and show loading, success, or error states. Hide the camera during verification and restore it when the user taps **Scan next**.

  jsx

  import {render} from 'preact';
  import {useState, useEffect, useRef} from 'preact/hooks';
  
  export default async () => {
    render(<Extension />, document.body);
  };
  
  const Extension = () => {
    const [state, setState] = useState('scanning'); // scanning | loading | success | error
    const [errorMessage, setErrorMessage] = useState('');
    const lastScannedRef = useRef('');
  
    useEffect(() => {
      shopify.scanner.showCameraScanner();
  
      const unsubscribe = shopify.scanner.scannerData.current.subscribe(
        async (scan) => {
          if (!scan.data || scan.data === lastScannedRef.current) {
            return;
          }
  
          lastScannedRef.current = scan.data;
          setState('loading');
          shopify.scanner.hideCameraScanner();
  
          try {
            // Replace with your actual backend verification call
            // const response = await fetch(`/api/verify?code=${scan.data}`);
            // const data = await response.json();
            // const valid = data.valid;
            const valid = true;
  
            if (valid) {
              setState('success');
              shopify.toast.show('Verified');
            } else {
              setErrorMessage('Code is not valid');
              setState('error');
            }
          } catch {
            setErrorMessage('Network error. Try again.');
            setState('error');
          }
        },
      );
  
      return () => {
        unsubscribe();
        shopify.scanner.hideCameraScanner();
      };
    }, []);
  
    const resetScanner = () => {
      lastScannedRef.current = '';
      setErrorMessage('');
      setState('scanning');
      shopify.scanner.showCameraScanner();
    };
  
    if (state === 'loading') {
      return (
        <s-page heading="Verifying...">
          <s-stack direction="block" block-alignment="center">
            <s-spinner />
          </s-stack>
        </s-page>
      );
    }
  
    if (state === 'success') {
      return (
        <s-page heading="Verified">
          <s-stack direction="block" gap="small">
            <s-banner heading="Code accepted" tone="success" />
            <s-button onClick={resetScanner}>Scan next</s-button>
          </s-stack>
        </s-page>
      );
    }
  
    if (state === 'error') {
      return (
        <s-page heading="Error">
          <s-stack direction="block" gap="small">
            <s-banner heading={errorMessage} tone="critical" />
            <s-button onClick={resetScanner}>Try again</s-button>
          </s-stack>
        </s-page>
      );
    }
  
    // state === 'scanning' — camera overlay is shown by showCameraScanner()
    return <s-page heading="Scan a code" />;
  };

• Description

  Subscribe to `shopify.scanner.sources.current` to detect which scanner hardware is available (camera, external, or embedded) and to `shopify.scanner.scannerData.current` to receive scan results. By identifying the scanner type, you can customize handling based on the scanning method.

  jsx

  import {render} from 'preact';
  import {useState, useEffect} from 'preact/hooks';
  
  export default async () => {
    render(<Extension />, document.body);
  };
  
  const Extension = () => {
    const [scanData, setScanData] = useState('');
    const [scanSource, setScanSource] = useState('');
    const [hasCameraScanner, setHasCameraScanner] = useState(false);
    const [hasExternalScanner, setHasExternalScanner] = useState(false);
  
    useEffect(() => {
      // This example doesn't call showCameraScanner(). Scan data
      // arrives from external/embedded scanners, or from the camera
      // if opened elsewhere — scannerData is shared globally.
      const unsubscribeData = shopify.scanner.scannerData.current.subscribe((result) => {
        setScanData(result.data || '');
        setScanSource(result.source || '');
      });
  
      const unsubscribeSources = shopify.scanner.sources.current.subscribe((sources) => {
        setHasCameraScanner(sources.includes('camera'));
        setHasExternalScanner(sources.includes('external'));
      });
  
      return () => {
        unsubscribeData();
        unsubscribeSources();
      };
    }, []);
  
    return (
      <s-page heading="Scanner Example">
        <s-stack direction="block">
          <s-text>Scanned data: {scanData}</s-text>
          <s-text>Scanned data source: {scanSource}</s-text>
          {hasCameraScanner && (
            <s-text>Camera scanner is available</s-text>
          )}
          {hasExternalScanner && (
            <s-text>External scanner is available</s-text>
          )}
        </s-stack>
      </s-page>
    );
  };