Documentazione · App Builder
Esportazione su GitHub e telefoni
Che cosa ti dà l'esportazione
Export code (esporta codice) mette l'app in un tuo repository GitHub, per le piattaforme che scegli:
| Piattaforma | Che cosa riceve il repository |
|---|---|
| Web app (codice Next.js) | Il runtime delle app e il kit (lo stesso codice che serve le app su WebRobot), il manifest dell'app, un README, un Dockerfile, un .env.example e un workflow che costruisce un'immagine container. |
| Android | Una shell per telefono (Capacitor) che apre l'app, e un workflow GitHub Actions che la costruisce. |
| iPhone | La stessa shell, e un workflow che la costruisce sulle macchine macOS di GitHub. |
Il codice esportato non è scritto da un modello: è il codice del runtime già revisionato più il manifest della tua app. La web app esportata si comporta come quella ospitata. I suoi agenti continuano a girare su WebRobot con la chiave API dell'app, che metti nel tuo ambiente. La chiave non viene mai scritta nel repository.
Prima di esportare
- Pubblica prima l'app. L'esportazione usa il manifest pubblicato, i cui agenti esistono già sulla piattaforma. Fino ad allora il pannello dice Publish the app first: the exported code uses its published agents. e il pulsante Export resta disattivato.
- Devi essere amministratore dell'organizzazione. L'accesso a GitHub viene memorizzato come credenziale cifrata dell'organizzazione, e solo gli amministratori possono memorizzare e leggere le credenziali.
Apri il pannello con Export code in App Studio, oppure con Export code sulla scheda di un'app nell'elenco delle app. Il pannello si intitola Export to GitHub: web and phone apps.
Collegare GitHub
La prima volta il pannello mostra Sign in to GitHub and allow WebRobot to create repositories and push code for you. e Connect GitHub (collega GitHub).
- Premi Connect GitHub. GitHub ti chiede di accedere e di concedere a WebRobot due scope:
repo(creare repository e fare push del codice) eworkflow(scrivere i workflow di build in.github/workflows). - Approva. GitHub ti riporta in App Studio con il pannello di esportazione aperto e il messaggio GitHub connected as @<login>. Choose the repository below and press Export.
Se rifiuti, il messaggio è GitHub access was not granted: nothing was connected. Se qualcosa fallisce, è GitHub connection failed: seguito dal motivo. L'accesso va completato entro 10 minuti.
Il token di accesso viene memorizzato cifrato come credenziale cloud della tua organizzazione chiamata github-oauth
(provider github). Tutti gli amministratori dell'organizzazione esportano con lo stesso collegamento. Per
scollegarlo, elimina quella credenziale in Cloud Credentials.
Una volta collegato, il pannello mostra Connected as @<login> e un link switch account (cambia account). Altri stati:
| Messaggio | Che cosa fare |
|---|---|
| The GitHub connection expired. | Premi di nuovo Connect GitHub. |
GitHub must also allow WebRobot to write the app's build workflow (.github/workflows). | Al collegamento manca lo scope workflow. Premi Reconnect GitHub e approva. |
| GitHub is not configured on this console yet. | L'esportazione non è disponibile su questa installazione. |
Scegliere il repository
| Campo | Significato |
|---|---|
| Owner | Il tuo account GitHub, o una delle organizzazioni GitHub di cui fai parte. |
| Repository name | Il valore predefinito è lo slug dell'app. Lettere, cifre, ., _ e -; gli altri caratteri diventano -. |
| New repository | GitHub crea il repository. Private repository è selezionato per impostazione predefinita. |
| Existing repository (a pull request) | Il codice va in un branch e in una pull request. |
Premi Export (mostra Exporting…). L'esportazione è un solo commit, con il messaggio
<app name> v<N> — <platforms> (WebRobot App Studio, kit <version>), per esempio Physio Booking v3 — web + android (WebRobot App Studio, kit <version>).
Nuovo repository
Il repository viene creato (inizializzato, quindi ha un branch predefinito) e il commit finisce sul branch predefinito. Il pannello dice Repository created with the app on <branch> (<N> files) e mostra il link al repository.
Se il repository esiste già, per esempio dopo un tentativo precedente, l'esportazione si ferma con <owner>/<repo> already exists (a previous attempt may have created it): untick "new repository" and export to it — it gets a branch and a pull request.
Repository esistente
Il tuo branch predefinito non viene mai scritto. Il commit va nel branch webrobot/<slug> e viene aperta una pull
request verso il branch predefinito, intitolata WebRobot: <commit message>. Il pannello dice Pushed to
webrobot/<slug> (<N> files) e mostra il link alla pull request.
Esportare di nuovo sposta webrobot/<slug> sul nuovo commit (il branch viene sovrascritto, non unito) e la pull
request aperta lo mostra. Rivedila e uniscila come qualsiasi altra modifica.
Il tuo account GitHub deve avere accesso in push al repository; altrimenti l'esportazione si ferma con your GitHub account cannot push to <owner>/<repo>.
Che cosa c'è nell'esportazione web
| Percorso | Che cosa |
|---|---|
manifest/<slug>.vertical.yaml | Il manifest pubblicato, in YAML, con un'intestazione che indica la versione pubblicata. |
apps/runtime | L'app Next.js che visualizza un manifest. |
packages/vertical-kit | Accesso, crediti, esecuzioni, il client WebRobot. |
schema/vertical-app.schema.json | Il contratto del manifest. python3 scripts/validate.py manifest/*.yaml verifica un manifest rispetto a esso. |
Dockerfile | Costruisce un'immagine che serve solo questa app (modalità app singola). |
.env.example | Le impostazioni di cui l'app ha bisogno. |
.github/workflows/build.yml | Costruisce l'immagine container e la carica su GitHub Container Registry (ghcr.io/<owner>/<repo>:<commit>) a ogni push su main, oppure a mano. |
README.md | Come eseguirla. |
I file di deployment del runtime ospitato, i manifest di esempio e gli script operativi sono esclusi.
Impostazioni
Copia .env.example in apps/runtime/.env.local per lo sviluppo (non farne mai il commit). In produzione passa gli
stessi valori al container. <SLUG> è lo slug in maiuscolo con _ al posto di -.
| Variabile | Valore |
|---|---|
VK_APP_<SLUG>_WEBROBOT_API_KEY | La chiave API dell'app: nella console WebRobot, Cloud Credentials › vertical-app-<slug>. |
VK_APP_<SLUG>_ADMIN_EMAILS | Chi è amministratore dell'app, separati da virgole. |
VK_APP_<SLUG>_EMAIL_ORG_ID | Facoltativa: l'organizzazione il cui server di posta invia i link di accesso. |
VK_SESSION_SECRET | 32 o più caratteri casuali, per esempio da openssl rand -base64 36. |
DATABASE_URL | Una stringa di connessione PostgreSQL. Senza, i dati restano in memoria (solo per lo sviluppo). |
WEBROBOT_API_URL | https://api.webrobot.eu |
VK_SINGLE_APP | true: serve questo solo manifest su qualunque dominio venga pubblicata l'app. |
Eseguirla
cp .env.example apps/runtime/.env.local # fill in the key, the admin emails, a session secret, the database
npm ci
npm run dev -w @webrobot/vertical-runtime # http://localhost:3000
In produzione: docker build -t <slug> . poi docker run --env-file apps/runtime/.env.local -p 3000:3000 <slug>.
Gli agenti continuano a girare sulla piattaforma WebRobot e il loro utilizzo viene addebitato alla tua organizzazione. I pagamenti a te (Stripe Connect) e la commissione della piattaforma restano configurati su WebRobot.
App per telefono
Seleziona Android e/o iPhone. L'app per telefono è una shell Capacitor che apre l'indirizzo web della tua app: stesse schermate, stessi agenti e dati, con la sessione della persona. Nulla dell'app viene copiato nell'app per telefono, quindi ciò che pubblichi in App Studio arriva ai telefoni senza una nuova release sugli store. Sul telefono non c'è mai una chiave della piattaforma. Sul telefono gli utenti accedono con il codice di 6 cifre dell'email di accesso.
Se selezioni solo piattaforme per telefono, il repository riceve il progetto per telefono, i suoi workflow, il manifest (come riferimento) e un README, senza codice web.
Impostazioni del telefono
I campi partono da spec.mobile dell'app, se presente.
| Campo | Regola |
|---|---|
| Store identifier | Obbligatorio. Reverse-DNS, minuscolo, almeno tre parti, per esempio com.yourcompany.physiobooking. Non cambia più una volta che l'app è in uno store. |
| Name under the icon (optional) | Al massimo 30 caratteri. Vuoto: il nome dell'app. |
| Address the phone app opens (optional) | Vuoto: l'app ospitata su WebRobot (https://<slug>.webrobot.eu, oppure spec.host se impostato). Impostalo se ospiti tu la web app. Deve essere https:// più un nome host, facoltativamente una porta, senza percorso. |
Queste impostazioni vanno solo nel repository esportato. Non vengono salvate nell'app in App Studio, quindi compilale
di nuovo alla prossima esportazione, oppure mettile in spec.mobile nella scheda JSON.
spec:
mobile:
appId: com.yourcompany.physiobooking
appName: Physio Booking
capabilities:
- name: camera
reason: To photograph your medical reports.
Funzionalità del telefono
Nell'app entrano solo le funzionalità che selezioni: vengono installati solo i loro plugin e richiesti solo i loro permessi. Per la maggior parte devi scrivere perché l'app ne ha bisogno; il telefono mostra quel testo quando lo chiede alla persona.
| Etichetta nel pannello | Nome | Motivo richiesto |
|---|---|---|
| Camera and photos | camera | sì |
| Location | location | sì |
| Location in the background | backgroundLocation | sì |
| Push notifications | push | no |
| Reminders on the phone | localNotifications | no |
| Face ID / fingerprint | biometrics | sì |
| Barcode and QR scanner | barcode | sì |
| Microphone | microphone | sì |
| Speech to text | speech | sì |
| Contacts | contacts | sì |
| Calendar | calendar | sì |
| Bluetooth devices | bluetooth | sì |
| Files on the phone | files | no |
| Share sheet | share | no |
| Vibration | haptics | no |
Gli store rifiutano i permessi che un'app non usa, quindi l'esportazione controlla in entrambe le direzioni:
Una funzionalità deve essere usata dall'app.
files,shareehapticssono sempre accettate. Le altre richiedono una parte dell'app che le usi:Funzionalità Usata da locationun campo posizione barcodeun campo codice a barre cameraun campo file con acquisizione calendarun'azione di aggiunta al calendario in una vista shareun'azione di condivisione in una vista biometricsil blocco dell'app, spec.mobile.lock: biometricmicrophoneuna vista chat (voce) pushnotifiche: un trigger che notifica, una pianificazione che recapita, o l'email quando un report è pronto Non ancora disponibili:
contacts,bluetooth,backgroundLocation,localNotificationsespeech. Nessuna parte di un'app può ancora usarle, quindi l'esportazione le rifiuta con no part of the app can use it yet: remove it.Una parte dell'app che richiede una funzionalità deve averla. Per esempio un campo posizione senza
locationviene rifiutato con a position field (…) needs 'location' in the phone app.backgroundLocationrichiede anchelocation.
Il pannello mostra un problema in ambra e tiene Export disattivato finché non è risolto: Store identifier: reverse-DNS, lower case, e.g. com.yourcompany.<slug>, Write why the app needs each phone feature you ticked: the phone shows it when asking, oppure The phone app opens an https address (https://host). I controlli sull'uso delle funzionalità da parte dell'app vengono eseguiti quando premi Export; i loro errori iniziano con the phone app settings are not valid.
Che cosa c'è nell'esportazione per telefono
| Percorso | Che cosa |
|---|---|
mobile/package.json | Capacitor e solo i plugin delle funzionalità selezionate, a versioni fisse. |
mobile/capacitor.config.json | L'identificativo per lo store, il nome, l'indirizzo che la shell apre, i colori dell'app. |
mobile/mobile.json | Ciò che la build applica ai progetti nativi: permessi, testi d'uso iOS, versione, orientamento, colori dell'icona e della schermata di avvio. |
mobile/www/index.html | La pagina mostrata quando il telefono non ha connessione, con un pulsante per riprovare. |
mobile/scripts/native.mjs, mobile/scripts/icon.mjs | Script di supporto alla build: applicano mobile.json, generano l'icona. |
mobile/README.md | Come funzionano le build e quali chiavi richiedono gli store. |
.github/workflows/android.yml | La build Android. |
.github/workflows/ios.yml | La build iPhone. |
Le cartelle native (android/, ios/) vengono generate durante la build e non sono conservate nel repository. Il
numero di build è il numero di esecuzione del workflow, quindi ogni caricamento ne ha uno più alto.
Build Android
Il workflow parte a ogni push su main che modifica mobile/, e a mano dalla scheda Actions.
- Senza chiave di firma costruisce un APK di debug che puoi installare su un telefono. Scaricalo dagli artifact dell'esecuzione.
- Con una chiave di firma costruisce un bundle firmato (AAB) per Google Play.
- Con anche un service account Play, carica il bundle nel canale di test interno come bozza. Google Play vuole che il primissimo bundle sia caricato a mano nella Play Console; il workflow carica i successivi.
Aggiungi questi secret al tuo repository (Settings › Secrets and variables › Actions):
| Secret | Che cosa |
|---|---|
ANDROID_KEYSTORE_BASE64 | Il tuo keystore di caricamento, codificato in base64. |
ANDROID_KEYSTORE_PASSWORD | La password del keystore. |
ANDROID_KEY_ALIAS | L'alias della chiave, per esempio upload. |
ANDROID_KEY_PASSWORD | La password della chiave. |
PLAY_SERVICE_ACCOUNT_JSON | Facoltativo: un service account Google Play, per il caricamento. |
GOOGLE_SERVICES_JSON | Con le notifiche push: il google-services.json Firebase dell'app. Senza, la build Android non si registra per le notifiche. |
Build iPhone
Il workflow gira sulle macchine macOS di GitHub, solo a mano (Actions › ios › Run workflow), perché i minuti macOS costano di più.
- Senza chiavi Apple costruisce l'app per il simulatore, per verificare che compili.
- Con le chiavi Xcode firma con il tuo team e carica la build su App Store Connect. Compare in TestFlight, e da lì la invii per la revisione.
Prima crea l'app in App Store Connect con il bundle id uguale al tuo identificativo per lo store. Poi aggiungi:
| Secret | Che cosa |
|---|---|
APPLE_TEAM_ID | L'id del tuo team Apple Developer (10 caratteri). |
APPSTORE_API_KEY_ID | Una chiave API di App Store Connect (Users and Access › Integrations), ruolo Admin. |
APPSTORE_API_ISSUER_ID | L'issuer id mostrato sopra le chiavi. |
APPSTORE_API_KEY_P8 | Il contenuto del file AuthKey_….p8 scaricato. |
Che cosa fornisci tu
- Un account GitHub (o un'organizzazione) e i suoi minuti di Actions.
- Per una web app ospitata da te: un posto dove eseguire il container, un database PostgreSQL, la chiave API dell'app e un segreto di sessione.
- Per Android su Google Play: il tuo account sviluppatore Google Play, un keystore di caricamento e, facoltativamente, un service account; per le notifiche push, un progetto Firebase.
- Per iPhone sull'App Store: il tuo account Apple Developer, la scheda dell'app in App Store Connect e una chiave API di App Store Connect.
Gli account degli store e le chiavi di firma sono tuoi. WebRobot non li conserva mai: restano come secret del tuo repository.
Limiti
- Viene esportata solo la versione pubblicata. Pubblica prima le ultime modifiche.
- L'esportazione è in una sola direzione. Le modifiche che fai nel repository non tornano in App Studio.
- Esportare di nuovo su un repository esistente sovrascrive il branch
webrobot/<slug>. - Il workflow di build web parte con i push su
main. Dopo aver unito la pull request in un altro branch predefinito, avvialo a mano. - Alcune funzionalità del telefono non sono ancora disponibili (vedi Funzionalità del telefono).
- L'app per telefono apre sempre un indirizzo web su HTTPS: non funziona senza connessione e al suo posto mostra la sua pagina offline.