Phone apps (Android and iOS)

Artavolo works on phones in three ways:

• The browser. The table screen, interfaces and forms are laid out for phones: records become cards, and there is an add button.
• Installed from the browser. Chrome, Edge and Safari offer to install the site as an app. It has its own icon and window, and shows a "No connection" page when there is no network.
• From Google Play and the App Store. The apps in mobile/ put the same screens in a native shell. They add a home-screen icon, a splash screen, and links that open in the app.

The apps open the site itself, so they are always up to date. A change to Artavolo reaches the apps without a new release.

What is in mobile/

Building

You need Node 22. For Android you also need JDK 21 and the Android SDK (platform 35). For iOS you need a Mac with Xcode.

cd mobile
npm ci
node scripts/configure.mjs                  # artavolo.com, "Artavolo", com.artavolo.app
npx cap sync
cd android && ./gradlew assembleDebug       # app/build/outputs/apk/debug/app-debug.apk
npx cap open ios                            # then build and run in Xcode

Your own instance, or under your own name

A self-hosted or white-labelled instance gets its own app. Give it its own address, name and id, and redraw the icons from its own mark:

node scripts/configure.mjs --url https://tables.acme.eu --name "Acme Tables" --id eu.acme.tables
node scripts/icons.mjs path/to/acme-mark.svg "#ffffff"
npx cap sync

On GitHub, run the "Mobile apps" workflow by hand with the same three values.

Publishing

Google Play

1. Create a developer account at play.google.com/console. There is a one-time registration fee. Register as an organisation, which needs a D-U-N-S number. New personal accounts must first run a closed test with a group of testers for two weeks; check Google's current rules when you register.
2. Create a signing key and keep it outside the repository: keytool -genkeypair -v -keystore release.keystore -alias artavolo -keyalg RSA -keysize 2048 -validity 10000. Enrol the app in Play App Signing.
3. Build the App Bundle. You can do it locally, with ./gradlew bundleRelease and the signing properties. Or let the workflow do it: set these repository secrets, and the workflow builds the bundle too.
   • ANDROID_KEYSTORE_BASE64 (the keystore file, base64-encoded)
   • ANDROID_KEYSTORE_PASSWORD
   • ANDROID_KEY_ALIAS
   • ANDROID_KEY_PASSWORD
4. Make the links open in the app. In the Play Console, open App integrity and copy the app signing certificate's SHA-256 fingerprint. Set APP_ANDROID_ID and APP_ANDROID_SHA256 in includes/config.php. The site then serves /.well-known/assetlinks.json, and Android opens links to /base/…, /interface/… and /form/… in the app.

App Store

1. Join the Apple Developer Program as an organisation (a yearly fee, and a D-U-N-S number).
2. Set up the app in Xcode. On a Mac, run npx cap open ios. Under Signing & Capabilities, choose the team, set the bundle id (com.artavolo.app), and add the Associated Domains capability with applinks:artavolo.com.
3. Make the links open in the app. Set APP_IOS_ID to <Team ID>.com.artavolo.app in includes/config.php. The site then serves /.well-known/apple-app-site-association.
4. Submit. In Xcode, choose Product, then Archive, then Distribute App, then App Store Connect. Then fill in the listing in App Store Connect.

For Apple's review. Apple turns down apps that are only a website in a frame (guideline 4.2). What this app adds:

• the offline page;
• links that open in the app;
• the splash screen;
• files and photos straight from the camera, into attachment fields.

Give the reviewers a demo account with a filled base. Push notifications would strengthen the case; see "Not yet" below.

Signing in to the app

People sign in to the app the same ways as on the website, and nothing new has to be remembered:

• Google, Microsoft or Apple. The app opens the provider in the phone's own browser, where most people are already signed in to Gmail or their work account. They tap their account once and are back in the app, signed in. (Google refuses its sign-in inside an app's own web view, which is why it opens in the browser.) The token on the way back is useless to any other app: only the app that started the sign-in holds the secret that turns it into a session.
• An e-mail code. "E-mail me a sign-in code" sends a 6-digit code and a link, good for 10 minutes. Nothing to remember, and it works for any account.
• A QR code from the website. In the account menu on the computer, "Sign in on your phone" shows a QR code. Scan it with the phone's camera: the phone is signed in, in the app if it is installed. The code works once, for 5 minutes.
• E-mail and password, as before, and single sign-on where the company has it.

Microsoft and Apple appear once their keys are set in the administration, Auth settings. The App Store asks for Sign in with Apple next to Google (guideline 4.8).

What the site does for the apps

• Recognising the app. The app adds ArtavoloApp/1.0 to its user agent, and the site uses that to know it is inside the app: the provider buttons then open in the phone's browser (see above).
• Back and links. Android's back button goes back a page, and closes the app at the first page. A link tapped elsewhere opens the page in the app (partials/app-install.phtml).
• Offline. With no network, the app shows its own "No connection" page and tries again when the phone is back online.

Not yet

• Push notifications (mentions, records waiting for review). These need Firebase Cloud Messaging and Apple Push Notification service credentials, and a way to send from the server.
• Barcode and QR scanning into a field.