@lumel/ap-viz-sdk

SDK for building custom data apps in Analytics Plus.

Installation

npm install @lumel/ap-viz-sdk

Getting Started with ApViz CLI

The fastest way to create a new Analytics Plus app is using the ApViz CLI:

# Install ApViz CLI globally
npm install -g @lumel/ap-viz-cli

# Create a new React TypeScript app
apviz create my-analytics-app --template react-ts
cd my-analytics-app
npm start

Quick Start

import { ApVizSdk, IApVizSdkProps, EApUpdateType } from '@lumel/ap-viz-sdk';

// Configure your app
const config: IApVizSdkProps = {
    configurations: {
        pivot: {
            // Your pivot configuration
        },
    },
    update: (props) => {
        // Handle data updates
        switch (props.type) {
            case EApUpdateType.DATA:
                // Update your app with new data
                renderApp(props.data, props.element);
                break;
            case EApUpdateType.APP_RESIZE:
                // Handle resize events
                resizeApp(props.viewport);
                break;
        }
    },
};

// Register your application
const appHost = ApVizSdk.register(config);

React TypeScript Example

Here's a complete example using React and TypeScript:

import React, { useEffect, useState } from 'react';
import { createRoot } from 'react-dom/client';
import { ApVizSdk, IApVizSdkProps, EApUpdateType, IApUpdateProps } from '@lumel/ap-viz-sdk';

interface AppProps {
    data?: any;
    viewport?: { width: number; height: number };
}

const MyAnalyticsApp: React.FC<AppProps> = ({ data, viewport }) => {
    const [chartData, setChartData] = useState(null);

    useEffect(() => {
        if (data) {
            // Process your data here
            setChartData(data);
        }
    }, [data]);

    return (
        <div style={{ width: viewport?.width, height: viewport?.height }}>
            <h2>My Analytics App</h2>
            {chartData && (
                <div>
                    {/* Your visualization components */}
                    <p>Data loaded: {JSON.stringify(chartData)}</p>
                </div>
            )}
        </div>
    );
};

// App configuration
const config: IApVizSdkProps = {
    configurations: {
        pivot: {
            // Your pivot configuration
        },
    },
    update: (props: IApUpdateProps) => {
        const container = props.element;
        const root = createRoot(container);

        root.render(<MyAnalyticsApp data={props.data} viewport={props.viewport} />);
    },
};

// Initialize the app
const appHost = ApVizSdk.register(config);

// Use SDK features
appHost.selectionManager.select([{ queryName: 'Category', selectionId: 'value1' }]);
appHost.persistProperties({ theme: 'dark', showLabels: true });

Core Features

Data Selection Management

// Select data points
appHost.selectionManager.select([{ queryName: 'Category', selectionId: 'electronics' }]);

// Clear selections
appHost.selectionManager.clear();

Drill-down Operations

import { DrillType } from '@lumel/ap-viz-sdk';

// Drill down to next level
appHost.drillManager.drill([{ queryName: 'Category', drillType: DrillType.DOWN }]);

// Drill up to previous level
appHost.drillManager.drill([{ queryName: 'Category', drillType: DrillType.UP }]);

State Persistence

// Persist custom properties
appHost.persistProperties({
    customSettings: { theme: 'dark', showLabels: true },
    filters: { category: 'electronics' },
});

API Reference

ApVizSdk

Main SDK class providing the entry point for application registration.

Methods

• ApVizSdk.register(config: IApVizSdkProps): AppHost - Registers a new visualization application

AppHost

Manages application lifecycle and communication with the parent Power BI environment.

Properties

• selectionManager: SelectionManagerService - Handles data point selections
• drillManager: DrillManagerService - Manages drill-down operations

Methods

• persistProperties(properties: TPersistProperties): void - Persists custom properties

Configuration Types

IApVizSdkProps

interface IApVizSdkProps {
    configurations: {
        pivot: IPivotConfiguration;
    };
    update: (props: IApUpdateProps) => void;
}

IApUpdateProps

interface IApUpdateProps {
    type: EApUpdateType;
    element: HTMLElement;
    viewport: IDimension;
    data: DataView;
    state: TPersistProperties;
}

Update Types

• EApUpdateType.DATA - Triggered when data changes
• EApUpdateType.APP_RESIZE - Triggered when visualization container is resized

TypeScript Support

This package includes full TypeScript definitions. Import types as needed:

import { IApVizSdkProps, IApUpdateProps, EApUpdateType, DrillType, ISelectionId } from '@lumel/ap-viz-sdk';

License

ISC

Examples and Templates

Get started quickly with our templates:

• React TypeScript: apviz create my-app --template react-ts
• Vanilla TypeScript: apviz create my-app --template vanilla-ts
• React JavaScript: apviz create my-app --template react-js

ApViz CLI Commands

# Create new app
apviz create <app-name> --template <template-name>

# Build for production
apviz build

Support

For issues and questions, please refer to the package repository or contact Lumel support.