एकीकरण

आप इंटरैक्टिव Sprucely.io डैशबोर्ड को अपनी वेबसाइट या वेब एप्लिकेशन में तीन तरीकों से एकीकृत कर सकते हैं: एक स्टैंडर्ड HTML iframe के साथ एम्बेड करके, स्टैंडअलोन JavaScript रनटाइम के साथ नेटिव रूप से रेंडर करके, या स्टैंडअलोन React कॉम्पोनेंट्स माउंट करके। iframe सेट अप करने में सबसे तेज़ है; स्टैंडअलोन रनटाइम डैशबोर्ड को सीधे आपके पेज में बनाते हैं और आपको रनटाइम पर नया डेटा पुश करने देते हैं। स्टैंडअलोन रनटाइम जिस JSON शेप को पढ़ते हैं - डैशबोर्ड, चार्ट और डेटासेट - वह डेटा प्रारूप रेफरेंस में दस्तावेज़ीकृत है। AI-संचालित डैशबोर्ड ऑटोमेशन के लिए, MCP APIs सेक्शन देखें।

HTML में डैशबोर्ड एम्बेड करना

सबसे सरल एकीकरण स्टैंडर्ड HTML iframe एलिमेंट का उपयोग करता है और किसी भी वेबसाइट पर, यहां तक कि लोकल HTML पेजों पर भी काम करता है। डैशबोर्ड को सफलतापूर्वक लोड होने के लिए साझा किया जाना ज़रूरी है, चाहे क्लाउड में हो या ऑन-प्रिमाइस में। ध्यान दें कि ऑन-प्रिमाइस डैशबोर्ड तभी लोड होंगे जब इसे एक्सेस करने वाला क्लाइंट उसी कॉर्पोरेट नेटवर्क में हो।

निर्देश:

1) डैशबोर्ड एम्बेड लिंक प्राप्त करें - डैशबोर्ड पेज पर, सुनिश्चित करें कि आपका डैशबोर्ड साझा किया गया है, और फिर इस डैशबोर्ड के लिए आइकन पर क्लिक करें। एक हरा पॉपअप बैनर आपको सूचित करेगा कि लिंक क्लिपबोर्ड पर कॉपी हो गया है। इसका उपयोग आप नीचे दिए गए HTML iframe के src कंटेंट को बदलने के लिए करेंगे।

2) डैशबोर्ड को फिक्स्ड साइज़ के साथ एम्बेड करें

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

(या) डैशबोर्ड को डायनामिक चौड़ाई के साथ एम्बेड करें - पैरेंट डॉक्यूमेंट की चौड़ाई के आधार पर डैशबोर्ड का साइज़ अपने आप बदलता है

आप चौड़ाई के आधार पर ऊंचाई को अपने आप फिर से कैलकुलेट करने के लिए aspect-ratio स्टाइल पैरामीटर का उपयोग कर सकते हैं।

<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) अन्य उपयोगी एम्बेड विकल्प

आप फ्रेम के लुक और फील को कस्टमाइज़ करने के लिए iframe एलिमेंट के स्टाइल ब्लॉक में कस्टम स्टाइल मॉडिफिकेशन जोड़ सकते हैं। ये पैरामीटर स्टैंडर्ड HTML CSS दिशानिर्देशों का पालन करते हैं। नीचे दिया गया उदाहरण डैशबोर्ड के चारों ओर एक ग्रे बॉर्डर जोड़ता है:

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

स्टैंडअलोन JavaScript के साथ एम्बेड करना

स्टैंडअलोन रनटाइम डैशबोर्ड को सीधे आपके पेज के अंदर रेंडर करता है - कोई iframe नहीं। आपका डेटा एक इन-ब्राउज़र डेटाबेस में लोड होता है और पूरी तरह इंटरैक्टिव चार्ट के रूप में बनाया जाता है; रनटाइम केवल आपके एक्सेस टोकन को वैलिडेट करने के लिए Sprucely.io से संपर्क करता है।

निर्देश:

1) एक्सेस टोकन बनाएं - अपनी प्रोफाइल के एक्सेस टोकन सेक्शन में, उस ओरिजिन के लिए एक एक्सेस टोकन बनाएं जहां से आपके पेज सर्व किए जाते हैं (उदाहरण के लिए https://www.yourdomain.com)। रेंडर करने से पहले रनटाइम यह वैलिडेट करता है कि एम्बेड करने वाले पेज का ओरिजिन टोकन से मेल खाता है।

2) रनटाइम लोड करें और एक डैशबोर्ड रेंडर करें - अपने पेज में रनटाइम स्क्रिप्ट जोड़ें, sprucely_db के साथ इन-ब्राउज़र डेटाबेस को एक बार कनेक्ट करें, फिर sprucely_create के साथ हर डैशबोर्ड को रेंडर करें। नीचे दिया गया पूरा पेज एक बटन भी जोड़ता है जो और पंक्तियां जोड़ता है:

