Integration

Du kan integrera interaktiva Sprucely.io-dashboards på din egen webbplats eller webbapplikation på tre sätt: genom att bädda in dem med ett vanligt HTML-iframe, genom att rendera dem direkt med den fristående JavaScript-runtimen, eller genom att montera de fristående React-komponenterna. iframe är snabbast att komma igång med; de fristående runtimerna ritar upp dashboards direkt på din sida och låter dig skicka in ny data vid körning. Den JSON-struktur som de fristående runtimerna läser - dashboards, diagram och dataset - dokumenteras i referensen för dataformat. För AI-driven dashboard-automatisering, se avsnittet MCP-API:er.

HTML-inbäddning

Den enklaste integrationen använder det vanliga HTML-iframe-elementet och fungerar på vilken webbplats som helst, eller till och med på lokala HTML-sidor. Dashboarden måste vara delad, antingen i molnet eller On-premise, för att den ska gå att ladda. Observera att On-premise-dashboards endast laddas när klienten som kommer åt den befinner sig inom samma företagsnätverk.

Instruktioner:

1) Hämta dashboardens inbäddningslänk - På sidan Dashboards säkerställer du att din dashboard är delad och klickar sedan på ikonen för denna dashboard. En grön popup-banner meddelar dig att länken har kopierats till urklipp. Du använder den för att ersätta innehållet i src-attributet på HTML-iframe-elementet nedan.

2) Bädda in dashboarden med fast storlek

<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>

(eller) Bädda in dashboarden med dynamisk bredd - Anpassar automatiskt dashboardens storlek baserat på det överordnade dokumentets bredd

Du kan använda style-parametern aspect-ratio för att automatiskt räkna om höjden baserat på bredden.

<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) Andra användbara inbäddningsalternativ

Du kan lägga till egna style-ändringar i style-blocket för iframe-elementet, för att anpassa utseendet och känslan på ramen. Dessa parametrar följer standardmässiga HTML CSS-riktlinjer. Exemplet nedan lägger till en grå kantlinje runt dashboarden:

<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>

Fristående JavaScript

Den fristående runtimen renderar dashboards direkt i din sida - ingen iframe. Din data laddas in i en databas i webbläsaren och ritas upp som fullt interaktiva diagram; runtimen kontaktar bara Sprucely.io för att validera din åtkomsttoken.

Instruktioner:

1) Skapa en åtkomsttoken - I avsnittet Åtkomsttokens på din profil skapar du en åtkomsttoken för den origin dina sidor serveras från (till exempel https://www.yourdomain.com). Runtimen validerar att den inbäddande sidans origin matchar token innan den renderas.

2) Ladda runtimen och rendera en dashboard - Lägg till runtime-skriptet på din sida, anslut databasen i webbläsaren en gång med sprucely_db, och rendera sedan varje dashboard med sprucely_create. Den kompletta sidan nedan kopplar även in en knapp som lägger till fler rader:

<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) Lägg till data vid körning - Anropa sprucely_add med ytterligare rader när som helst. Varje dashboard som använder datasetet uppdateras automatiskt:

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

Funktionsreferens

sprucely_db({ id, host, accessToken }) - ansluter databasen i webbläsaren och validerar din åtkomsttoken mot sidans origin. Renderar en statusbanner i det element som identifieras av id. Anropa den en gång per sida, innan du skapar dashboards.
sprucely_create({ id, dashboard, data }) - renderar en dashboard i det element som identifieras av id. Parametern dashboard definierar layout och styling; data tillhandahåller datasetet med dess namn, kolumnnamn, kolumntyper (VARCHAR, INTEGER, FLOAT eller TIMESTAMP) och rader - se referensen för dataformat.
sprucely_add(data) - lägger till rader i det dataset vars namn matchar ett redan inläst dataset, och uppdaterar sedan alla dashboards som använder det.

Fristående React

