Integraatio

Voit integroida interaktiiviset Sprucely.io-kojelaudat omaan verkkosivustoosi tai verkkosovellukseesi kolmella tavalla: upottamalla ne tavanomaisella HTML iframe -elementillä, renderöimällä ne natiivisti itsenäisen JavaScript-ajoympäristön avulla tai liittämällä itsenäiset React-komponentit. iframe on nopein tapa ottaa käyttöön; itsenäiset ajoympäristöt piirtävät kojelaudat suoraan sivullesi ja antavat sinun syöttää uutta dataa ajon aikana. JSON-rakenne, jota itsenäiset ajoympäristöt lukevat - kojelaudat, kaaviot ja datasetit - on dokumentoitu tietomuoto-viitteessä. Tekoälypohjaista kojelautojen automatisointia varten katso MCP-rajapinnat-osio.

Kojelautojen upottaminen HTML:ään

Yksinkertaisin integrointitapa käyttää vakiomuotoista HTML iframe -elementtiä ja toimii millä tahansa verkkosivustolla, jopa paikallisilla HTML-sivuilla. Kojelaudan on oltava jaettu, joko Cloudissa tai On-premise-ympäristössä, jotta se latautuu onnistuneesti. Huomaa, että On-premise-kojelaudat latautuvat vain, kun sitä käyttävä laite on samassa yritysverkossa.

Ohjeet:

1) Hae kojelaudan upotuslinkki - Koontinäytöt-sivulla varmista, että kojelautasi on jaettu, ja napsauta sitten tämän kojelaudan -kuvaketta. Vihreä ponnahdusilmoitus kertoo, että linkki on kopioitu leikepöydälle. Käytät tätä korvataksesi alla olevan HTML iframe -elementin src-sisällön.

2) Upota kojelauta kiinteällä koolla

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

(tai) Upota kojelauta dynaamisella leveydellä - Muuttaa kojelaudan kokoa automaattisesti isäntäsivun leveyden perusteella

Voit käyttää aspect-ratio-tyyliparametria korkeuden automaattiseen uudelleenlaskentaan leveyden perusteella.

<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) Muita hyödyllisiä upotusvaihtoehtoja

Voit lisätä omia tyylimuutoksia iframe-elementin style-lohkoon mukauttaaksesi kehyksen ulkoasua. Nämä parametrit noudattavat tavanomaisia HTML CSS -ohjeita. Alla oleva esimerkki lisää kojelaudan ympärille harmaan reunuksen:

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

Upottaminen itsenäisellä JavaScriptillä

Itsenäinen ajoympäristö piirtää kojelaudat suoraan sivullesi - ei iframe-elementtiä. Datasi ladataan selaimen sisäiseen tietokantaan ja piirretään täysin interaktiivisiksi kaavioiksi; ajoympäristö ottaa yhteyttä vain Sprucely.ioon pääsytunnuksesi validoimiseksi.

Ohjeet:

1) Luo pääsytunnus - Luo profiilisi Pääsytunnukset-osiossa pääsytunnus sille alkuperälle, josta sivusi tarjoillaan (esimerkiksi https://www.yourdomain.com). Ajoympäristö varmistaa, että upottavan sivun alkuperä vastaa tunnusta ennen renderöintiä.

2) Lataa ajoympäristö ja renderöi kojelauta - Lisää ajoympäristön skripti sivullesi, yhdistä selaimen sisäinen tietokanta kerran komennolla sprucely_db ja renderöi sitten jokainen kojelauta komennolla sprucely_create. Alla oleva täydellinen sivu kytkee myös painikkeen, joka lisää rivejä:

<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) Lisää dataa ajon aikana - Kutsu komentoa sprucely_add lisärivien kanssa milloin tahansa. Jokainen datasetiä käyttävä kojelauta päivittyy automaattisesti:

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

Funktioreferenssi

sprucely_db({ id, host, accessToken }) - yhdistää selaimen sisäisen tietokannan ja validoi pääsytunnuksesi sivun alkuperää vasten. Renderöi tilailmoituksen id:llä tunnistettuun elementtiin. Kutsu sitä kerran per sivu, ennen kojelautojen luomista.
sprucely_create({ id, dashboard, data }) - renderöi yhden kojelaudan id:llä tunnistettuun elementtiin. dashboard-parametri määrittää asettelun ja tyylin; data-parametri toimittaa datasetin nimineen, otsikkoineen, saraketyyppeineen (VARCHAR, INTEGER, FLOAT tai TIMESTAMP) ja riveineen - katso tietomuoto-viite.
sprucely_add(data) - lisää rivejä datasetiin, jonka nimi vastaa jo ladatun datasetin nimeä, ja päivittää sitten kaikki sitä käyttävät kojelaudat.

Upottaminen itsenäisellä Reactilla

Jos sivustosi on rakennettu Reactilla, voit renderöidä kojelaudat komponentteina sen sijaan, että lataisit skriptin manuaalisesti. Komponentit käyttävät samoja pääsytunnuksia, kojelautamäärittelyjä ja datasetin muotoa kuin itsenäinen JavaScript-ajoympäristö.

