Settings

The app is configured by a single JSON document encoded into a QR code. When the app scans that QR code, it applies and stores the settings.

Use the settings configurator

The easiest way to produce a valid settings QR code is the settings configurator — fill in the fields, get the QR code, scan it. No JSON authoring, and it cannot produce a document the app will silently ignore.

Writing the JSON by hand stays fully supported — the format below is public and stable. This page is the reference for it.

Document shape#

{  "app": "scan2check.com",  "settings": {    "apiUrl": "https://example.com/scanner/"  }}

app — must be exactly the string scan2check.com. If it is missing or different, the app does not recognise the QR code as settings at all and silently ignores it. This is the single most common first-run mistake.
settings — the settings object. A document with no settings key is still a valid settings QR code; it simply applies nothing.

Defaults at a glance#

Field	Type	Default	Notes
`apiUrl`	string	`""` (unset)	`http://` is allowed
`apiUrlOpened`	string	unset	app-opened / update-requested endpoint
`apiTimeout`	integer (ms)	`3000`	values below 3000 are clamped up to 3000
`autoScanTimeout`	integer (ms)	`-1000`	any negative value = disabled
`symbols`	array of string	all nine	unknown ids dropped; QR always enabled
`soundSuccess`	string	`beep2`
`soundFailed`	string	`doubleBeep2`
`headers`	object (string → text)	`{}`	numbers and booleans are sent as text; objects/arrays dropped
`showUpdateButton`	boolean or `"true"`	`false`	needs `apiUrlOpened` to appear
`formData`	object `{schema, showOnce}`	unset	`""` or `{}` removes the form

Fields#

apiUrl#

The endpoint every scanned code is POSTed to. "", null and an absent key all mean unset.

http:// URLs are legal and deliberately supported for on-premise networks — the configurator warns about them, but never blocks them.

apiUrlOpened#

The endpoint called for application-opened / update-requested events. See On app opened for a working example.

apiTimeout#

Request timeout in milliseconds. Default 3000. Values below 3000 are silently clamped up to 3000 — setting apiTimeout: 500 gives you 3000 ms, not 500. A non-numeric or absent value also yields 3000.

autoScanTimeout#

Controls whether the scanner restarts by itself after the ok/failed status screen. Default -1000.

any negative value (-1, -1000, …) — disabled; the user must tap the Scan button.
0 — the status screen is skipped entirely and the camera comes straight back.
positive N — the status screen is shown, counts down N milliseconds, then the scanner auto-launches (800 = 0.8 s).

symbols#

An allowlist of symbologies to recognise; everything else is ignored. The only nine valid ids, in this order:

code39, code93, code128, ean8, ean13, pdf417, qr, upce, datamatrix

Unknown ids are dropped silently — no error is shown.
If the array is absent, empty, or every id in it is unknown, all nine are used.
QR is force-enabled in the scanner regardless of this list, so a settings QR code can always be scanned. That also means QR appearing in scan results is expected even when you left it out.
Omitting the key keeps whatever allowlist the device already stores — the merge is shallow. To hand a device back all nine, send an empty array: "symbols": [].

soundSuccess#

Sound played on a "success" API response. Default beep2. Valid ids (note the camelCase): beep1, beep2, doubleBeep1, doubleBeep2.

soundFailed#

Sound played on a "failed" API response. Default doubleBeep2. Same valid ids as above.

headers#

An object of custom HTTP headers added to every API request, e.g. an API key. Any JSON primitive value is accepted and sent as its text — "X-Tenant": 42 arrives as the header value 42, and true as true. Only entries whose value is an object or an array are dropped.

"headers": {  "X-API-KEY": "123456",  "X-CUSTOM-VALUE": "789101112"}

Headers are secrets

Header values are usually API keys. The configurator never puts headers into a shareable link — copy a link and the headers are stripped out. Treat a settings QR code that carries headers as a credential.

showUpdateButton#

Shows the UPDATE button on the home screen. Accepts the boolean true or the string "true". Default false. The button only actually appears when apiUrlOpened is also set, since it triggers a settings-update request to that endpoint.

formData#

Defines the custom form collected with each scan. It is an object:

"formData": {  "schema": { "...": "..." },  "showOnce": false}

schema — the form fields; see Custom Form.
showOnce — when true, the form is shown once and never persisted to the device.
"", {}, or an object with no usable schema removes the form.

Updating a setting#

A scanned settings QR code is shallow-merged over what the device already stores. Keys you leave out keep their previous value, so a QR code can be a partial update:

{  "app": "scan2check.com",  "settings": {    "apiUrl": "https://some.other.url"  }}

This does not remove any other previously stored setting.

Removing a setting#

Set the key to an empty string to clear it:

{  "app": "scan2check.com",  "settings": {    "formData": ""  }}

The example above removes the formData setting, so no form is shown after a code is scanned.