Integrazione

Puoi integrare dashboard interattive di Sprucely.io nel tuo sito web o nella tua applicazione web in tre modi: incorporandole con un iframe HTML standard, renderizzandole nativamente con il runtime JavaScript standalone, oppure montando i componenti React standalone. L’iframe è il più rapido da configurare; i runtime standalone disegnano le dashboard direttamente nella tua pagina e ti permettono di inserire nuovi dati a runtime. La struttura JSON che i runtime standalone leggono - dashboard, grafici e dataset - è documentata nel riferimento formato dati. Per l’automazione delle dashboard basata sull’IA, consulta la sezione API MCP.

Incorporare le dashboard in HTML

L’integrazione più semplice utilizza l’elemento iframe HTML standard e funziona su qualsiasi sito web, o persino su pagine HTML locali. Affinché si carichi correttamente, la dashboard deve essere condivisa, sia in Cloud che On-premise. Tieni presente che le dashboard On-premise si caricano solo quando il client che vi accede si trova all’interno della stessa rete aziendale.

Istruzioni:

1) Estrai il link di incorporamento della dashboard - Nella pagina Dashboard, assicurati che la tua dashboard sia condivisa, quindi fai clic sull’icona per questa dashboard. Un banner verde a comparsa ti notificherà che il link è stato copiato negli appunti. Lo utilizzerai per sostituire il contenuto dell’attributo src dell’iframe HTML qui sotto.

2) Incorpora la dashboard con una dimensione fissa

<html>
  <head>
    <title>Sprucely.io Dashboard</title>
  </head>
  <body>
    <h1>Sprucely.io Dashboard</h1>
    <iframe src="https://www.sprucely.io/service/dashboards/embed/[userId]/[dashboardId]/"
            allow="clipboard-write"
            style="height: 500px; width: 700px;"
            title="Sprucely.io Dashboard"></iframe>
  </body>
</html>

(oppure) Incorpora la dashboard con larghezza dinamica - Ridimensiona automaticamente la dashboard in base alla larghezza del documento genitore

Puoi utilizzare il parametro di stile aspect-ratio per ricalcolare automaticamente l’altezza in base alla larghezza.

<html>
  <head>
    <title>Sprucely.io Dashboard</title>
  </head>
  <body>
    <h1>Sprucely.io Dashboard</h1>
    <iframe src="https://www.sprucely.io/service/dashboards/embed/[userId]/[dashboardId]/"
            allow="clipboard-write"
            scrolling="no"
            style="width: 100%; aspect-ratio: 1.5; border: none;"
            title="Sprucely.io Dashboard"></iframe>
  </body>
</html>

3) Altre opzioni utili per l’incorporamento

Puoi aggiungere modifiche di stile personalizzate al blocco style dell’elemento iframe, per personalizzare l’aspetto del frame. Questi parametri seguono le linee guida HTML e CSS standard. L’esempio seguente aggiunge un bordo grigio attorno alla dashboard:

<html>
  <head>
    <title>Sprucely.io Dashboard</title>
  </head>
  <body>
    <h1>Sprucely.io Dashboard</h1>
    <iframe src="https://www.sprucely.io/service/dashboards/embed/[userId]/[dashboardId]/"
            allow="clipboard-write"
            style="height: 100%; width: 100%; border: 2px solid grey;"
            title="Sprucely.io Dashboard"></iframe>
  </body>
</html>

Incorporare con JavaScript standalone

Il runtime standalone renderizza le dashboard direttamente all’interno della tua pagina - senza iframe. I tuoi dati vengono caricati in un database in-browser e disegnati come grafici completamente interattivi; il runtime contatta Sprucely.io solo per convalidare il tuo token di accesso.

Istruzioni:

1) Crea un token di accesso - Nella sezione Token di accesso del tuo profilo, crea un token di accesso per l’origine da cui vengono servite le tue pagine (ad esempio https://www.yourdomain.com). Il runtime verifica che l’origine della pagina di incorporamento corrisponda al token prima di eseguire il rendering.

2) Carica il runtime e renderizza una dashboard - Aggiungi lo script del runtime alla tua pagina, connetti il database in-browser una sola volta con sprucely_db, quindi renderizza ogni dashboard con sprucely_create. La pagina completa qui sotto collega anche un pulsante che aggiunge altre righe:

