Integration

Du kan integrere interaktive Sprucely.io-dashboards på din egen hjemmeside eller webapplikation på tre måder: ved at indlejre dem med en standard HTML-iframe, ved at gengive dem nativt med den selvstændige JavaScript-runtime, eller ved at montere de selvstændige React-komponenter. iframe-elementet er hurtigst at sætte op; de selvstændige runtimes tegner dashboards direkte i din side og lader dig tilføje nye data under kørslen. Den JSON-struktur, som de selvstændige runtimes læser - dashboards, diagrammer og datasæt - er dokumenteret i referencen for dataformat. For AI-drevet dashboard-automatisering, se afsnittet om MCP API’er.

Indlejring af dashboards i HTML

Den enkleste integration bruger det almindelige HTML-iframe-element og virker på enhver hjemmeside, eller endda lokale HTML-sider. Dashboardet skal være delt, enten i skyen eller on-premise, for at det kan indlæses korrekt. Bemærk, at on-premise-dashboards kun indlæses, når klienten, der tilgår dem, er inden for det samme virksomhedsnetværk.

Vejledning:

1) Udtræk dashboardets indlejringslink - På siden Dashboards skal du sikre dig, at dit dashboard er delt, og derefter klikke på -ikonet for dette dashboard. En grøn pop-up-banner giver dig besked om, at linket er kopieret til udklipsholderen. Dette bruger du til at erstatte indholdet i HTML-iframe-elementets src nedenfor.

2) Indlejr 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) Indlejr dashboardet med dynamisk bredde - Tilpasser automatisk dashboardets størrelse baseret på det overordnede dokuments bredde

Du kan bruge style-parameteren aspect-ratio til automatisk at genberegne højden baseret 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 indlejringsmuligheder

Du kan tilføje tilpassede style-ændringer til style-blokken for iframe-elementet for at tilpasse framens udseende og fremtoning. Disse parametre følger standard HTML/CSS-retningslinjer. Eksemplet nedenfor tilføjer en grå kant rundt om 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>

Indlejring med selvstændig JavaScript

Den selvstændige runtime gengiver dashboards direkte i din side - uden iframe. Dine data indlæses i en database i browseren og tegnes som fuldt interaktive diagrammer; runtimen kontakter kun Sprucely.io for at validere dit adgangstoken.

Vejledning:

1) Opret et adgangstoken - I afsnittet Adgangstokens på din profil skal du oprette et adgangstoken for den origin, dine sider serveres fra (for eksempel https://www.yourdomain.com). Runtimen validerer, at den indlejrende sides origin matcher tokenet, før der gengives.

2) Indlæs runtimen og gengiv et dashboard - Tilføj runtime-scriptet til din side, forbind databasen i browseren én gang med sprucely_db, og gengiv derefter hvert dashboard med sprucely_create. Den komplette side nedenfor forbinder også en knap, der tilføjer flere rækker:

<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) Tilføj data under kørslen - Kald sprucely_add med yderligere rækker når som helst. Hvert dashboard, der bruger datasættet, opdateres automatisk:

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

Funktionsreference

sprucely_db({ id, host, accessToken }) - forbinder databasen i browseren og validerer dit adgangstoken mod sidens origin. Gengiver en statusbanner i det element, der identificeres af id. Kald den én gang pr. side, før du opretter dashboards.
sprucely_create({ id, dashboard, data }) - gengiver ét dashboard i det element, der identificeres af id. Parameteren dashboard definerer layout og styling; data angiver datasættet med dets navn, kolonnenavne, kolonnetyper (VARCHAR, INTEGER, FLOAT eller TIMESTAMP) og rækker - se referencen for dataformat.
sprucely_add(data) - tilføjer rækker til det datasæt, hvis navn matcher et allerede indlæst datasæt, og opdaterer derefter alle dashboards, der bruger det.

Indlejring med selvstændig React

Hvis din hjemmeside er bygget med React, kan du gengive dashboards som komponenter i stedet for at indlæse scriptet manuelt. Komponenterne bruger de samme adgangstokens, dashboarddefinitioner og datasætformat som den selvstændige JavaScript-runtime.

