@bigdigital/kiosk-content-sdk

Kiosk Content SDK

npm install @bigdigital/kiosk-content-sdk

Content Management Features

• Offline-first content storage
• Dynamic template support
• Real-time content updates
• Type-safe content validation
• Automatic content synchronization
• Rich media support
• Kiosk monitoring and status tracking

Comprehensive Example

Here's a complete example showing content management with template support and kiosk monitoring:

import { useContentWithTemplate, kioskSDK } from '@bigdigital/kiosk-content-sdk';
import { useEffect, useState } from 'react';
import { Badge } from './ui/badge';
import { Wifi, WifiOff } from 'lucide-react';

interface ContentViewProps {
  contentId: string;
}

function ContentView({ contentId }: ContentViewProps) {
  const [kioskStatus, setKioskStatus] = useState<'connected' | 'disconnected'>('disconnected');

  // Content management configuration
  const config = {
    projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
    apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
    offlineSupport: true, // Enable offline support
    cacheStrategy: "local", // Use local storage for caching
    syncInterval: 300000, // Sync every 5 minutes
    cacheMaxAge: 600000 // Cache expires after 10 minutes
  };

  // Initialize content with template
  const { 
    content, 
    template, 
    loading, 
    error, 
    isOnline,
    refresh 
  } = useContentWithTemplate(config, contentId);

  // Initialize kiosk monitoring
  useEffect(() => {
    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
    const wsHost = window.location.host;
    const wsUrl = `${protocol}//${wsHost}/api/ws/kiosk`;

    const connection = kioskSDK.initializeMonitoring({
      url: wsUrl,
      onConnectionUpdate: (isConnected) => {
        setKioskStatus(isConnected ? 'connected' : 'disconnected');
      }
    });

    // Handle connection events
    connection.on('error', (error) => {
      console.error('Kiosk connection error:', error);
    });

    connection.on('disconnected', () => {
      console.log('Kiosk disconnected, attempting to reconnect...');
    });

    // Cleanup on unmount
    return () => {
      connection.disconnect();
    };
  }, []);

  // Loading state
  if (loading) {
    return (
      <div className="flex items-center justify-center p-8">
        <div className="animate-spin h-8 w-8 border-4 border-primary border-t-transparent rounded-full" />
      </div>
    );
  }

  // Error state
  if (error) {
    return (
      <div className="p-4 bg-destructive/15 text-destructive rounded-md">
        <h2 className="font-semibold mb-2">Error</h2>
        <p>{error.message}</p>
        <button 
          onClick={refresh}
          className="mt-4 px-4 py-2 bg-primary text-white rounded-md"
        >
          Retry
        </button>
      </div>
    );
  }

  // Content not found
  if (!content) {
    return (
      <div className="p-4 text-muted-foreground">
        Content not found
      </div>
    );
  }

  return (
    <div className="space-y-6">
      {/* Connection status indicator */}
      <div className="fixed bottom-4 right-4">
        <Badge 
          variant={kioskStatus === 'connected' ? 'default' : 'destructive'}
          className="flex items-center gap-2"
        >
          {kioskStatus === 'connected' ? (
            <>
              <Wifi className="h-3 w-3" />
              <span>Connected</span>
            </>
          ) : (
            <>
              <WifiOff className="h-3 w-3" />
              <span>Offline</span>
            </>
          )}
        </Badge>
      </div>

      {/* Content display */}
      <div className="space-y-4">
        <h1 className="text-2xl font-bold">{content.title}</h1>
        <p className="text-muted-foreground">{content.description}</p>

        {/* Template-specific content */}
        {template && (
          <div className="mt-8">
            <h2 className="text-xl font-semibold mb-4">
              Template: {template.name}
            </h2>
            {template.fields.map(field => (
              <div key={field.id} className="mb-4">
                <h3 className="font-medium">{field.label}</h3>
                {/* Render field based on type */}
                {field.type === 'text' && (
                  <p>{content.data[field.id]}</p>
                )}
                {field.type === 'image' && (
                  <img 
                    src={content.data[field.id]} 
                    alt={field.label}
                    className="rounded-lg max-w-full h-auto" 
                  />
                )}
              </div>
            ))}
          </div>
        )}

        {/* Offline indicator */}
        {!isOnline && (
          <div className="mt-4 p-2 bg-yellow-50 text-yellow-600 rounded-md text-sm">
            Working offline - Changes will sync when connection is restored
          </div>
        )}

        <button
          onClick={refresh}
          className="mt-6 px-4 py-2 bg-primary text-white rounded-md"
        >
          Refresh Content
        </button>
      </div>
    </div>
  );
}