<html>
  <head>
    <title>Orders Dashboard</title>
  </head>
  <body>
    <div id="database"></div>
    <div id="orders_dashboard"></div>
    <button onclick="addRows()">Add rows</button>

    <script src="https://www.sprucely.io/cross-origin/sprucely-runtime.min.js"></script>
    <script>
      const data = {
        name:    "Orders",
        headers: ["region", "amount", "items"],
        types:   ["VARCHAR", "FLOAT", "INTEGER"],
        entries: [
          ["North", 120.50, 2],
          ["South",  89.95, 1],
          ["North", 432.00, 5],
          ["South",  74.50, 1]
        ]
      };

      const dashboard = {
        config: {
          type: "dashboard",
          style: {
            widget: {
              color: "#667FFF",
              backgroundColor: "#0C0B29",
              primaryColor: "#01EEAE",
              primaryColorSubtle: "#C70584",
              secondaryColor: "#2C2B49"
            }
          }
        },
        data: {
          type: "dash",
          children: [
            {
              type: "dash_stacker_hor",
              children: [
                { type: "dash_chart", datasetId: "Orders", x: "region", chartType: "bar", dataFunction: "count" },
                { type: "dash_chart", datasetId: "Orders", x: "amount", y: "items", chartType: "hexbin", dataFunction: "count" }
              ]
            }
          ]
        }
      };

      sprucely_db({
        id: "database",
        host: "https://www.yourdomain.com",
        accessToken: "YOUR_ACCESS_TOKEN"
      });
      sprucely_create({ id: "orders_dashboard", dashboard, data });

      function addRows() {
        sprucely_add({
          name:    "Orders",
          headers: ["region", "amount", "items"],
          types:   ["VARCHAR", "FLOAT", "INTEGER"],
          entries: [
            ["East", 310.40, 3],
            ["West", 129.95, 1]
          ]
        });
      }
    </script>
  </body>
</html>

3) Aggiungi dati a runtime - Chiama sprucely_add con righe aggiuntive in qualsiasi momento. Ogni dashboard che utilizza il dataset si aggiorna automaticamente:

sprucely_add({
  name:    "Orders",
  headers: ["region", "amount", "items"],
  types:   ["VARCHAR", "FLOAT", "INTEGER"],
  entries: [
    ["East", 310.40, 3],
    ["West", 129.95, 1]
  ]
});

Riferimento delle funzioni

sprucely_db({ id, host, accessToken }) - connette il database in-browser e convalida il tuo token di accesso rispetto all’origine della pagina. Renderizza un banner di stato nell’elemento identificato da id. Chiamala una sola volta per pagina, prima di creare le dashboard.
sprucely_create({ id, dashboard, data }) - renderizza una dashboard nell’elemento identificato da id. Il parametro dashboard definisce il layout e lo stile; data fornisce il dataset con il suo nome, le intestazioni, i tipi di colonna (VARCHAR, INTEGER, FLOAT o TIMESTAMP) e le righe - consulta il riferimento formato dati.
sprucely_add(data) - aggiunge righe al dataset il cui nome corrisponde a un dataset già caricato, quindi aggiorna tutte le dashboard che lo utilizzano.

Incorporare con React standalone

Se il tuo sito è costruito con React, puoi renderizzare le dashboard come componenti invece di caricare lo script manualmente. I componenti utilizzano gli stessi token di accesso, definizioni di dashboard e formato dataset del runtime JavaScript standalone.

Istruzioni:

1) Crea un token di accesso - Come per JavaScript standalone, crea un token di accesso per l’origine del tuo sito nella sezione Token di accesso del tuo profilo.

2) Renderizza i componenti della dashboard - Recupera il runtime da https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js e posizionalo nel tuo progetto. Monta un componente Sprucely.Database per pagina e un componente Sprucely.Dashboard per ogni dashboard. Le dashboard mostrano un indicatore di caricamento finché il database non ha convalidato il token di accesso, quindi vengono renderizzate. L’applicazione completa qui sotto renderizza due dashboard da dataset separati e aggiunge nuove righe alla prima dopo cinque secondi:

// Get https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js
// and place it in your project, next to this file.

import React, { useEffect } from "react";
import { createRoot } from "react-dom/client";
import Sprucely, { sprucely_add } from "./sprucely-runtime.min.cjs.js";

const style = {
  widget: {
    color: "#667FFF",
    backgroundColor: "#0C0B29",
    primaryColor: "#01EEAE",
    primaryColorSubtle: "#C70584",
    secondaryColor: "#2C2B49"
  }
};

const orders = {
  name:    "Orders",
  headers: ["region", "amount", "items"],
  types:   ["VARCHAR", "FLOAT", "INTEGER"],
  entries: [
    ["North", 120.50, 2],
    ["South",  89.95, 1],
    ["North", 432.00, 5],
    ["South",  74.50, 1]
  ]
};

const returns = {
  name:    "Returns",
  headers: ["reason", "amount", "days"],
  types:   ["VARCHAR", "FLOAT", "INTEGER"],
  entries: [
    ["Damaged", 45.00, 3],
    ["Late",    12.50, 8],
    ["Changed", 99.90, 2]
  ]
};

const moreOrders = {
  name:    "Orders",
  headers: ["region", "amount", "items"],
  types:   ["VARCHAR", "FLOAT", "INTEGER"],
  entries: [
    ["East", 310.40, 3],
    ["West", 129.95, 1]
  ]
};

const ordersDashboard = {
  config: { type: "dashboard", style },
  data: {
    type: "dash",
    children: [
      {
        type: "dash_stacker_hor",
        children: [
          { type: "dash_chart", datasetId: "Orders", x: "region", chartType: "bar", dataFunction: "count" },
          { type: "dash_chart", datasetId: "Orders", x: "amount", y: "items", chartType: "hexbin", dataFunction: "count" }
        ]
      }
    ]
  }
};

