Integracja

Interaktywne dashboardy Sprucely.io możesz zintegrować z własną witryną lub aplikacją internetową na trzy sposoby: osadzając je za pomocą standardowego elementu HTML iframe, renderując je natywnie za pomocą samodzielnego środowiska uruchomieniowego JavaScript, albo montując samodzielne komponenty React. iframe konfiguruje się najszybciej; samodzielne środowiska uruchomieniowe rysują dashboardy bezpośrednio na Twojej stronie i pozwalają na bieżąco dopisywać nowe dane w trakcie działania. Struktura JSON odczytywana przez samodzielne środowiska uruchomieniowe - dashboardy, wykresy i zbiory danych - jest opisana w referencji format danych. Informacje o automatyzacji dashboardów sterowanej przez AI znajdziesz w sekcji MCP API.

Osadzanie dashboardów w HTML

Najprostsza integracja wykorzystuje standardowy element HTML iframe i działa na dowolnej witrynie, a nawet na lokalnych stronach HTML. Aby dashboard poprawnie się załadował, musi być udostępniony - w Chmurze albo On-premise. Pamiętaj, że dashboardy On-premise ładują się wyłącznie wtedy, gdy klient uzyskujący do nich dostęp znajduje się w tej samej sieci firmowej.

Instrukcje:

1) Pobierz link do osadzenia dashboardu - Na stronie Dashboardy upewnij się, że Twój dashboard jest udostępniony, a następnie kliknij ikonę przy tym dashboardzie. Zielony baner powiadomi Cię, że link został skopiowany do schowka. Użyjesz go, aby zastąpić poniższą zawartość atrybutu src elementu HTML iframe.

2) Osadź dashboard w stałym rozmiarze

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

(lub) Osadź dashboard z dynamiczną szerokością - Automatycznie dostosowuje rozmiar dashboardu na podstawie szerokości dokumentu nadrzędnego

Możesz użyć parametru stylu aspect-ratio, aby automatycznie przeliczać wysokość na podstawie szerokości.

<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) Inne przydatne opcje osadzania

Możesz dodać własne modyfikacje stylu do bloku style elementu iframe, aby dostosować wygląd ramki. Te parametry są zgodne ze standardowymi wytycznymi HTML/CSS. Poniższy przykład dodaje szare obramowanie wokół dashboardu:

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

Osadzanie za pomocą samodzielnego JavaScript

Samodzielne środowisko uruchomieniowe renderuje dashboardy bezpośrednio na Twojej stronie - bez iframe. Twoje dane są wczytywane do bazy danych działającej w przeglądarce i rysowane jako w pełni interaktywne wykresy; środowisko uruchomieniowe kontaktuje się ze Sprucely.io wyłącznie w celu zweryfikowania Twojego tokenu dostępu.

Instrukcje:

1) Utwórz token dostępu - W sekcji Tokeny dostępu swojego profilu utwórz token dostępu dla źródła (origin), z którego serwowane są Twoje strony (na przykład https://www.yourdomain.com). Przed renderowaniem środowisko uruchomieniowe sprawdza, czy źródło osadzającej strony zgadza się z tokenem.

2) Wczytaj środowisko uruchomieniowe i wyrenderuj dashboard - Dodaj skrypt środowiska uruchomieniowego do swojej strony, połącz raz bazę danych działającą w przeglądarce za pomocą sprucely_db, a następnie wyrenderuj każdy dashboard za pomocą sprucely_create. Poniższa kompletna strona podpina też przycisk, który dopisuje kolejne wiersze:

<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) Dopisuj dane w trakcie działania - W dowolnym momencie wywołaj sprucely_add z dodatkowymi wierszami. Każdy dashboard korzystający z tego zbioru danych odświeży się automatycznie:

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

Opis funkcji

sprucely_db({ id, host, accessToken }) - łączy bazę danych działającą w przeglądarce i weryfikuje Twój token dostępu względem źródła strony. Renderuje baner statusu w elemencie wskazanym przez id. Wywołaj ją raz na stronę, przed utworzeniem dashboardów.
sprucely_create({ id, dashboard, data }) - renderuje jeden dashboard w elemencie wskazanym przez id. Parametr dashboard definiuje układ i stylowanie; data dostarcza zbiór danych wraz z jego nazwą, nagłówkami, typami kolumn (VARCHAR, INTEGER, FLOAT lub TIMESTAMP) i wierszami - patrz referencja format danych.
sprucely_add(data) - dopisuje wiersze do zbioru danych, którego nazwa zgadza się z już wczytanym zbiorem danych, a następnie odświeża wszystkie dashboardy, które go używają.

Osadzanie za pomocą samodzielnego React

