Skip to main content
Version: v3000

Customize the scanning UI

The BlinkCard scanning UI is configurable on every platform.

On the web, the UI is configured through two option groups passed to createBlinkCard:

  • feedbackUiOptions: the scanning feedback layer (onboarding, help, timeout modal, instruction text)
  • cameraManagerUiOptions: the camera controls (torch, close, mirror buttons, and layering)

On Android and iOS, the UI is configured through settings objects passed to the scanning entry point.

Where the UI is mounted (web)​

By default the UI mounts full-screen into document.body. To embed it inside your own layout, pass targetNode:

const blinkCard = await createBlinkCard({
  licenseKey: "your-license-key",
  targetNode: document.getElementById("scanner-container") ?? undefined,
});

When you provide a targetNode, the UI fills that element instead of the whole screen, so it sits within your page's branding.

Onboarding and help​

Toggle the onboarding guide shown before scanning starts and the help button shown during scanning.

On the web, these live in feedbackUiOptions, passed to createBlinkCard.

const blinkCard = await createBlinkCard({
  licenseKey: "your-license-key",
  feedbackUiOptions: {
    showOnboardingGuide: false,
    showHelpButton: false,
    showTimeoutModal: true,
    helpTooltipShowDelay: 5000,
    helpTooltipHideDelay: 5000,
  },
});
  • showOnboardingGuide: show the onboarding guide before scanning starts (default true)
  • showHelpButton: show the help button (default true)
  • helpTooltipShowDelay: milliseconds before the help tooltip appears automatically, or null to never auto-show (default 5000)
  • helpTooltipHideDelay: milliseconds before the help tooltip auto-hides, or null to never auto-hide (default 5000)
  • showTimeoutModal: show the modal when scanning times out (default true)

Camera controls​

On the web, the camera controls live in cameraManagerUiOptions.

const blinkCard = await createBlinkCard({
  licenseKey: "your-license-key",
  cameraManagerUiOptions: {
    showTorchButton: true,
    showCloseButton: true,
    showMirrorCameraButton: false,
    showCameraErrorModal: true,
  },
});
  • showTorchButton: show the torch (flashlight) toggle when the device supports it (default true)
  • showCloseButton: show the close button (default true)
  • showMirrorCameraButton: show the mirror-camera button (default false)
  • showCameraErrorModal: show a modal on camera errors such as denied permission (default true)
  • zIndex: the stacking order when the UI renders as a full-screen overlay (only applies when no targetNode is set)

Customize the instruction text​

On the web, both option groups accept localizationStrings to override the on-screen messages. Pass only the keys you want to change; the rest fall back to the built-in copy.

const blinkCard = await createBlinkCard({
  licenseKey: "your-license-key",
  feedbackUiOptions: {
    localizationStrings: {
      flip_card: "Turn the card over",
    },
  },
});

To translate the whole UI into another language, override the full set of strings. The SDK ships with several built-in locales; see Supported languages.

Last updated on