Integration

Sie können interaktive Sprucely.io-Dashboards auf drei Arten in Ihre eigene Website oder Webanwendung integrieren: durch Einbetten mit einem Standard-HTML-iframe, durch natives Rendern mit der eigenständigen JavaScript-Runtime oder durch Einbinden der eigenständigen React-Komponenten. Der iframe lässt sich am schnellsten einrichten; die eigenständigen Runtimes zeichnen die Dashboards direkt in Ihre Seite und erlauben es Ihnen, zur Laufzeit neue Daten einzuspielen. Die JSON-Struktur, die die eigenständigen Runtimes einlesen - Dashboards, Diagramme und Datensätze - ist in der Referenz Datenformat dokumentiert. Für KI-gestützte Dashboard-Automatisierung siehe den Abschnitt MCP APIs.

Dashboards in HTML einbetten

Die einfachste Integration verwendet das Standard-HTML-Element iframe und funktioniert auf jeder Website oder sogar in lokalen HTML-Seiten. Damit es erfolgreich geladen werden kann, muss das Dashboard freigegeben sein - entweder in der Cloud oder On-Premise. Beachten Sie, dass On-Premise-Dashboards nur geladen werden, wenn der darauf zugreifende Client sich im selben Unternehmensnetzwerk befindet.

Anleitung:

1) Dashboard-Einbettungslink extrahieren - Stellen Sie auf der Seite Dashboards sicher, dass Ihr Dashboard freigegeben ist, und klicken Sie dann auf das -Symbol für dieses Dashboard. Ein grünes Popup-Banner informiert Sie darüber, dass der Link in die Zwischenablage kopiert wurde. Diesen verwenden Sie, um den src-Inhalt des HTML-iframe unten zu ersetzen.

2) Dashboard mit fester Größe einbetten

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

(oder) Dashboard mit dynamischer Breite einbetten - Passt die Größe des Dashboards automatisch an die Breite des übergeordneten Dokuments an

Sie können den Style-Parameter aspect-ratio verwenden, um die Höhe automatisch anhand der Breite neu zu berechnen.

<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) Weitere nützliche Einbettungsoptionen

Sie können dem Style-Block des iframe-Elements eigene Style-Anpassungen hinzufügen, um das Erscheinungsbild des Frames zu individualisieren. Diese Parameter folgen den gängigen CSS-Richtlinien für HTML. Das folgende Beispiel fügt einen grauen Rahmen um das Dashboard hinzu:

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

Einbetten mit eigenständigem JavaScript

Die eigenständige Runtime rendert Dashboards direkt innerhalb Ihrer Seite - ganz ohne iframe. Ihre Daten werden in eine Browser-interne Datenbank geladen und als vollständig interaktive Diagramme gezeichnet; die Runtime kontaktiert Sprucely.io lediglich, um Ihr Zugriffstoken zu validieren.

Anleitung:

1) Zugriffstoken erstellen - Erstellen Sie im Abschnitt Zugriffstokens Ihres Profils ein Zugriffstoken für die Origin, von der Ihre Seiten ausgeliefert werden (zum Beispiel https://www.yourdomain.com). Die Runtime prüft vor dem Rendern, ob die Origin der einbettenden Seite mit dem Token übereinstimmt.

2) Runtime laden und ein Dashboard rendern - Fügen Sie das Runtime-Skript in Ihre Seite ein, verbinden Sie die Browser-interne Datenbank einmalig mit sprucely_db und rendern Sie anschließend jedes Dashboard mit sprucely_create. Die vollständige Seite unten bindet außerdem eine Schaltfläche ein, die weitere Zeilen anhängt:

<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) Daten zur Laufzeit anhängen - Rufen Sie sprucely_add jederzeit mit zusätzlichen Zeilen auf. Jedes Dashboard, das den Datensatz verwendet, aktualisiert sich automatisch:

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

Funktionsreferenz

sprucely_db({ id, host, accessToken }) - verbindet die Browser-interne Datenbank und validiert Ihr Zugriffstoken gegen die Seiten-Origin. Rendert ein Statusbanner in das durch id identifizierte Element. Rufen Sie diese Funktion einmal pro Seite auf, bevor Sie Dashboards erstellen.
sprucely_create({ id, dashboard, data }) - rendert ein Dashboard in das durch id identifizierte Element. Der Parameter dashboard definiert Layout und Styling; data liefert den Datensatz mit Name, Headern, Spaltentypen (VARCHAR, INTEGER, FLOAT oder TIMESTAMP) und Zeilen - siehe die Referenz Datenformat.
sprucely_add(data) - hängt Zeilen an den Datensatz an, dessen Name mit einem bereits geladenen Datensatz übereinstimmt, und aktualisiert anschließend alle Dashboards, die ihn verwenden.

Einbetten mit eigenständigem React