const returnsDashboard = {
  config: { type: "dashboard", style },
  data: {
    type: "dash",
    children: [
      {
        type: "dash_stacker_hor",
        children: [
          { type: "dash_chart", datasetId: "Returns", x: "amount", y: "days", d: "amount", r: "days", chartType: "dot", dataFunction: "average" }
        ]
      }
    ]
  }
};

const App = () => {
  useEffect(() => {
    const timer = setTimeout(() => { sprucely_add(moreOrders); }, 5000);
    return () => clearTimeout(timer);
  }, []);

  return (
    <>
      <Sprucely.Database host="https://www.yourdomain.com" accessToken="YOUR_ACCESS_TOKEN" />
      <Sprucely.Dashboard id="orders_dashboard" dashboard={ordersDashboard} data={orders} />
      <Sprucely.Dashboard id="returns_dashboard" dashboard={returnsDashboard} data={returns} />
    </>
  );
};

createRoot(document.getElementById("root")).render(<App />);

Fornire chiavi a breve termine

Il token di accesso che crei sopra è a lunga durata ed è pensato per rimanere un segreto lato server. Se il tuo backend serve le pagine di incorporamento - anziché una pagina priva di backend proprio - non hai bisogno di inserire affatto quel token a lunga durata nella pagina: il tuo backend può scambiarlo, da server a server, con un token di rendering a breve durata (15 minuti) immediatamente prima di servire ogni pagina, e solo il token di rendering raggiunge il browser. Un token di rendering che un visitatore estrae dalla pagina è utile solo per qualche minuto, non a tempo indeterminato.

Istruzioni:

1) Scambia il tuo token di accesso con un token di rendering - dal tuo backend, chiama POST https://www.sprucely.io/api/auth/render_token con il tuo token di accesso come credenziale bearer. La risposta contiene il nuovo token, l’host a cui è vincolato e la sua durata in secondi:

// On your server, immediately before serving each embedding page:
const response = await fetch("https://www.sprucely.io/api/auth/render_token", {
  method:  "POST",
  headers: { Authorization: "Bearer " + process.env.SPRUCELY_ACCESS_TOKEN }
});
const { token, expires_in } = await response.json(); // expires_in: 900 (15 minutes)

// Send only the render token to the browser - never the long-lived access
// token itself:
res.send(`
  <script src="https://www.sprucely.io/cross-origin/sprucely-runtime.min.js"></script>
  <script>
    sprucely_db({
      id: "database",
      host: "https://www.yourdomain.com",
      accessToken: "${token}"
    });
  </script>
`);

2) Fornisci il token di rendering al browser - utilizzalo esattamente come un token di accesso quando chiami sprucely_db o monti Sprucely.Database. Ripeti lo scambio prima di servire ogni pagina (oppure a intervalli regolari se metti in cache la pagina renderizzata), in modo che il browser non riceva mai un token valido per più di 15 minuti.

Riferimento delle funzioni

POST /api/auth/render_token - scambia un token di accesso valido, inviato come Authorization: Bearer <token>, con un token di rendering. Restituisce { token, host, expires_in } con expires_in fisso a 900 secondi. Un token di rendering non può essere scambiato con un altro token di rendering - solo un token di accesso a lunga durata può richiederne uno.

Impostazioni di sicurezza

Se il tuo sito applica una Content Security Policy (CSP), le integrazioni JavaScript e React standalone descritte sopra richiedono che alcune sorgenti siano consentite prima che le dashboard possano caricarsi - il runtime carica il proprio script da Sprucely.io, apre un database in-browser basato su WebAssembly e convalida il tuo token di accesso rispetto alla nostra API, e ciascuno di questi elementi richiede un’autorizzazione CSP esplicita. Se il tuo sito non utilizza CSP, puoi saltare questa sezione.

Aggiungi le seguenti sorgenti alla tua policy esistente - si tratta di direttive da unire, non di una policy completa che sostituisce quella già in uso:

script-src   'self' https://www.sprucely.io 'wasm-unsafe-eval';
connect-src  'self' https://www.sprucely.io;
worker-src   'self' blob: https://www.sprucely.io;

A cosa serve ciascuna direttiva:

script-src - https://www.sprucely.io carica lo script del runtime. 'wasm-unsafe-eval' è necessario per compilare ed eseguire il database in-browser, che è costruito su WebAssembly.
connect-src - https://www.sprucely.io viene contattato per convalidare il tuo token di accesso e per caricare i file WebAssembly e worker del database.
worker-src - il database in-browser esegue le proprie query su un thread in background, creato a partire da un URL blob:.

Nessuna delle direttive sopra richiede 'unsafe-inline' - il runtime Sprucely stesso non ne ha mai bisogno. Se mantieni le tue definizioni di dashboard e dataset in un tag <script> inline, come nell’esempio JavaScript standalone sopra, oppure la tua pagina utilizza stili inline, aggiungi 'unsafe-inline' a script-src o style-src, oppure valuta l’uso di nonce CSP.