export default ContentView;

Quick Start

Basic Content Management

import { useKioskContent } from '@bigdigital/kiosk-content-sdk';

function ContentDisplay() {
  const { content, isLoading } = useKioskContent({
    projectId: 'your-project-id',
    offlineSupport: true
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {content.map(item => (
        <div key={item.id}>
          <h2>{item.title}</h2>
          <p>{item.description}</p>
        </div>
      ))}
    </div>
  );
}

Managing Templates

import { useTemplate } from '@bigdigital/kiosk-content-sdk';

function TemplateEditor() {
  const { template } = useTemplate('template-id');

  return (
    <div>
      <h1>{template.name}</h1>
      {template.fields.map(field => (
        <div key={field.id}>
          {/* Render appropriate field editor based on type */}
          {field.type === 'text' && <input type="text" />}
          {field.type === 'image' && <ImageUploader />}
        </div>
      ))}
    </div>
  );
}

Content Types

// Content item structure
interface Content {
  id: string;
  title: string;
  description: string;
  data: Record<string, any>;
  template?: string;
  metadata: {
    createdAt: string;
    updatedAt: string;
    version: number;
  };
}

// Template structure
interface Template {
  id: string;
  name: string;
  fields: Field[];
}

// Field definitions
interface Field {
  id: string;
  type: 'text' | 'image' | 'video' | 'rich-text';
  required: boolean;
  label: string;
  settings?: Record<string, any>;
}

Hooks Reference

Content Management

• useKioskContent: Fetch and manage content items
• useProjectContent: Get content for specific project
• useContentWithTemplate: Get content with template data
• useOfflineContent: Access offline-stored content

Template Management

• useTemplate: Manage single template
• useTemplates: List all available templates
• useTemplateContent: Get content for specific template

Synchronization

• useContentSync: Handle content synchronization

Type Safety

The SDK provides TypeScript support out of the box:

import { Content, Template } from '@bigdigital/kiosk-content-sdk';

// Your content is fully typed
const content: Content = {
  id: 'unique-id',
  title: 'My Content',
  description: 'Description',
  data: {
    // Your content data
  }
};

Error Handling

import { useKioskContent } from '@bigdigital/kiosk-content-sdk';

function ContentWithErrorHandling() {
  const { content, error, retry } = useKioskContent({
    onError: (error) => {
      console.error('Content error:', error);
    }
  });

  if (error) {
    return (
      <div>
        <p>Error: {error.message}</p>
        <button onClick={retry}>Retry</button>
      </div>
    );
  }

  return <ContentDisplay content={content} />;
}

Key Features for Content Management

• Automatic offline storage
• Template-based content validation
• Real-time content updates
• Rich media support
• Type-safe content handling
• Automatic content synchronization
• Error recovery and retry mechanisms
• Kiosk status monitoring and management

For more detailed documentation and advanced features, visit our documentation.

Testing

The SDK includes testing utilities for mocking content and connection behavior:

import { MockKioskConnection } from '@bigdigital/kiosk-content-sdk/testing';

const mockConnection = new MockKioskConnection({
  mockResponses: {
    'content-1': { /* mock content */ }
  }
});