Integrasjon

Du kan integrere interaktive Sprucely.io-dashboard i ditt eget nettsted eller din egen webapplikasjon på tre måter: ved å bygge dem inn med en standard HTML-iframe, ved å rendre dem direkte med den frittstående JavaScript-runtimen, eller ved å montere de frittstående React-komponentene. iframe-en er raskest å sette opp; de frittstående runtimene tegner dashboardene direkte i siden din og lar deg legge til nye data underveis, mens siden kjører. JSON-strukturen som de frittstående runtimene leser - dashboard, diagrammer og datasett - er dokumentert i referansen for dataformat. For AI-drevet dashboard-automatisering, se avsnittet om MCP-APIer.

HTML-innbygging

Den enkleste integrasjonen bruker det vanlige HTML-iframe-elementet, og fungerer på alle nettsteder, eller til og med lokale HTML-sider. Dashboardet må være delt, enten i skyen eller on-premise, for at det skal lastes inn. Merk at on-premise-dashboard bare lastes inn når klienten som åpner det er innenfor samme bedriftsnettverk.

Fremgangsmåte:

1) Hent innbyggingslenken for dashboardet - På siden Dashboard, sørg for at dashboardet ditt er delt, og klikk deretter på -ikonet for dette dashboardet. En grønn varselboks vil informere deg om at lenken er kopiert til utklippstavlen. Du bruker denne til å erstatte innholdet i src-attributtet til HTML-iframe-en nedenfor.

2) Bygg inn dashboardet med en fast størrelse

<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) Bygg inn dashboardet med dynamisk bredde - Endrer automatisk størrelse på dashboardet basert på foreldredokumentets bredde

Du kan bruke style-parameteren aspect-ratio for å automatisk beregne høyden på nytt basert 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) Andre nyttige innbyggingsalternativer

Du kan legge til egne stilendringer i style-blokken til iframe-elementet for å tilpasse utseendet på rammen. Disse parameterne følger standard HTML/CSS-retningslinjer. Eksemplet nedenfor legger til en grå kant rundt dashboardet:

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

Frittstående JavaScript

Den frittstående runtimen rendrer dashboardene direkte i siden din - uten iframe. Dataene dine lastes inn i en database i nettleseren og tegnes som fullt interaktive diagrammer; runtimen kontakter kun Sprucely.io for å validere tilgangstokenet ditt.

Fremgangsmåte:

1) Opprett et tilgangstoken - I delen Tilgangstokener i profilen din oppretter du et tilgangstoken for opprinnelsen (origin) som sidene dine serveres fra (for eksempel https://www.yourdomain.com). Runtimen validerer at opprinnelsen til siden som bygger inn dashboardet, samsvarer med tokenet før det rendres.

2) Last inn runtimen og rendre et dashboard - Legg til runtime-scriptet på siden din, koble til databasen i nettleseren én gang med sprucely_db, og rendre deretter hvert dashboard med sprucely_create. Den komplette siden nedenfor kobler også til en knapp som legger til flere 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) Legg til data under kjøring - Kall sprucely_add med flere rader når som helst. Alle dashboard som bruker datasettet, oppdateres automatisk:

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

Funksjonsreferanse

sprucely_db({ id, host, accessToken }) - kobler til databasen i nettleseren og validerer tilgangstokenet ditt mot sidens opprinnelse. Rendrer en statusbanner inn i elementet identifisert av id. Kall den én gang per side, før du oppretter dashboard.
sprucely_create({ id, dashboard, data }) - rendrer ett dashboard inn i elementet identifisert av id. Parameteren dashboard definerer layout og styling; data leverer datasettet med navn, kolonneoverskrifter, kolonnetyper (VARCHAR, INTEGER, FLOAT eller TIMESTAMP) og rader - se referansen for dataformat.
sprucely_add(data) - legger til rader i datasettet hvis navn samsvarer med et allerede innlastet datasett, og oppdaterer deretter alle dashboard som bruker det.

Frittstående React