Jeśli Twoja witryna jest zbudowana w React, możesz renderować dashboardy jako komponenty zamiast ręcznie wczytywać skrypt. Komponenty korzystają z tych samych tokenów dostępu, definicji dashboardu i formatu zbioru danych co samodzielne środowisko uruchomieniowe JavaScript.

Instrukcje:

1) Utwórz token dostępu - Podobnie jak w przypadku samodzielnego JavaScript, utwórz token dostępu dla źródła swojej witryny w sekcji Tokeny dostępu swojego profilu.

2) Wyrenderuj komponenty dashboardu - Pobierz środowisko uruchomieniowe z https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js i umieść je w swoim projekcie. Zamontuj jeden komponent Sprucely.Database na stronę oraz jeden komponent Sprucely.Dashboard na dashboard. Dashboardy pokazują wskaźnik ładowania, dopóki baza danych nie zweryfikuje tokenu dostępu, a następnie się renderują. Poniższa kompletna aplikacja renderuje dwa dashboardy z osobnych zbiorów danych i po pięciu sekundach dopisuje nowe wiersze do pierwszego z nich:

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

Wydawanie krótkotrwałych tokenów

Token dostępu, który tworzysz powyżej, jest długoterminowy i ma pozostać sekretem po stronie serwera. Jeśli strony z osadzonym dashboardem serwuje Twój własny backend - a nie strona pozbawiona własnego backendu - wcale nie musisz umieszczać na niej tego długoterminowego tokenu - Twój backend może wymienić go, w komunikacji serwer-serwer, na krótkotrwały (15-minutowy) token renderowania tuż przed wysłaniem każdej strony, dzięki czemu do przeglądarki trafia wyłącznie token renderowania. Token renderowania, który odwiedzający wyodrębni ze strony, jest użyteczny jedynie przez kilka minut, a nie bezterminowo.

Instrukcje:

1) Wymień token dostępu na token renderowania - z poziomu swojego backendu wywołaj POST https://www.sprucely.io/api/auth/render_token z tokenem dostępu jako poświadczeniem bearer. Odpowiedź zawiera nowy token, powiązany z nim host oraz czas jego ważności w sekundach:

// 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) Prześlij token renderowania do przeglądarki - używaj go dokładnie tak jak tokenu dostępu przy wywoływaniu sprucely_db lub montowaniu Sprucely.Database. Powtarzaj wymianę przed wysłaniem każdej strony (lub cyklicznie, jeśli renderowaną stronę buforujesz), tak aby przeglądarka nigdy nie otrzymywała tokenu ważnego dłużej niż 15 minut.

Opis funkcji

POST /api/auth/render_token - wymienia ważny token dostępu, przesłany jako Authorization: Bearer <token>, na token renderowania. Zwraca { token, host, expires_in }, przy czym expires_in jest zawsze równe 900 sekund. Tokenu renderowania nie można wymienić na kolejny token renderowania - o nowy token może wystąpić wyłącznie długoterminowy token dostępu.

Ustawienia zabezpieczeń

Jeśli Twoja witryna wymusza Content Security Policy (CSP), opisane powyżej integracje samodzielnego JavaScript i React wymagają dopuszczenia kilku źródeł, zanim dashboardy się załadują - środowisko uruchomieniowe wczytuje swój skrypt ze Sprucely.io, otwiera bazę danych działającą w przeglądarce opartą na WebAssembly oraz weryfikuje Twój token dostępu względem naszego API, a każdy z tych elementów wymaga jawnego dopuszczenia w CSP. Jeśli Twoja witryna nie korzysta z CSP, możesz pominąć tę sekcję.

Dodaj poniższe źródła do swojej istniejącej polityki - są to dyrektywy do połączenia z tym, co już masz, a nie kompletna polityka mająca to zastąpić:

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;

Do czego służy każda dyrektywa:

script-src - https://www.sprucely.io wczytuje skrypt środowiska uruchomieniowego. 'wasm-unsafe-eval' jest wymagane do skompilowania i uruchomienia bazy danych działającej w przeglądarce, która jest zbudowana na WebAssembly.
connect-src - https://www.sprucely.io jest kontaktowane w celu zweryfikowania Twojego tokenu dostępu oraz wczytania plików WebAssembly i workera bazy danych.
worker-src - baza danych działająca w przeglądarce wykonuje swoje zapytania w wątku w tle, utworzonym z adresu URL blob:.

Żadna z powyższych dyrektyw nie wymaga 'unsafe-inline' - samo środowisko uruchomieniowe Sprucely nigdy go nie potrzebuje. Jeśli własne definicje dashboardu i zbioru danych trzymasz w tagu inline <script>, tak jak w powyższym przykładzie samodzielnego JavaScript, albo Twoja strona korzysta ze stylów inline, dodaj 'unsafe-inline' do script-src lub style-src, albo rozważ użycie CSP nonce.