<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) रनटाइम पर डेटा जोड़ें - किसी भी समय अतिरिक्त पंक्तियों के साथ sprucely_add को कॉल करें। उस डेटासेट का उपयोग करने वाला हर डैशबोर्ड अपने आप रिफ्रेश हो जाता है:

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

फ़ंक्शन रेफरेंस

sprucely_db({ id, host, accessToken }) - इन-ब्राउज़र डेटाबेस को कनेक्ट करता है और पेज ओरिजिन के विरुद्ध आपके एक्सेस टोकन को वैलिडेट करता है। id से पहचाने गए एलिमेंट में एक स्टेटस बैनर रेंडर करता है। डैशबोर्ड बनाने से पहले, इसे प्रति पेज एक बार कॉल करें।
sprucely_create({ id, dashboard, data }) - id से पहचाने गए एलिमेंट में एक डैशबोर्ड रेंडर करता है। dashboard पैरामीटर लेआउट और स्टाइलिंग परिभाषित करता है; data डेटासेट को उसके नाम, हेडर, कॉलम टाइप्स (VARCHAR, INTEGER, FLOAT या TIMESTAMP) और पंक्तियों के साथ प्रदान करता है - डेटा प्रारूप रेफरेंस देखें।
sprucely_add(data) - उस डेटासेट में पंक्तियां जोड़ता है जिसका नाम पहले से लोड किए गए डेटासेट से मेल खाता है, फिर उसका उपयोग करने वाले सभी डैशबोर्ड को रिफ्रेश करता है।

स्टैंडअलोन React के साथ एम्बेड करना

अगर आपकी साइट React से बनी है, तो आप स्क्रिप्ट को मैन्युअली लोड करने के बजाय डैशबोर्ड को कॉम्पोनेंट्स के रूप में रेंडर कर सकते हैं। ये कॉम्पोनेंट्स स्टैंडअलोन JavaScript रनटाइम जैसे ही एक्सेस टोकन, डैशबोर्ड डेफिनिशन और डेटासेट फॉर्मेट का उपयोग करते हैं।

निर्देश:

1) एक्सेस टोकन बनाएं - स्टैंडअलोन JavaScript की तरह ही, अपनी प्रोफाइल के एक्सेस टोकन सेक्शन में अपनी साइट के ओरिजिन के लिए एक एक्सेस टोकन बनाएं।

2) डैशबोर्ड कॉम्पोनेंट्स रेंडर करें - रनटाइम को https://www.sprucely.io/cross-origin/sprucely-runtime.min.cjs.js से प्राप्त करें और इसे अपने प्रोजेक्ट में रखें। हर पेज पर एक Sprucely.Database कॉम्पोनेंट माउंट करें, और हर डैशबोर्ड के लिए एक Sprucely.Dashboard कॉम्पोनेंट। जब तक डेटाबेस एक्सेस टोकन को वैलिडेट नहीं कर लेता, तब तक डैशबोर्ड एक लोडिंग इंडिकेटर दिखाते हैं, फिर रेंडर होते हैं। नीचे दिया गया पूरा एप्लिकेशन अलग-अलग डेटासेट से दो डैशबोर्ड रेंडर करता है और पांच सेकंड बाद पहले डैशबोर्ड में नई पंक्तियां जोड़ता है:

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

अल्पकालिक टोकन सर्व करना

ऊपर आपके द्वारा बनाया गया एक्सेस टोकन लंबे समय तक वैध रहता है और इसे सर्वर-साइड सीक्रेट के रूप में ही रखा जाना चाहिए। अगर आपका खुद का बैकएंड एम्बेड करने वाले पेजों को सर्व करता है - ऐसे पेज के बजाय जिसका खुद का कोई बैकएंड नहीं है - तो आपको उस लंबे समय तक वैध टोकन को पेज में डालने की बिल्कुल भी ज़रूरत नहीं है - आपका बैकएंड हर पेज को सर्व करने से ठीक पहले, सर्वर-टू-सर्वर, इसे एक अल्पकालिक (15 मिनट) रेंडर टोकन के बदले एक्सचेंज कर सकता है, और ब्राउज़र तक केवल रेंडर टोकन ही पहुंचता है। विज़िटर पेज से जो रेंडर टोकन निकालता है, वह केवल कुछ मिनटों के लिए ही उपयोगी होता है, हमेशा के लिए नहीं।