Hvis nettstedet ditt er bygget med React, kan du rendre dashboard som komponenter i stedet for å laste inn scriptet manuelt. Komponentene bruker de samme tilgangstokenene, dashboard-definisjonene og datasettformatet som den frittstående JavaScript-runtimen.

Fremgangsmåte:

1) Opprett et tilgangstoken - Som for frittstående JavaScript oppretter du et tilgangstoken for nettstedets opprinnelse i delen Tilgangstokener i profilen din.

2) Rendre dashboard-komponentene - Hent runtimen fra https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js og plasser den i prosjektet ditt. Monter én Sprucely.Database-komponent per side, og én Sprucely.Dashboard-komponent per dashboard. Dashboard viser en innlastingsindikator helt til databasen har validert tilgangstokenet, og rendres deretter. Det komplette programmet nedenfor rendrer to dashboard fra separate datasett, og legger til nye rader i det første etter 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 />);

Servering av korttidsnøkler

Tilgangstokenet du oppretter ovenfor, er langvarig og skal forbli en hemmelighet på serversiden. Hvis din egen backend serverer sidene som bygger inn dashboardet - i stedet for en side uten egen backend - trenger du ikke å legge det langvarige tokenet inn i siden i det hele tatt - backenden din kan bytte det, server-til-server, mot et kortlevd (15 minutter) rendringstoken like før hver side serveres, slik at det kun er rendringstokenet som noensinne når nettleseren. Et rendringstoken en besøkende henter ut fra siden, er bare nyttig i noen minutter, ikke på ubestemt tid.

Fremgangsmåte:

1) Bytt tilgangstokenet ditt mot et rendringstoken - fra backenden din, kall POST https://www.sprucely.io/api/auth/render_token med tilgangstokenet ditt som bearer-legitimasjon. Svaret inneholder det nye tokenet, den tilknyttede verten, og levetiden 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) Server rendringstokenet til nettleseren - bruk det akkurat som et tilgangstoken når du kaller sprucely_db eller monterer Sprucely.Database. Gjenta byttet før hver side serveres (eller på en timer hvis du cacher den rendrede siden), slik at nettleseren aldri mottar et token som er gyldig i mer enn 15 minutter.

Funksjonsreferanse

POST /api/auth/render_token - bytter et gyldig tilgangstoken, sendt som Authorization: Bearer <token>, mot et rendringstoken. Returnerer { token, host, expires_in } med expires_in fast satt til 900 sekunder. Et rendringstoken kan ikke byttes mot et nytt rendringstoken - bare et langvarig tilgangstoken kan be om ett.

Sikkerhetsinnstillinger

Hvis nettstedet ditt håndhever en Content Security Policy (CSP), trenger de frittstående JavaScript- og React-integrasjonene ovenfor noen få tillatte kilder før dashboard kan lastes inn - runtimen laster inn scriptet sitt fra Sprucely.io, åpner en database i nettleseren basert på WebAssembly, og validerer tilgangstokenet ditt mot vårt API, og hver av disse krever en eksplisitt CSP-tillatelse. Hvis nettstedet ditt ikke bruker CSP, kan du hoppe over denne delen.

Legg til følgende kilder i din eksisterende policy - dette er direktiver som skal flettes inn, ikke en komplett policy som erstatter det du allerede 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;

Hva hvert direktiv brukes til:

script-src - https://www.sprucely.io laster inn runtime-scriptet. 'wasm-unsafe-eval' kreves for å kompilere og kjøre databasen i nettleseren, som er bygget på WebAssembly.
connect-src - https://www.sprucely.io kontaktes for å validere tilgangstokenet ditt og for å laste inn databasens WebAssembly- og worker-filer.
worker-src - databasen i nettleseren kjører spørringene sine på en bakgrunnstråd, opprettet fra en blob:-URL.

Ingen av direktivene ovenfor krever 'unsafe-inline' - selve Sprucely-runtimen trenger det aldri. Hvis du beholder dine egne dashboard- og datasettdefinisjoner i en innebygd <script>-tag, som i eksemplet for frittstående JavaScript ovenfor, eller hvis siden din bruker innebygde stiler, legger du til 'unsafe-inline' i script-src eller style-src, eller vurderer CSP-nonces.