Entegrasyon

Etkileşimli Sprucely.io panolarını kendi web sitenize veya web uygulamanıza üç şekilde entegre edebilirsiniz: standart bir HTML iframe ile gömerek, bağımsız JavaScript çalışma zamanıyla yerel olarak oluşturarak veya bağımsız React bileşenlerini yerleştirerek. iframe, kurulumu en hızlı olan yöntemdir; bağımsız çalışma zamanları panoları doğrudan sayfanıza çizer ve çalışma zamanında yeni veri eklemenize olanak tanır. Bağımsız çalışma zamanlarının okuduğu JSON yapısı - panolar, grafikler ve veri kümeleri - veri formatı referansında belgelenmiştir. Yapay zekâ destekli pano otomasyonu için MCP API’leri bölümüne bakın.

Panoları HTML İçine Gömme

En basit entegrasyon, standart HTML iframe öğesini kullanır ve herhangi bir web sitesinde, hatta yerel HTML sayfalarında bile çalışır. Panonun başarıyla yüklenebilmesi için Bulutta veya Şirket İçinde paylaşılmış olması gerekir. Şirket İçi panoların yalnızca kendisine erişen istemci aynı kurumsal ağ içindeyken yükleneceğini unutmayın.

Talimatlar:

1) Pano gömme bağlantısını alın - Panolar sayfasında panonuzun paylaşıldığından emin olun ve ardından bu pano için simgesine tıklayın. Bağlantının panoya kopyalandığını bildiren yeşil bir açılır banner görüntülenecektir. Bunu, aşağıdaki HTML iframe öğesinin src içeriğinin yerine koymak için kullanacaksınız.

2) Panoyu sabit bir boyutla gömün

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

(veya) Panoyu dinamik genişlikle gömün - Panoyu, üst dokümanın genişliğine göre otomatik olarak yeniden boyutlandırır

Genişliğe göre yüksekliği otomatik olarak yeniden hesaplamak için aspect-ratio stil parametresini kullanabilirsiniz.

<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) Diğer kullanışlı gömme seçenekleri

Çerçevenin görünümünü ve hissini özelleştirmek için iframe öğesinin style bloğuna özel stil değişiklikleri ekleyebilirsiniz. Bu parametreler standart HTML CSS yönergelerini izler. Aşağıdaki örnek, panonun etrafına gri bir kenarlık ekler:

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

Bağımsız JavaScript ile Gömme

Bağımsız çalışma zamanı, panoları doğrudan sayfanızın içinde oluşturur - iframe gerekmez. Verileriniz tarayıcı içi bir veritabanına yüklenir ve tamamen etkileşimli grafikler olarak çizilir; çalışma zamanı yalnızca erişim tokeninizi doğrulamak için Sprucely.io ile iletişime geçer.

Talimatlar:

1) Bir erişim tokeni oluşturun - Profilinizin Erişim Tokenleri bölümünde, sayfalarınızın sunulduğu köken için bir erişim tokeni oluşturun (örneğin https://www.yourdomain.com). Çalışma zamanı, oluşturmadan önce gömülü sayfanın kökeninin token ile eşleştiğini doğrular.

2) Çalışma zamanını yükleyin ve bir pano oluşturun - Çalışma zamanı betiğini sayfanıza ekleyin, tarayıcı içi veritabanını sprucely_db ile bir kez bağlayın, ardından her panoyu sprucely_create ile oluşturun. Aşağıdaki eksiksiz sayfa, daha fazla satır ekleyen bir düğmeyi de devreye alır:

<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) Çalışma zamanında veri ekleyin - İstediğiniz zaman ek satırlarla sprucely_add öğesini çağırın. Bu veri kümesini kullanan her pano otomatik olarak yenilenir:

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

İşlev referansı

sprucely_db({ id, host, accessToken }) - tarayıcı içi veritabanını bağlar ve erişim tokeninizi sayfa kökenine göre doğrular. id ile tanımlanan öğenin içine bir durum banner’ı oluşturur. Panolar oluşturmadan önce, sayfa başına bir kez çağırın.
sprucely_create({ id, dashboard, data }) - id ile tanımlanan öğenin içine bir pano oluşturur. dashboard parametresi düzeni ve stili tanımlar; data ise veri kümesini adı, başlıkları, sütun türleri (VARCHAR, INTEGER, FLOAT veya TIMESTAMP) ve satırlarıyla birlikte sağlar - bkz. veri formatı referansı.
sprucely_add(data) - adı, zaten yüklenmiş bir veri kümesiyle eşleşen veri kümesine satırlar ekler, ardından onu kullanan tüm panoları yeniler.

Bağımsız React ile Gömme

Siteniz React ile oluşturulduysa, betiği manuel olarak yüklemek yerine panoları bileşenler olarak oluşturabilirsiniz. Bu bileşenler, bağımsız JavaScript çalışma zamanıyla aynı erişim tokenlerini, pano tanımlarını ve veri kümesi formatını kullanır.

