@vizcore/sdk

JavaScript SDK for embedding analytics dashboards with full interactivity and native rendering.

Features

• Native Rendering - Render dashboards directly in your app without iframes
• Full Highcharts Support - Interactive charts with animations and tooltips
• AI Insights - AI-powered contextual insights that suggest new charts
• Location Filtering - Filter all dashboard data by location or other parameters
• Theme Support - Light and dark themes with easy customization
• Responsive - Adapts to any screen size
• Fast & Lightweight - Minimal dependencies, optimized bundle
• Real-time Updates - Auto-refresh and live data updates
• Framework Agnostic - Works with React, Vue, Angular, or vanilla JS

Installation

npm install @vizcore/sdk

Or include via CDN:

<link rel="stylesheet" href="https://unpkg.com/@vizcore/[email protected]/dist/vizcore.css" />
<script src="https://unpkg.com/@vizcore/[email protected]/dist/vizcore.min.js"></script>

Quick Start

import VizCore from "@vizcore/sdk";
import "@vizcore/sdk/dist/vizcore.css";

// Initialize the SDK with API key
VizCore.init({
  apiKey: "your-api-key",
});

// Or initialize with auth token (for authenticated users)
VizCore.init({
  authToken: "Bearer your-jwt-token",
});

// Render a dashboard
const dashboard = await VizCore.render("dashboard-id", "#container", {
  locationId: "location-123",
  theme: "dark",
});

Basic Usage

Authentication

The SDK supports both API key and JWT token authentication:

// Using API Key (for public dashboards)
const renderer = new DashboardRenderer({
  apiKey: "your-api-key",
  container: "#dashboard-container",
});

// Using Auth Token (for authenticated users)
const renderer = new DashboardRenderer({
  authToken: "Bearer your-jwt-token",
  container: "#dashboard-container",
});

// Update auth token dynamically (e.g., after token refresh)
renderer.setAuthToken("Bearer new-jwt-token");

Create a Dashboard Renderer

import { DashboardRenderer } from "@vizcore/sdk";

const renderer = new DashboardRenderer({
  apiKey: "your-api-key", // or use authToken
  container: "#dashboard-container",
});

// Render dashboard with options
await renderer.render("dashboard-id", {
  locationId: "location-123",
  theme: "dark",
  refreshInterval: 30, // seconds
});

Location Filtering

Filter all dashboard data by location:

// Initial render with location
await renderer.render("dashboard-id", {
  locationId: "store-001",
});

// Update location dynamically
await renderer.updateLocation("store-002");

Theme Support

// Set theme during initialization
const renderer = new DashboardRenderer({
  container: "#dashboard",
  theme: "dark", // or 'light'
});

// Update theme dynamically
renderer.updateTheme("light");

AI Insights

Enable AI-powered contextual insights that analyze your dashboard and suggest new charts:

const renderer = new DashboardRenderer({
  container: "#dashboard",
  apiKey: "your-api-key",
  enableInsights: true,
  insightsPosition: "bottom", // or 'left', 'right'
  insightsAutoOpen: true,
});

// Programmatic control
renderer.toggleInsights(); // Toggle panel
renderer.showInsights(); // Show panel
renderer.hideInsights(); // Hide panel
await renderer.refreshInsights(); // Refresh insights

Event Handling

// Listen to dashboard events
renderer.on("dashboard:loaded", (data) => {
  console.log("Dashboard loaded:", data);
});

renderer.on("widget:click", (data) => {
  console.log("Widget clicked:", data);
});

renderer.on("data:updated", (data) => {
  console.log("Data refreshed:", data);
});

// Listen to AI Insights events
renderer.on("insights:loaded", (insights) => {
  console.log("AI insights loaded:", insights);
});

renderer.on("insight-widget:added", (widget) => {
  console.log("Insight widget added:", widget);
});

Framework Integration

React

import { useEffect, useRef } from "react";
import VizCore from "@vizcore/sdk";
import "@vizcore/sdk/dist/vizcore.css";

function Dashboard({ dashboardId, locationId }) {
  const containerRef = useRef(null);
  const rendererRef = useRef(null);

  useEffect(() => {
    const renderer = VizCore.create({
      apiKey: process.env.REACT_APP_API_KEY,
      container: containerRef.current,
    });

    renderer.render(dashboardId, { locationId });
    rendererRef.current = renderer;

    return () => renderer.destroy();
  }, [dashboardId]);

  useEffect(() => {
    if (rendererRef.current) {
      rendererRef.current.updateLocation(locationId);
    }
  }, [locationId]);

  return <div ref={containerRef} />;
}

Vue

<template>
  <div ref="dashboardContainer"></div>
</template>

<script>
import VizCore from "@vizcore/sdk";
import "@vizcore/sdk/dist/vizcore.css";

export default {
  props: ["dashboardId", "locationId"],

  mounted() {
    this.renderer = VizCore.create({
      apiKey: process.env.VUE_APP_API_KEY,
      container: this.$refs.dashboardContainer,
    });

    this.renderer.render(this.dashboardId, {
      locationId: this.locationId,
    });
  },

  watch: {
    locationId(newLocation) {
      this.renderer.updateLocation(newLocation);
    },
  },

  beforeUnmount() {
    if (this.renderer) {
      this.renderer.destroy();
    }
  },
};
</script>

API Reference

VizCore.init(options)

Initialize the SDK with global settings.

• apiKey - API key for authentication
• preloadHighcharts - Pre-load Highcharts library (default: false)

VizCore.create(config)

Create a new dashboard renderer instance.

• container - DOM element or selector
• apiKey - API key (overrides global)
• theme - Initial theme ('light' or 'dark')

DashboardRenderer

Methods

• render(dashboardId, options) - Render a dashboard
• updateLocation(locationId) - Update location filter
• updateTheme(theme) - Change theme
• refresh() - Refresh dashboard data
• resize() - Recalculate layout
• destroy() - Clean up and remove dashboard

Events

• dashboard:loaded - Dashboard successfully loaded
• dashboard:error - Error loading dashboard
• widget:loaded - Widget rendered
• widget:error - Widget error
• widget:click - Widget interaction
• data:updated - Data refreshed
• theme:changed - Theme updated

Configuration

Dashboard Options

{
  locationId: 'location-123',    // Filter by location
  theme: 'dark',                 // Theme (light/dark)
  refreshInterval: 30,           // Auto-refresh in seconds
  parameters: {                  // Custom parameters
    startDate: '2024-01-01',
    endDate: '2024-12-31'
  }
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT

Support

For issues and questions, please visit our GitHub repository.