निर्देश:

1) अपने एक्सेस टोकन को रेंडर टोकन के लिए एक्सचेंज करें - अपने बैकएंड से, POST https://www.sprucely.io/api/auth/render_token को अपने एक्सेस टोकन को बियरर क्रेडेंशियल के रूप में भेजते हुए कॉल करें। रिस्पॉन्स में नया टोकन, उससे बाउंड होस्ट, और सेकंड में उसकी लाइफटाइम शामिल होती है:

// 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) रेंडर टोकन को ब्राउज़र तक सर्व करें - sprucely_db को कॉल करते समय या Sprucely.Database को माउंट करते समय इसका उपयोग बिल्कुल एक्सेस टोकन की तरह करें। हर पेज को सर्व करने से पहले एक्सचेंज दोहराएं (या अगर आप रेंडर किए गए पेज को कैश करते हैं तो एक टाइमर पर), ताकि ब्राउज़र को कभी भी 15 मिनट से ज़्यादा समय तक वैध टोकन न मिले।

फ़ंक्शन रेफरेंस

POST /api/auth/render_token - Authorization: Bearer <token> के रूप में भेजे गए एक वैध एक्सेस टोकन को एक रेंडर टोकन के लिए एक्सचेंज करता है। { token, host, expires_in } रिटर्न करता है, जिसमें expires_in हमेशा 900 सेकंड पर तय रहता है। एक रेंडर टोकन को किसी और रेंडर टोकन के लिए एक्सचेंज नहीं किया जा सकता - केवल एक लंबे समय तक वैध एक्सेस टोकन ही इसका अनुरोध कर सकता है।

सुरक्षा सेटिंग्स

अगर आपकी साइट Content Security Policy (CSP) लागू करती है, तो ऊपर दिए गए स्टैंडअलोन JavaScript और React इंटीग्रेशन के लिए डैशबोर्ड लोड होने से पहले कुछ सोर्स की अनुमति देना ज़रूरी है - रनटाइम अपनी स्क्रिप्ट Sprucely.io से लोड करता है, WebAssembly पर आधारित एक इन-ब्राउज़र डेटाबेस खोलता है, और हमारे API के विरुद्ध आपके एक्सेस टोकन को वैलिडेट करता है, और इनमें से हर एक को एक स्पष्ट CSP अनुमति की ज़रूरत होती है। अगर आपकी साइट CSP का उपयोग नहीं करती, तो आप इस सेक्शन को छोड़ सकते हैं।

अपनी मौजूदा पॉलिसी में निम्नलिखित सोर्स जोड़ें - ये मर्ज करने के लिए डायरेक्टिव हैं, आपके पास पहले से मौजूद पूरी पॉलिसी को बदलने के लिए नहीं:

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;

हर डायरेक्टिव किसलिए है:

script-src - https://www.sprucely.io रनटाइम स्क्रिप्ट लोड करता है। इन-ब्राउज़र डेटाबेस, जो WebAssembly पर बना है, उसे कंपाइल और रन करने के लिए 'wasm-unsafe-eval' आवश्यक है।
connect-src - आपके एक्सेस टोकन को वैलिडेट करने और डेटाबेस की WebAssembly और वर्कर फ़ाइलों को लोड करने के लिए https://www.sprucely.io से संपर्क किया जाता है।
worker-src - इन-ब्राउज़र डेटाबेस अपनी क्वेरी एक बैकग्राउंड थ्रेड पर चलाता है, जो एक blob: URL से बनाई जाती है।

इनमें से किसी को भी 'unsafe-inline' की ज़रूरत नहीं है - Sprucely रनटाइम को खुद इसकी कभी ज़रूरत नहीं पड़ती। अगर आप अपने डैशबोर्ड और डेटासेट डेफिनिशन को एक इनलाइन <script> टैग में रखते हैं, जैसा ऊपर स्टैंडअलोन JavaScript उदाहरण में है, या आपका खुद का पेज इनलाइन स्टाइल का उपयोग करता है, तो 'unsafe-inline' को script-src या style-src में जोड़ें, या CSP नॉन्स पर विचार करें।