Talimatlar:

1) Bir erişim tokeni oluşturun - Bağımsız JavaScript’te olduğu gibi, profilinizin Erişim Tokenleri bölümünde sitenizin kökeni için bir erişim tokeni oluşturun.

2) Pano bileşenlerini oluşturun - Çalışma zamanını https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js adresinden alın ve projenize yerleştirin. Sayfa başına bir Sprucely.Database bileşeni, pano başına bir Sprucely.Dashboard bileşeni yerleştirin. Panolar, veritabanı erişim tokenini doğrulayana kadar bir yükleme göstergesi gösterir, ardından oluşturulur. Aşağıdaki eksiksiz uygulama, ayrı veri kümelerinden iki pano oluşturur ve beş saniye sonra ilkine yeni satırlar ekler:

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

Kısa Ömürlü Anahtarlar Sunma

Yukarıda oluşturduğunuz erişim tokeni uzun ömürlüdür ve sunucu tarafında gizli kalması amaçlanmıştır. Gömme sayfalarını - kendi arka ucu olmayan bir sayfanın aksine - kendi arka ucunuz sunuyorsa, bu uzun ömürlü tokeni sayfaya hiç koymanıza gerek yoktur - arka ucunuz, her sayfayı sunmadan hemen önce onu sunucudan sunucuya kısa ömürlü (15 dakikalık) bir render tokeniyle değiştirebilir ve tarayıcıya yalnızca bu render tokeni ulaşır. Bir ziyaretçinin sayfadan çıkardığı render tokeni yalnızca birkaç dakika boyunca işe yarar, süresiz değil.

Talimatlar:

1) Erişim tokeninizi bir render tokeniyle değiştirin - arka ucunuzdan, erişim tokeninizi taşıyıcı kimlik bilgisi olarak kullanarak POST https://www.sprucely.io/api/auth/render_token çağrısı yapın. Yanıt, yeni tokeni, bağlı olduğu kökeni ve saniye cinsinden ömrünü taşır:

// 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) Render tokenini tarayıcıya sunun - bunu, sprucely_db öğesini çağırırken veya Sprucely.Database öğesini bağlarken tam olarak bir erişim tokeni gibi kullanın. Her sayfayı sunmadan önce bu değişimi tekrarlayın (oluşturulan sayfayı önbelleğe alıyorsanız bir zamanlayıcıyla), böylece tarayıcı hiçbir zaman 15 dakikadan uzun süre geçerli bir token almaz.

İşlev referansı

POST /api/auth/render_token - Authorization: Bearer <token> olarak gönderilen geçerli bir erişim tokenini bir render tokeniyle değiştirir. { token, host, expires_in } döndürür; expires_in değeri sabit olarak 900 saniyeye ayarlanmıştır. Bir render tokeni başka bir render tokeniyle değiştirilemez - yalnızca uzun ömürlü bir erişim tokeni bir tane talep edebilir.

Güvenlik Ayarları

Siteniz bir İçerik Güvenliği Politikası (CSP) uyguluyorsa, yukarıdaki bağımsız JavaScript ve React entegrasyonlarının panoların yüklenebilmesi için birkaç kaynağa izin verilmesi gerekir - çalışma zamanı betiğini Sprucely.io’dan yükler, WebAssembly tabanlı bir tarayıcı içi veritabanı açar ve erişim tokeninizi API’mize karşı doğrular; bunların her biri açık bir CSP izni gerektirir. Siteniz CSP kullanmıyorsa bu bölümü atlayabilirsiniz.

Aşağıdaki kaynakları mevcut politikanıza ekleyin - bunlar birleştirilecek yönergelerdir, sahip olduğunuz politikanın yerine geçecek eksiksiz bir politika değildir:

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;

Her yönergenin amacı:

script-src - https://www.sprucely.io, çalışma zamanı betiğini yükler. WebAssembly üzerine inşa edilen tarayıcı içi veritabanını derlemek ve çalıştırmak için 'wasm-unsafe-eval' gereklidir.
connect-src - erişim tokeninizi doğrulamak ve veritabanının WebAssembly ile worker dosyalarını yüklemek için https://www.sprucely.io ile iletişime geçilir.
worker-src - tarayıcı içi veritabanı, sorgularını blob: URL’sinden oluşturulan bir arka plan iş parçacığında çalıştırır.

Yukarıdakilerin hiçbiri 'unsafe-inline' gerektirmez - Sprucely çalışma zamanının kendisi buna hiçbir zaman ihtiyaç duymaz. Yukarıdaki bağımsız JavaScript örneğinde olduğu gibi kendi pano ve veri kümesi tanımlarınızı satır içi bir <script> etiketinde tutuyorsanız veya kendi sayfanız satır içi stiller kullanıyorsa, 'unsafe-inline' öğesini script-src veya style-src içine ekleyin ya da CSP nonce’larını değerlendirin.