Pair and set up the app¶
Connect the mobile app to your company's installation using a QR code — or enter the API URL manually if QR isn't available.
Required role
Any mobile-enabled role (Technician, Mapper, Admin, PegotecUser).
Overview¶
Before you can sign in, the mobile app needs to know which installation to talk to. Every company has its own API URL (for example, api.customer.sm-tm.app). Pairing the app sets that URL and optionally a company context.
Two pairing methods:
- QR code (recommended) — your Admin generates a QR code from the web portal; you scan it; the app configures itself in one step.
- Manual entry — for cases where QR isn't practical: low-bandwidth site, unusual device, or you're helping someone remotely.
Once paired, the app remembers the configuration until you factory-reset it.
Prerequisites¶
- The app is installed on your device. See Installing the app.
- Your Admin has:
- Created an account for you.
- Given you credentials (email / username + password), and either:
- Generated a QR code (from Mobile Setup on the web portal), or
- Given you the API URL in writing.
Pair using a QR code¶
1. Open the app¶
Tap the app icon. On first launch you see the Setup screen with two buttons: Scan QR code and Enter URL manually.
2. Grant camera permission¶
Tap Scan QR code. If this is the first camera use, the OS asks for camera permission — tap Allow.
3. Scan the code¶
Point the camera at the QR code on your Admin's web portal screen (or a printed copy). Hold steady for a second.
The app decodes the QR, which contains:
- The API URL (e.g.
https://api.customer.sm-tm.app). - (Optional) A company context if your organisation runs multiple companies on one installation.
4. Confirm the configuration¶
The app shows a summary: the server name and — if the QR included one — the company. Tap Continue.
5. Sign in¶
You land on the login screen. Enter your email (or username) and password, tap Sign in.
If your Admin included a pre-filled username in the QR code, the field is already filled — just enter your password.
6. Wait for the initial sync¶
After sign-in, the app downloads your slice of the hierarchy, your assigned tasks, master data, and the translation bundle for your language. The progress bar shows how far along you are. This typically takes 30–90 seconds on a good connection.
7. Set up biometric unlock¶
Once the initial sync finishes, you're prompted to set up biometric unlock. See Biometric unlock — it's strongly recommended.
You're paired. The Dashboard opens.
Pair manually (no QR code)¶
1. Open the app → Setup screen¶
Tap Enter URL manually.
2. Enter the API URL¶
Type the URL exactly as your Admin gave it to you. Include the scheme (https://).
The app validates the URL by pinging the server's health endpoint. If the URL is unreachable, you see an error — double-check typos and try again.
3. Continue through sign-in and initial sync¶
Same as steps 5–7 above.
Re-pairing after a factory reset¶
If you've reset the app and need to pair again:
- The app returns to the Setup screen automatically.
- Scan the QR code (or enter the URL) as before.
- Sign in.
All your drafts and cached data are cleared by a factory reset. Make sure you've submitted everything before you reset.
Changing which installation you're connected to¶
Switching installations is rare — it usually only happens when:
- A customer moves from staging to production (they've been beta-testing a new deployment).
- A field technician is temporarily loaned to a different site.
The only way to switch is to factory-reset the app and pair again:
- Settings → Factory reset → Confirm.
- Re-pair with the new QR or URL.
Factory reset destroys unsynced work
Any drafts that haven't uploaded are lost. Check Pending uploads = 0 before resetting.
What the app stores after pairing¶
| Item | Where | Cleared by |
|---|---|---|
| API URL | Encrypted keychain | Factory reset |
| Company context | Encrypted keychain | Factory reset |
| Access token | Encrypted keychain | Sign-out or factory reset |
| Cached data (hierarchy, tasks, translations, master data) | Encrypted on-device storage | Sign-out or factory reset |
| Photos queued for upload | Encrypted local storage | Sign-out or factory reset |
Troubleshooting¶
| Problem | Likely cause | Fix |
|---|---|---|
| QR code won't scan | Camera can't focus, or the code is too small on the screen | Move closer, zoom in on the web portal, or ask for a larger printed copy |
| "Couldn't reach the server" | URL typo, or the server is down | Double-check the URL; open it in a browser to confirm it responds |
| "Invalid configuration" | The QR code is malformed or from a different platform | Get a fresh QR from your Admin's Mobile Setup page |
| Stuck on initial sync | Slow network, or a very large hierarchy | Stay on Wi-Fi; be patient (can take 2+ minutes for large sites); close and reopen if it's been 5+ minutes |
| Login fails after pairing | Wrong credentials, or your account belongs to a different installation | Confirm with your Admin that your account is on this installation |
See I can't log in for more.