Ohjeet:

1) Luo pääsytunnus - Luo sivustosi alkuperälle pääsytunnus profiilisi Pääsytunnukset-osiossa, samoin kuin itsenäisen JavaScriptin kanssa.

2) Renderöi kojelautakomponentit - Hae ajoympäristö osoitteesta https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js ja sijoita se projektiisi. Liitä yksi Sprucely.Database-komponentti per sivu ja yksi Sprucely.Dashboard-komponentti per kojelauta. Kojelaudat näyttävät latausilmaisimen, kunnes tietokanta on validoinut pääsytunnuksen, ja renderöityvät sitten. Alla oleva täydellinen sovellus renderöi kaksi kojelautaa kahdesta erillisestä datasetista ja lisää uusia rivejä ensimmäiseen viiden sekunnin kuluttua:

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

Lyhytaikaisten avainten tarjoaminen

Yllä luomasi pääsytunnus on pitkäikäinen, ja sen on tarkoitus pysyä palvelinpuolen salaisuutena. Jos oma backendisi tarjoilee upotettavat sivut - ei siis sivu, jolla ei ole omaa backendiä - sinun ei tarvitse sijoittaa pitkäikäistä tunnusta sivulle lainkaan - backendisi voi vaihtaa sen palvelimelta palvelimelle lyhytikäiseksi (15 minuutin) renderöintitunnukseksi juuri ennen kunkin sivun tarjoilua, ja vain renderöintitunnus päätyy koskaan selaimeen. Vierailijan sivulta poimima renderöintitunnus on hyödyllinen vain muutaman minuutin ajan, ei rajattomasti.

Ohjeet:

1) Vaihda pääsytunnuksesi renderöintitunnukseksi - kutsu backendistäsi komentoa POST https://www.sprucely.io/api/auth/render_token käyttäen pääsytunnustasi bearer-tunnistetietona. Vastaus sisältää uuden tunnuksen, sen sidotun isännän ja sen elinajan sekunteina:

// 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) Tarjoile renderöintitunnus selaimelle - käytä sitä täsmälleen samalla tavalla kuin pääsytunnusta kutsuessasi komentoa sprucely_db tai liittäessäsi komponenttia Sprucely.Database. Toista vaihto ennen jokaisen sivun tarjoilua (tai ajastimen mukaan, jos välimuistitat renderöidyn sivun), jotta selain ei koskaan saa tunnusta, joka on voimassa yli 15 minuuttia.

Funktioreferenssi

POST /api/auth/render_token - vaihtaa voimassa olevan pääsytunnuksen, joka lähetetään muodossa Authorization: Bearer <token>, renderöintitunnukseksi. Palauttaa muodon { token, host, expires_in }, jossa expires_in on kiinteästi 900 sekuntia. Renderöintitunnusta ei voi vaihtaa toiseksi renderöintitunnukseksi - vain pitkäikäinen pääsytunnus voi pyytää sellaisen.

Suojausasetukset

Jos sivustosi toteuttaa Content Security Policyn (CSP), yllä olevat itsenäiset JavaScript- ja React-integraatiot tarvitsevat muutaman sallitun lähteen, ennen kuin kojelaudat latautuvat - ajoympäristö lataa skriptinsä Sprucely.iosta, avaa WebAssemblyyn perustuvan selaimen sisäisen tietokannan ja validoi pääsytunnuksesi rajapintaamme vasten, ja jokainen näistä tarvitsee nimenomaisen CSP-sallinnan. Jos sivustosi ei käytä CSP:tä, voit ohittaa tämän osion.

Lisää seuraavat lähteet olemassa olevaan käytäntöösi - nämä ovat direktiivejä, jotka yhdistetään mukaan, ei täydellistä käytäntöä, joka korvaisi jo käytössä olevan:

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;

Mihin kukin direktiivi tarvitaan:

script-src - https://www.sprucely.io lataa ajoympäristön skriptin. 'wasm-unsafe-eval' vaaditaan kääntämään ja ajamaan selaimen sisäistä tietokantaa, joka on rakennettu WebAssemblyn päälle.
connect-src - https://www.sprucely.io-osoitteeseen otetaan yhteyttä pääsytunnuksesi validoimiseksi ja tietokannan WebAssembly- ja worker-tiedostojen lataamiseksi.
worker-src - selaimen sisäinen tietokanta ajaa kyselynsä taustasäikeessä, joka luodaan blob:-URL:sta.

Mikään yllä olevista ei vaadi 'unsafe-inline' - Sprucely-ajoympäristö itse ei koskaan tarvitse sitä. Jos säilytät omat kojelauta- ja datasetmäärittelysi inline <script>-tagissa, kuten yllä olevassa itsenäisen JavaScriptin esimerkissä, tai omalla sivullasi käytetään inline-tyylejä, lisää 'unsafe-inline' kohteeseen script-src tai style-src, tai harkitse CSP-nonce-arvojen käyttöä.