Scanning QR codes

Permission: camera.scan. Opens the app's native full-screen scanner over your page. Your page stays loaded underneath.

import { getSDKErrorCode, hasBridgeMethod, parseICatholicQr, scanQr } from '@i-catholic/mini-app-sdk'

const canScan = hasBridgeMethod('scanQr') // hide the "Scan" button when false

try {
  const scanned = await scanQr({ title: 'Quét mã QR lớp học' }) // null when the user cancels
  if (scanned) {
    const qr = parseICatholicQr(scanned.text)
    switch (qr.kind) {
      case 'app-link':    /* qr.type, qr.path, qr.url — https://i-catholic.org/app/{type}/… */ break
      case 'scheme-link': /* qr.path, qr.url — catholic://… */ break
      case 'member-id':   /* qr.documentId — a member QR (bare id) */ break
      case 'other':       /* qr.text — anything else */ break
    }
  }
} catch (e) {
  switch (getSDKErrorCode(e)) {
    case 'UNSUPPORTED':        // outside the app, or this app version cannot scan yet
    case 'PERMISSION_DENIED':  // the user refused camera.scan for your mini app
    case 'CAMERA_UNAVAILABLE': // the OS camera permission is off, or your mini app is not the visible screen
    case 'BUSY':               // a scan is already open
    case 'INVALID_PARAMS':     // title longer than 60 characters
    case 'TIMEOUT':            // no result within 10 minutes
  }
}

• Cancel is not an error. Closing the scanner resolves null.
• You get the raw string. The app never interprets, filters or follows what was scanned. An i-Catholic link scanned in your mini app is returned to you and not opened automatically.
• title (optional, plain text) appears in the scanner header. Whitespace (including newlines) folds to single spaces, and the result may be at most 60 characters (SCAN_QR_TITLE_MAX_LENGTH; an emoji counts once). The header always names your mini app too, so the user knows who receives the code.
• Call it while your mini app is on screen. If another screen is on top, the app refuses with CAMERA_UNAVAILABLE.
• The timeout is long. The user has up to 10 minutes (SCAN_QR_TIMEOUT). The app closes the scanner just before that, so the camera is never left open.
• Use the scanQr() helper rather than sdk.scanQr(). The helper checks that the method exists (UNSUPPORTED) and validates title before calling the app.

parseICatholicQr(text) is a pure function that works anywhere, even outside the app. It recognises i-Catholic payloads by shape:

kind	Matches	Fields
app-link	http(s) URL on i-catholic.org or a subdomain, path under /app/ (query and hash ignored)	type, path[], url
scheme-link	catholic://…	path[], url
member-id	a bare id of 20–32 lowercase letters/digits	documentId
other	anything else, trimmed	text

Path segments are percent-decoded. Anything doubtful is classified as other: look-alike domains (i-catholic.org.evil.com), a user name, password or port in the URL, whitespace, backslashes or control characters, or a segment that decodes to contain /. A member-id match checks the shape only. It does not prove the member exists.