Format

QR code format

For backends that create their own QR codes. A QR code is a link with the settings after the #. Browsers don't send anything after # to the server. The link must start with exactly https://tracker.iwi.tw/setup.html; with any other domain or path, the app rejects it as not a GeoCourier setup code.

https://tracker.iwi.tw/setup.html#<format>.<data>.<check>

format

1: plain; 2: encrypted with a password. The app asks the user to update when it sees a format it doesn't know.

data

Format 1: the settings JSON as UTF-8, base64url-encoded (no = padding). Format 2: see below.

check

The first 8 lowercase hex characters of the SHA-256 of "<format>.<data>". If the link was cut off or altered, it won't match and the app won't import it.

Settings JSON

t

Title. Required.

u

URL. Required. https://; http:// only for localhost, 127.0.0.1, and 10.0.2.2 (debug builds of the app).

m

Method. Only written for PUT; omitted means POST.

h

Headers, [[key, value], …] in order. Omitted if none.

n

Note. Omitted if empty.

Fields are checked the same way as in the app's server editor. If any field fails, nothing is imported. The one exception is a title that already exists on the phone: it isn't rejected, and the app appends (2), (3), and so on. Unknown keys are ignored. Imported servers are always enabled, and importing isn't available while tracking. One QR code holds one server and no capture settings.

Format 2: encrypted with a password

A 256-bit key is derived with PBKDF2-HMAC-SHA256 (password NFC-normalized and UTF-8 encoded, 16-byte random salt, 600,000 iterations), and the settings JSON is encrypted with AES-GCM (12-byte random IV). <data> is the base64url of the salt, IV, ciphertext, and authentication tag, in that order. Use only ASCII letters, digits, and symbols (! to ~, no spaces) in the password: phone password fields often can't type other characters.

Example

{"t":"Example Server","u":"https://api.example.com/v1/tracker","h":[["X-Api-Key","f0bb877b43ef7e5880a51405f415e99c"]]}

https://tracker.iwi.tw/setup.html#1.eyJ0IjoiRXhhbXBsZSBTZXJ2ZXIiLCJ1IjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdjEvdHJhY2tlciIsImgiOltbIlgtQXBpLUtleSIsImYwYmI4NzdiNDNlZjdlNTg4MGE1MTQwNWY0MTVlOTljIl1dfQ.2afe2593

The link length depends almost entirely on the token. For QR codes you plan to post, use an API key or a short JWT.