App esterne

Corpo della richiesta

Risposta

{
  "user": {
    "id": "cmlwjuy7e0000fiyvsdbo6mya",
    "email": "laura@example.com",
    "name": "Laura Bianchi"
  },
  "embed": { "key": "portale", "name": "Portale" },
  "apiKey": {
    "key": "boxe_9f3c…",
    "persistent": true,
    "issuedNow": false,
    "header": "x-api-key"
  },
  "api": { "baseUrl": "https://box.example.com/api/public" }
}

• 200Ticket valido: identità nella risposta.
• 400Manca il ticket o la chiave.
• 401Ticket scaduto, già usato, oppure chiave sbagliata.
• 403L’account non è abilitato ad aprire questa app.
• 500Il servizio di autenticazione non è raggiungibile, oppure le app esterne non sono configurate su questa Box.

Dura nel tempo

Uno scambio successivo per lo stesso utente restituisce la stessa chiave. Riaprire l’app non invalida quella che stai già usando, quindi puoi conservarla e lavorare anche quando l’utente non è collegato — sincronizzazioni notturne, webhook, promemoria.

Vede quello che vede l’utente

La chiave non è un accesso amministrativo: ogni chiamata è filtrata sulla visibilità di quella persona, e sullo spazio di lavoro da cui l’app è stata aperta. Quello spazio è legato alla chiave: mandare un header x-organization-id diverso non la sposta altrove.

Come muore

La chiave smette di funzionare, subito, quando:

• il cliente revoca gli accessi dalla pagina di configurazione;
• l’app viene disinstallata dalla Box;
• l’app viene messa in pausa.

Dopo una revoca, la chiave nuova arriva con la prima riapertura dell’app: non c’è niente da riconfigurare. Gestisci un 401 rimandando l’utente al lancio, non ritentando la stessa chiave.

Includi la libreria

Un solo file, senza dipendenze: /sdk/embed-v1.js di questo sito espone window.IntelligenceBox (con un bundler CommonJS, require restituisce lo stesso oggetto). I tipi TypeScript sono accanto, in /sdk/embed-v1.d.ts. Puoi anche copiarlo nel tuo progetto: una modifica incompatibile arriverà come v2, in un file nuovo.

<script src="https://www.intelligencebox.it/sdk/embed-v1.js"></script>
<script>
  // "Excel / CSV": the user chooses where the file goes.
  exportButton.addEventListener("click", async () => {
    const csv = new Blob([rows.join("\n")], { type: "text/csv" });
    await IntelligenceBox.saveFile({ fileName: "dashboard.csv", data: csv });
  });

  // "PDF / print": produce the PDF, then open it in the default viewer.
  printButton.addEventListener("click", async () => {
    const pdf = await fetch("/dashboard.pdf").then((r) => r.blob());
    await IntelligenceBox.openFile({ fileName: "dashboard.pdf", data: pdf });
  });

  // Instead of window.confirm / window.prompt.
  deleteButton.addEventListener("click", async () => {
    if (await IntelligenceBox.confirm("Delete this record?", { destructive: true })) remove();
  });
  linkButton.addEventListener("click", async () => {
    const url = await IntelligenceBox.prompt("Link URL", "https://");
    if (url !== null) insertLink(url);
  });
</script>

Funzioni

Le finestre di dialogo hanno sempre come titolo il nome della tua app, come un browser scrive il sito sopra un confirm: la pagina sceglie solo il testo e le etichette dei pulsanti.

Lo stesso codice nel browser

Fuori dall’app — una scheda del browser, un altro sito che incorpora la tua pagina — ogni funzione usa il browser: openExternal apre una nuova scheda, saveFile scarica il file, openFile lo apre in una scheda, alert, confirm e prompt sono quelli nativi.

Limiti e sicurezza

• File fino a 100 MB.
• Testo delle finestre fino a 4.000 caratteri, solo testo semplice; etichette dei pulsanti fino a 40.
• Una finestra alla volta, fino a 5 in coda. Se la pagina dell’iframe cambia, quelle in attesa si chiudono come annullate.
• openExternal: al massimo 5 indirizzi ogni 10 secondi.
• La libreria parla solo con la pagina dell’app, e l’app risponde solo all’iframe e all’origine della tua installazione. Non passa identità né chiavi: non mandarci mai la apiKey.

Errori

Una richiesta rifiutata rigetta la promessa con IntelligenceBoxError, il cui code è unsupported (funzione non disponibile qui, o un tipo di file che openFile non apre), invalid (argomenti sbagliati), busy (troppe richieste in attesa) o failed (non è riuscito, e l’utente ha già visto l’avviso).