# Costruisci un'app

Gli sviluppatori possono costruire app personalizzate per SweetHive — una piccola
vista dati incorporata in un contesto, o un prodotto completo su un proprio URL.
Registri l'app una volta, ricevi le credenziali client e sviluppi con l'**App SDK**.

## Due tipi di app

| | **Incorporata** | **Esterna** |
|---|---|---|
| Dove gira | dentro l'interfaccia del contesto SweetHive (un iframe sandbox) | un proprio URL / dominio, avviata da SweetHive |
| Adatta per | viste dati, moduli, dashboard limitate a un contesto | prodotti completi con la propria interfaccia |

Entrambe si autenticano allo stesso modo: un **token a breve durata con ambito
limitato**, vincolato lato server dall'ambito dell'installazione **e** dalla
visibilità in tempo reale di chi guarda. La tua app non vede mai più di quanto veda la
persona che la usa, e l'accesso è revocato nell'istante in cui lo perde.

## Registra e sviluppa

1. Apri **Sviluppatore → App** dal menu utente.
2. Scegli **Registra app**: dalle un nome, scegli *Incorporata* o *Esterna*, imposta
   URL, icona e capacità.
3. Salva il **client ID e il secret** (mostrati una sola volta).
4. **Scarica la guida di sviluppo dell'SDK (.md)** — il contratto completo:
   l'handshake dell'iframe, l'autenticazione, l'API dati con ambito, i test e la
   pubblicazione. Mettila nel tuo repository e sviluppa con il tuo assistente AI di
   programmazione.
   Disponibile anche qui: [SWEETHIVE_APP_SDK.md](/downloads/SWEETHIVE_APP_SDK.md).
5. Imposta l'app su **Attiva** così gli admin degli hive possono installarla da
   *Contesto → App → Aggiungi app*.

## Come funziona lo standard

- **Le app incorporate** girano in un iframe sandbox e ricevono un token a breve
  durata con ambito limitato tramite un handshake `postMessage` — mai un cookie, così
  funziona anche nelle app mobili. La tua app deve consentire a SweetHive di
  incorniciarla (una CSP `frame-ancestors` che includa le origini delle app mobili —
  la guida SDK fornisce l'header esatto).
- **Le app esterne** si aprono al proprio URL con un avvio firmato; su mobile si
  aprono nel browser in-app nativo.
- Ogni chiamata dati è vincolata lato server dall'ambito dell'installazione
  intersecato con la visibilità in tempo reale di chi guarda — stessa legge, stesso
  audit di qualsiasi attore SweetHive.

## App esterne e hub

Un'app esterna è un prodotto completo su un proprio URL. SweetHive mostra una
tessera di avvio; al click l'app si apre con un **avvio firmato** e crea la
propria sessione — su mobile nel browser in-app nativo.

Le app esterne su un'origine autorizzata possono anche far accedere gli utenti
direttamente con il loro account SweetHive (**SSO**): con una sessione SweetHive
attiva non viene chiesta alcuna password; altrimenti l'utente accede dalla
pagina di login di SweetHive e viene rimandato subito nell'app. Richiedi
l'autorizzazione dell'origine quando registri l'app.

### Hub multi-hive: una shell, tante app

Un prodotto che gestisce più hive da un'unica interfaccia segue lo **standard
hub shell** — una shell riutilizzabile modellata da un manifest:

- La **shell** fornisce, una volta sola per ogni app: l'accesso SSO, il
  selettore hive in alto a destra, la gestione di Team e Inviti, il tema
  chiaro/scuro e la barra laterale comprimibile.
- Il **manifest** (salvato con la registrazione dell'app) dichiara il brand e
  le voci del pannello sinistro. Ogni voce apre una vista integrata nella shell
  oppure — la parte chiave — **una qualunque app SweetHive incorporata resa in
  un frame, senza modifiche**: una sola build serve l'interfaccia del contesto
  e l'hub.
- Cambiare hive ridefinisce l'ambito di tutto: la shell risolve
  l'installazione dell'app nell'hive selezionato e ricarica la vista attiva,
  così ogni schermata segue l'hive — inclusi gli stati vuoti per gli hive in
  cui l'app non è installata.

La guida SDK contiene il contratto completo: lo schema del manifest,
l'handshake delle viste e le insidie da evitare.

## Testa e pubblica

Registra la tua app con un URL localhost, installala in un contesto di prova, e
l'handshake consegna un token reale con ambito sui tuoi dati. Quando è pronta,
impostala su **Attiva** — e disattivala in qualsiasi momento; le installazioni si
fermano immediatamente.