Integratie

U kunt interactieve Sprucely.io-dashboards op drie manieren integreren in uw eigen website of webapplicatie: door ze in te sluiten met een standaard HTML-iframe, door ze native te renderen met de standalone JavaScript-runtime, of door de standalone React-componenten te mounten. De iframe is het snelst ingesteld; de standalone runtimes tekenen de dashboards rechtstreeks in uw pagina en laten u tijdens runtime nieuwe data toevoegen. De JSON-structuur die de standalone runtimes uitlezen - dashboards, grafieken en datasets - wordt gedocumenteerd in de dataformaat-referentie. Voor AI-gestuurde dashboardautomatisering raadpleegt u de sectie MCP API’s.

Dashboards insluiten in HTML

De eenvoudigste integratie gebruikt het standaard HTML-iframe-element en werkt op elke website, of zelfs op lokale HTML-pagina’s. Het dashboard moet zijn gedeeld, hetzij in de Cloud, hetzij On-premise, wil het succesvol laden. Let op: On-premise-dashboards laden alleen wanneer de client die ze opvraagt zich binnen hetzelfde bedrijfsnetwerk bevindt.

Instructies:

1) Haal de embedlink van het dashboard op - Zorg op de pagina Dashboards dat uw dashboard is gedeeld en klik vervolgens op het icoon voor dit dashboard. Een groene pop-upbanner laat u weten dat de link naar het klembord is gekopieerd. Deze gebruikt u om de inhoud van het iframe-src-attribuut hieronder te vervangen.

2) Sluit het dashboard in met een vaste grootte

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

(of) Sluit het dashboard in met dynamische breedte - Wijzigt automatisch de grootte van het dashboard op basis van de breedte van het bovenliggende document

U kunt de style-parameter aspect-ratio gebruiken om de hoogte automatisch te herberekenen op basis van de breedte.

<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) Andere nuttige insluitopties

U kunt aangepaste stijlwijzigingen toevoegen aan het style-blok van het iframe-element om het uiterlijk van het frame aan te passen. Deze parameters volgen de standaard HTML- en CSS-richtlijnen. Onderstaand voorbeeld voegt een grijze rand toe rond het 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>

Insluiten met Standalone JavaScript

De standalone runtime rendert dashboards rechtstreeks in uw pagina - geen iframe. Uw data wordt geladen in een browserdatabase en getekend als volledig interactieve grafieken; de runtime neemt alleen contact op met Sprucely.io om uw toegangstoken te valideren.

Instructies:

1) Maak een toegangstoken aan - Maak in de sectie Toegangstokens van uw profiel een toegangstoken aan voor de origin waarvandaan uw pagina’s worden geserveerd (bijvoorbeeld https://www.yourdomain.com). De runtime controleert of de origin van de insluitende pagina overeenkomt met het token voordat er wordt gerenderd.

2) Laad de runtime en render een dashboard - Voeg het runtime-script toe aan uw pagina, verbind eenmalig met de browserdatabase via sprucely_db, en render vervolgens elk dashboard met sprucely_create. De volledige pagina hieronder koppelt ook een knop die meer rijen toevoegt:

<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) Data toevoegen tijdens runtime - Roep sprucely_add op met extra rijen, op elk gewenst moment. Elk dashboard dat de dataset gebruikt, wordt automatisch vernieuwd:

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

Functiereferentie

sprucely_db({ id, host, accessToken }) - verbindt de browserdatabase en valideert uw toegangstoken tegen de pagina-origin. Rendert een statusbanner in het element dat wordt geïdentificeerd door id. Roep deze functie eenmalig per pagina aan, vóór het aanmaken van dashboards.
sprucely_create({ id, dashboard, data }) - rendert één dashboard in het element dat wordt geïdentificeerd door id. De parameter dashboard bepaalt de lay-out en styling; data levert de dataset met naam, headers, kolomtypen (VARCHAR, INTEGER, FLOAT of TIMESTAMP) en rijen - zie de dataformaat-referentie.
sprucely_add(data) - voegt rijen toe aan de dataset waarvan de naam overeenkomt met een reeds geladen dataset, en vernieuwt vervolgens alle dashboards die deze gebruiken.

Insluiten met Standalone React