Om din webbplats är byggd med React kan du rendera dashboards som komponenter istället för att ladda skriptet manuellt. Komponenterna använder samma åtkomsttokens, dashboard-definitioner och dataset-format som den fristående JavaScript-runtimen.

Instruktioner:

1) Skapa en åtkomsttoken - Precis som för fristående JavaScript skapar du en åtkomsttoken för din webbplats origin i avsnittet Åtkomsttokens på din profil.

2) Rendera dashboard-komponenterna - Hämta runtimen från https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js och placera den i ditt projekt. Montera en Sprucely.Database-komponent per sida, och en Sprucely.Dashboard-komponent per dashboard. Dashboards visar en laddningsindikator tills databasen har validerat åtkomsttoken, och renderas sedan. Det kompletta programmet nedan renderar två dashboards från separata dataset och lägger till nya rader i den första efter fem sekunder:

// 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 />);

Servera korttidstokens

Åtkomsttokenen du skapar ovan är långlivad och är tänkt att förbli en hemlighet på serversidan. Om din egen backend serverar inbäddningssidorna - snarare än en sida utan egen backend - behöver du aldrig placera den långlivade tokenen i sidan alls - din backend kan istället växla in den, server-till-server, mot en korttidsgiltig render-token (15 minuter) omedelbart innan varje sida serveras, och det är bara render-tokenen som någonsin når webbläsaren. En render-token som en besökare extraherar från sidan är bara användbar i några minuter, inte på obestämd tid.

Instruktioner:

1) Växla in din åtkomsttoken mot en render-token - anropa POST https://www.sprucely.io/api/auth/render_token från din backend, med din åtkomsttoken skickad som bearer-autentisering. Svaret innehåller den nya tokenen, dess bundna host samt dess livslängd i sekunder:

// 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) Servera render-tokenen till webbläsaren - använd den precis som en åtkomsttoken vid anrop av sprucely_db eller montering av Sprucely.Database. Upprepa utväxlingen innan varje sida serveras (eller enligt ett tidsschema om du cachar den renderade sidan), så att webbläsaren aldrig tar emot en token som är giltig längre än 15 minuter.

Funktionsreferens

POST /api/auth/render_token - växlar in en giltig åtkomsttoken, skickad som Authorization: Bearer <token>, mot en render-token. Returnerar { token, host, expires_in } där expires_in alltid är satt till 900 sekunder. En render-token kan inte växlas in mot en ny render-token - bara en långlivad åtkomsttoken kan begära en.

Säkerhetsinställningar

Om din webbplats tillämpar en Content Security Policy (CSP), behöver de fristående JavaScript- och React-integrationerna ovan ett antal källor tillåtna innan dashboards kan laddas - runtimen laddar sitt skript från Sprucely.io, öppnar en databas i webbläsaren baserad på WebAssembly, och validerar din åtkomsttoken mot vårt API, och vart och ett av dessa kräver ett explicit CSP-tillstånd. Om din webbplats inte använder CSP kan du hoppa över det här avsnittet.

Lägg till följande källor i din befintliga policy - det här är direktiv som ska slås samman med den, inte en fullständig policy som ersätter den du redan har:

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;

Vad varje direktiv används till:

script-src - https://www.sprucely.io laddar runtime-skriptet. 'wasm-unsafe-eval' krävs för att kompilera och köra databasen i webbläsaren, som är byggd på WebAssembly.
connect-src - https://www.sprucely.io kontaktas för att validera din åtkomsttoken och för att ladda databasens WebAssembly- och worker-filer.
worker-src - databasen i webbläsaren kör sina frågor på en bakgrundstråd, skapad från en blob:-URL.

Inget av ovanstående kräver 'unsafe-inline' - Sprucely-runtimen själv behöver den aldrig. Om du behåller dina egna dashboard- och dataset-definitioner i en inline <script>-tagg, som i exemplet med fristående JavaScript ovan, eller om din egen sida använder inline styles, lägg till 'unsafe-inline' i script-src eller style-src, eller överväg CSP-nonces.