Wenn Ihre Website mit React erstellt ist, können Sie Dashboards als Komponenten rendern, statt das Skript manuell zu laden. Die Komponenten verwenden dieselben Zugriffstoken, Dashboard-Definitionen und dasselbe Datensatzformat wie die eigenständige JavaScript-Runtime.

Anleitung:

1) Zugriffstoken erstellen - Erstellen Sie wie bei eigenständigem JavaScript ein Zugriffstoken für die Origin Ihrer Website im Abschnitt Zugriffstokens Ihres Profils.

2) Dashboard-Komponenten rendern - Beziehen Sie die Runtime von https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js und legen Sie sie in Ihrem Projekt ab. Binden Sie eine Sprucely.Database-Komponente pro Seite ein und eine Sprucely.Dashboard-Komponente pro Dashboard. Dashboards zeigen eine Ladeanzeige, bis die Datenbank das Zugriffstoken validiert hat, und rendern anschließend. Die vollständige Anwendung unten rendert zwei Dashboards aus getrennten Datensätzen und hängt nach fünf Sekunden neue Zeilen an das erste davon an:

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

Kurzlebige Tokens ausliefern

Das oben erstellte Zugriffstoken ist langlebig und soll ausschließlich als serverseitiges Geheimnis verbleiben. Liefert Ihr eigenes Backend die Einbettungsseiten aus - statt einer Seite ganz ohne eigenes Backend -, müssen Sie dieses langlebige Token überhaupt nicht in die Seite einbetten: Ihr Backend kann es Server-zu-Server gegen ein kurzlebiges (15 Minuten gültiges) Rendertoken eintauschen, unmittelbar bevor jede Seite ausgeliefert wird, sodass ausschließlich das Rendertoken jemals den Browser erreicht. Ein Rendertoken, das ein Besucher aus der Seite extrahiert, ist nur für wenige Minuten brauchbar, nicht auf unbestimmte Zeit.

Anleitung:

1) Zugriffstoken gegen ein Rendertoken eintauschen - Rufen Sie von Ihrem Backend aus POST https://www.sprucely.io/api/auth/render_token auf und übergeben Sie Ihr Zugriffstoken als Bearer-Anmeldedaten. Die Antwort enthält das neue Token, den zugehörigen Host und seine Gültigkeitsdauer in Sekunden:

// 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) Rendertoken an den Browser ausliefern - Verwenden Sie es beim Aufruf von sprucely_db oder beim Einbinden von Sprucely.Database genau wie ein Zugriffstoken. Wiederholen Sie den Austausch vor jeder ausgelieferten Seite (oder zeitgesteuert, wenn Sie die gerenderte Seite zwischenspeichern), sodass der Browser niemals ein länger als 15 Minuten gültiges Token erhält.

Funktionsreferenz

POST /api/auth/render_token - tauscht ein gültiges Zugriffstoken, gesendet als Authorization: Bearer <token>, gegen ein Rendertoken. Gibt { token, host, expires_in } zurück, wobei expires_in fest auf 900 Sekunden gesetzt ist. Ein Rendertoken kann nicht gegen ein weiteres Rendertoken eingetauscht werden - nur ein langlebiges Zugriffstoken kann eines anfordern.

Sicherheitseinstellungen

Wenn Ihre Website eine Content Security Policy (CSP) durchsetzt, benötigen die eigenständigen JavaScript- und React-Integrationen oben einige freigegebene Quellen, bevor Dashboards geladen werden - die Runtime lädt ihr Skript von Sprucely.io, öffnet eine Browser-interne, auf WebAssembly basierende Datenbank und validiert Ihr Zugriffstoken gegen unsere API, und jede dieser Aktionen benötigt eine explizite CSP-Freigabe. Verwendet Ihre Website keine CSP, können Sie diesen Abschnitt überspringen.

Fügen Sie die folgenden Quellen zu Ihrer bestehenden Richtlinie hinzu - dies sind Direktiven zum Zusammenführen, keine vollständige Richtlinie, die das Bestehende ersetzt:

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;

Wofür jede Direktive dient:

script-src - https://www.sprucely.io lädt das Runtime-Skript. 'wasm-unsafe-eval' wird benötigt, um die Browser-interne Datenbank, die auf WebAssembly basiert, zu kompilieren und auszuführen.
connect-src - https://www.sprucely.io wird kontaktiert, um Ihr Zugriffstoken zu validieren und die WebAssembly- und Worker-Dateien der Datenbank zu laden.
worker-src - die Browser-interne Datenbank führt ihre Abfragen in einem Hintergrundthread aus, der aus einer blob:-URL erstellt wird.

Nichts davon erfordert 'unsafe-inline' - die Sprucely-Runtime selbst benötigt es nie. Wenn Sie Ihre eigenen Dashboard- und Datensatzdefinitionen wie im obigen Beispiel für eigenständiges JavaScript in einem Inline-<script>-Tag halten oder Ihre eigene Seite Inline-Styles verwendet, fügen Sie 'unsafe-inline' zu script-src oder style-src hinzu, oder erwägen Sie CSP-Nonces.