Als uw site is gebouwd met React, kunt u dashboards renderen als componenten in plaats van het script handmatig te laden. De componenten gebruiken dezelfde toegangstokens, dashboarddefinities en datasetindeling als de standalone JavaScript-runtime.

Instructies:

1) Maak een toegangstoken aan - Maak, net als bij standalone JavaScript, een toegangstoken aan voor de origin van uw site in de sectie Toegangstokens van uw profiel.

2) Render de dashboardcomponenten - Haal de runtime op via https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js en plaats deze in uw project. Mount één Sprucely.Database-component per pagina, en één Sprucely.Dashboard-component per dashboard. Dashboards tonen een laadindicator totdat de database het toegangstoken heeft gevalideerd, en renderen daarna. De volledige applicatie hieronder rendert twee dashboards uit afzonderlijke datasets en voegt na vijf seconden nieuwe rijen toe aan de eerste:

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

Kortlevende sleutels serveren

Het toegangstoken dat u hierboven aanmaakt, is langlevend en is bedoeld om een serverzijdig geheim te blijven. Als uw eigen backend de insluitende pagina’s serveert - in plaats van een pagina zonder eigen backend - hoeft u dat langlevende token helemaal niet in de pagina te plaatsen - uw backend kan het, server-to-server, inwisselen voor een kortlevend (15 minuten) rendertoken vlak voordat elke pagina wordt geserveerd, waarbij alleen het rendertoken ooit de browser bereikt. Een rendertoken dat een bezoeker uit de pagina haalt, is slechts enkele minuten bruikbaar, niet voor onbepaalde tijd.

Instructies:

1) Wissel uw toegangstoken in voor een rendertoken - roep vanuit uw backend POST https://www.sprucely.io/api/auth/render_token aan met uw toegangstoken als bearer-credential. Het antwoord bevat het nieuwe token, de host waaraan het gebonden is, en de levensduur in seconden:

// 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) Serveer het rendertoken aan de browser - gebruik het precies zoals een toegangstoken bij het aanroepen van sprucely_db of het mounten van Sprucely.Database. Herhaal de inwisseling vóór het serveren van elke pagina (of volgens een timer, als u de gerenderde pagina in cache bewaart), zodat de browser nooit een token ontvangt dat langer dan 15 minuten geldig is.

Functiereferentie

POST /api/auth/render_token - wisselt een geldig toegangstoken, verzonden als Authorization: Bearer <token>, in voor een rendertoken. Retourneert { token, host, expires_in }, waarbij expires_in vaststaat op 900 seconden. Een rendertoken kan niet worden ingewisseld voor een ander rendertoken - alleen een langlevend toegangstoken kan er een aanvragen.

Beveiligingsinstellingen

Als uw site een Content Security Policy (CSP) afdwingt, moeten de standalone JavaScript- en React-integraties hierboven een aantal bronnen toestaan voordat dashboards laden - de runtime laadt zijn script vanaf Sprucely.io, opent een browserdatabase op basis van WebAssembly, en valideert uw toegangstoken tegen onze API, en elk van deze acties vereist een expliciete CSP-toestemming. Als uw site geen CSP gebruikt, kunt u deze sectie overslaan.

Voeg de volgende bronnen toe aan uw bestaande policy - dit zijn directives om samen te voegen, niet een complete policy ter vervanging van wat u al heeft:

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;

Waar elke directive voor dient:

script-src - https://www.sprucely.io laadt het runtime-script. 'wasm-unsafe-eval' is vereist om de browserdatabase, die is gebouwd op WebAssembly, te compileren en uit te voeren.
connect-src - er wordt contact opgenomen met https://www.sprucely.io om uw toegangstoken te valideren en om de WebAssembly- en workerbestanden van de database te laden.
worker-src - de browserdatabase voert haar query’s uit op een thread op de achtergrond, aangemaakt vanuit een blob:-URL.

Geen van bovenstaande vereist 'unsafe-inline' - de Sprucely-runtime zelf heeft dit nooit nodig. Als u uw eigen dashboard- en datasetdefinities bewaart in een inline <script>-tag, zoals in het standalone JavaScript-voorbeeld hierboven, of als uw eigen pagina inline stijlen gebruikt, voegt u 'unsafe-inline' toe aan script-src of style-src, of overweegt u CSP-nonces.