Vejledning:

1) Opret et adgangstoken - Som for selvstændig JavaScript skal du oprette et adgangstoken for din hjemmesides origin i afsnittet Adgangstokens på din profil.

2) Gengiv dashboard-komponenterne - Hent runtimen fra https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js og placer den i dit projekt. Montér én Sprucely.Database-komponent pr. side og én Sprucely.Dashboard-komponent pr. dashboard. Dashboards viser en indlæsningsindikator, indtil databasen har valideret adgangstokenet, og gengives derefter. Den komplette applikation nedenfor gengiver to dashboards fra separate datasæt og tilføjer nye rækker til det første 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 />);

Servering af kortvarige nøgler

Det adgangstoken, du opretter ovenfor, er langtidsholdbart og er tiltænkt at forblive en hemmelighed på serversiden. Hvis din egen backend serverer de indlejrende sider - frem for en side helt uden egen backend - behøver du slet ikke at placere det langtidsholdbare token i siden overhovedet - din backend kan i stedet, server-til-server, udveksle det til et kortvarigt (15 minutters) render-token umiddelbart før hver side serveres, og det er kun render-tokenet, der nogensinde når frem til browseren. Et render-token, som en besøgende udtrækker fra siden, er kun anvendeligt i få minutter, ikke på ubestemt tid.

Vejledning:

1) Udveksl dit adgangstoken til et render-token - fra din backend skal du kalde POST https://www.sprucely.io/api/auth/render_token med dit adgangstoken som bearer-legitimation. Svaret indeholder det nye token, dets tilknyttede host og dets levetid 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 render-tokenet til browseren - brug det på nøjagtig samme måde som et adgangstoken, når du kalder sprucely_db eller monterer Sprucely.Database. Gentag udvekslingen, før hver side serveres (eller med et fast interval, hvis du cacher den gengivne side), så browseren aldrig modtager et token, der er gyldigt i mere end 15 minutter.

Funktionsreference

POST /api/auth/render_token - udveksler et gyldigt adgangstoken, sendt som Authorization: Bearer <token>, til et render-token. Returnerer { token, host, expires_in }, hvor expires_in er fast sat til 900 sekunder. Et render-token kan ikke udveksles til et andet render-token - kun et langtidsholdbart adgangstoken kan anmode om ét.

Sikkerhedsindstillinger

Hvis din hjemmeside håndhæver en Content Security Policy (CSP), skal de selvstændige JavaScript- og React-integrationer ovenfor have et par kilder tilladt, før dashboards kan indlæses - runtimen indlæser sit script fra Sprucely.io, åbner en database i browseren, der er bygget på WebAssembly, og validerer dit adgangstoken mod vores API, og hver af disse kræver en eksplicit CSP-tilladelse. Hvis din hjemmeside ikke bruger CSP, kan du springe dette afsnit over.

Tilføj følgende kilder til din eksisterende politik - dette er direktiver, der skal flettes ind, ikke en komplet politik, der skal erstatte den, 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;

Hvad hvert direktiv bruges til:

script-src - https://www.sprucely.io indlæser runtime-scriptet. 'wasm-unsafe-eval' er påkrævet for at kompilere og køre databasen i browseren, som er bygget på WebAssembly.
connect-src - https://www.sprucely.io kontaktes for at validere dit adgangstoken og for at indlæse databasens WebAssembly- og worker-filer.
worker-src - databasen i browseren kører sine forespørgsler på en baggrundstråd, oprettet fra en blob:-URL.

Ingen af ovenstående kræver 'unsafe-inline' - selve Sprucely-runtimen har aldrig brug for det. Hvis du opbevarer dine egne dashboard- og datasætdefinitioner i et inline <script>-tag, som i eksemplet med selvstændig JavaScript ovenfor, eller din egen side bruger inline styles, skal du tilføje 'unsafe-inline' til script-src eller style-src eller overveje CSP-nonces.