@percy.ai/roi-embed

v1.0.3

Published

5 months ago

ROI Dashboard component for embedding in PHP applications

Downloads

0High
0Medium
0Low

percy-dev

ROI Dashboard Embed

A JavaScript component that allows you to embed the ROI Dashboard into any web application, including PHP applications.

Features

✅ Easy integration with any web application
✅ Works with PHP, HTML, or any web framework
✅ Complete ROI dashboard functionality
✅ Responsive design with Tailwind CSS
✅ TypeScript support
✅ UMD and ES module builds
✅ Built with Vite for optimal performance

Installation

Option 1: NPM Package (Recommended)

npm install @percy.ai/roi-embed

Option 2: Direct Script Include

Download the built files from the dist/ directory and include them in your project.

Quick Start

HTML Usage

<!DOCTYPE html>
<html>
<head>
    <title>ROI Dashboard</title>
    <!-- Load CSS styles -->
    <link rel="stylesheet" href="./dist/roi-embed.css">
</head>
<body>
    <div id="roi-dashboard"></div>

    <!-- Load React from CDN -->
    <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
    
    <!-- Load ROI Embed -->
    <script src="./dist/roi-embed.umd.js"></script>
    
    <script>
        window.ROIEmbed.init('roi-dashboard', {
            userId: 123,
            clientKey: 'your-client-key',
            defaultRange: {
                from: new Date(2024, 0, 1),
                to: new Date()
            }
        });
    </script>
</body>
</html>

PHP Integration

<?php
$userId = 123; // From your authentication system
$clientKey = 'your-client-key';
?>
<!DOCTYPE html>
<html>
<head>
    <title>ROI Dashboard</title>
    <!-- Load CSS styles -->
    <link rel="stylesheet" href="./dist/roi-embed.css">
</head>
<body>
    <div id="roi-dashboard"></div>
    
    <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
    <script src="./dist/roi-embed.umd.js"></script>
    
    <script>
        window.ROIEmbed.init('roi-dashboard', {
            userId: <?php echo json_encode($userId); ?>,
            clientKey: <?php echo json_encode($clientKey); ?>,
            defaultRange: {
                from: new Date('<?php echo date('Y-01-01'); ?>'),
                to: new Date('<?php echo date('Y-m-d'); ?>')
            }
        });
    </script>
</body>
</html>

JavaScript/TypeScript

import { initROIEmbed } from '@percy.ai/roi-embed';
import '@percy.ai/roi-embed/dist/roi-embed.css'; // Import CSS

// Initialize the dashboard
initROIEmbed('roi-dashboard', {
    userId: 123,
    clientKey: 'your-client-key',
    defaultRange: {
        from: new Date(2024, 0, 1),
        to: new Date()
    }
}).then(root => {
    console.log('ROI Dashboard initialized successfully');
}).catch(error => {
    console.error('Failed to initialize ROI Dashboard:', error);
});

Required Files

When using the embed, you need to include both files:

JavaScript: roi-embed.umd.js (1.72MB) - The component logic
CSS: roi-embed.css (66KB) - Tailwind CSS and component styles

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | userId | number | Yes | The ID of the user to display ROI data for | | clientKey | string | No | Client API key for authentication | | defaultRange | object | No | Default date range for the dashboard | | defaultRange.from | Date | No | Start date for the default range | | defaultRange.to | Date | No | End date for the default range | | apiUrl | string | No | Custom API URL (uses default if not provided) |

Examples

Complete examples are provided in the package:

example.html - Basic HTML integration
example.php - PHP application integration

Build Information

The package includes:

UMD Build (roi-embed.umd.js): For direct browser usage with <script> tags
ES Module Build (roi-embed.es.js): For modern bundlers and ES6 imports
CSS Styles (roi-embed.css): Tailwind CSS and component styles
TypeScript Declarations (*.d.ts): Full TypeScript support

Bundle Sizes

UMD: 1.72MB (482KB gzipped)
ES Module: 2.38MB (558KB gzipped)
CSS: 66KB (12KB gzipped)

Browser Support

Chrome 88+
Firefox 85+
Safari 14+
Edge 88+

Development

To build from source:

# Install dependencies
pnpm install

# Build the package
pnpm build

# Watch for changes during development
pnpm dev

Troubleshooting

Common Issues

Unstyled components
- Make sure you're loading the CSS file: <link rel="stylesheet" href="./dist/roi-embed.css">
- CSS must be loaded before the JavaScript
"ROI Embed library not loaded" error
- Ensure the script is loaded before trying to initialize
- Check that the path to roi-embed.umd.js is correct
React dependencies missing
- Make sure React and ReactDOM are loaded before the ROI embed script
- Use the CDN links provided in the examples
Container not found error
- Ensure the target div element exists before calling init()
- Use DOMContentLoaded event to ensure DOM is ready

Debug Mode

Add this to enable debug logging:

window.ROI_DEBUG = true;

Support

For issues and questions, please check the package documentation or contact support.

License

This package is part of the Percy.ai ecosystem.