Export Features

Export Features & Live Share Links

Alpha Insights provides powerful export capabilities and live sharing functionality to help you distribute your reports. This guide covers all export methods and configuration options based on the actual implementation.

Available Export Methods

PDF Export: Professional reports generated via headless browser with full chart rendering
CSV Export: Comprehensive data export packaged as ZIP archive
Live Share Links: Secure, real-time shareable URLs with access control

PDF Export

How PDF Export Works

Alpha Insights uses a sophisticated PDF generation system that:

Creates a temporary live share link for your report (expires in 1 hour)
Sends the live link URL to the WPDavies API endpoint
Uses Puppeteer (headless Chrome) to render the report page
Generates a high-quality PDF with all charts and visualizations
Returns the PDF as base64 encoded data
Saves the PDF file to your server
Automatically cleans up the temporary live link

Technical Requirements

Active License Required: PDF export requires a valid Alpha Insights license key
API Endpoint: Uses https://wpdavies.dev/wp-json/wp-davies/v1/alpha-insights/generate/pdf
Timeout: 60 seconds for PDF generation
Storage Location: PDFs are saved in wp-content/uploads/wp-davies/alpha-insights/exports/pdf_files/

How to Export to PDF

Open any report in Alpha Insights
Click the Export button in the report toolbar
Select Export as PDF
Wait for processing (10-60 seconds depending on report complexity)
PDF automatically downloads to your computer

PDF File Naming

PDF files are automatically named using this format:

[sanitized-report-name]-[date-time-stamp].pdf

Example: weekly-performance-report-2024-10-23-14-30-45.pdf

What’s Included in PDF Exports

Report Header: Alpha Insights branding, report name, and date range
All Widgets: Metric cards, charts, tables exactly as shown in the report
Live Data: Current data at the time of PDF generation
Full Styling: Colors, fonts, and formatting preserved

PDF Export Best Practices

Simplify Complex Reports: Very large reports (10+ widgets) may take longer to generate
Check Data First: Verify your filters and date range before exporting
Use Descriptive Names: The PDF filename is based on your report name
License Validation: Ensure your license is active before attempting export

Troubleshooting PDF Export

Error: “You must have a valid license key to use this feature”

Go to Alpha Insights → Settings → License
Verify your license key is entered and activated
Click “Validate License” to refresh activation status

Error: “Report not found”

Save your report configuration before attempting PDF export
Refresh the page and try again

Error: “API request failed” or “PDF generation API returned error”

Check your site’s internet connectivity
Verify your server can make outbound HTTPS requests to wpdavies.dev
Check WordPress debug logs for detailed error messages
Contact support if the issue persists

Warning: “Temporary live link could not be deleted”

PDF was generated successfully, but cleanup failed
Manually delete the temp link from Report Settings if needed
Temporary links auto-expire after 1 hour regardless

CSV Export

How CSV Export Works

The CSV export system is highly sophisticated and handles complex nested data structures:

Fetches all data from the report (orders, products, expenses, etc.)
Intelligently analyzes the data structure for each entity
Generates separate CSV files for different data types
Packages all CSV files into a single ZIP archive
Automatically cleans up temporary files

CSV Export Features

Multiple CSV Files: One CSV per data type (orders, products, expenses, etc.)
Nested Data Support: Handles complex multi-dimensional arrays
Date-Based Data: Special formatting for time-series data
Categorized Data: Separate sections for different categories
UTF-8 Encoding: Full support for international characters with BOM
ZIP Compression: All CSVs packaged in a single download

How to Export to CSV

Open any report in Alpha Insights
Click the Export button
Select Export as CSV
Wait for data processing (varies by data size)
ZIP file downloads automatically
Extract the ZIP to access individual CSV files

CSV File Structure

The export creates multiple CSV files based on your report data:

Orders Data:

orders_data_table_orders.csv
orders_totals.csv
orders_data_by_date.csv

Products Data:

products_data_table_products.csv
products_by_category.csv
products_totals.csv

Expenses Data:

expenses_data_table_expenses.csv
expenses_totals.csv
expenses_categorized_data.csv

CSV Data Type Handling

Data Tables: Standard tabular data with column headers

First row contains formatted column headers
Each subsequent row is a record
Date columns (containing timestamps) automatically formatted as “Y-m-d H:i:s”

Totals: Key-value pairs

Column 1: Metric name (formatted for readability)
Column 2: Value

Data By Date: Time-series data

First column: Dates in YYYY-MM-DD format
Subsequent columns: Metrics for each date
Handles multi-dimensional data (e.g., revenue by traffic source over time)

Categorized Data: Grouped data with category headers

Category name rows separate different groups
Blank rows between categories for readability
Sub-data formatted appropriately (tables or key-value pairs)

CSV File Naming

ZIP archive naming format:

[report-name]_export_[timestamp].zip

Example: sales-overview_export_2024-10-23_14-30-45.zip

Storage & Cleanup

CSV Files Location: wp-content/uploads/wp-davies/alpha-insights/csv/
Temporary Files: wp-content/uploads/wp-davies/alpha-insights/tmp/
Auto-Cleanup: Temporary files deleted after ZIP creation
Old File Cleanup: ZIP files older than 24 hours are automatically removed
Temp File Cleanup: Temporary CSV files older than 1 hour are automatically removed

CSV Export Best Practices

Use Filters: Apply date ranges and filters before export to limit data size
Large Datasets: Stores with 10,000+ orders may create large ZIP files (10MB+)
Excel Compatibility: Files include UTF-8 BOM for proper Excel opening
Data Analysis: Perfect for importing into Excel, Google Sheets, or BI tools

Troubleshooting CSV Export

Error: “No data available to export”

Your current filters returned no results
Adjust date range or remove some filters
Ensure your report has loaded data before exporting

Error: “ZipArchive class not available on this server”

Your PHP installation doesn’t have ZIP support
Contact your hosting provider to enable the PHP ZIP extension

Error: “Failed to create ZIP archive”

Check folder permissions on wp-content/uploads directory
Ensure sufficient disk space is available
Review error logs for detailed permission issues

Issue: Excel shows garbled characters

CSV files use UTF-8 encoding with BOM
In Excel: Data → From Text/CSV → Select UTF-8 encoding
Or open directly in Google Sheets (handles UTF-8 automatically)

Live Share Links

What Are Live Share Links?

Live Share Links are secure, publicly accessible URLs that display your reports in real-time. Anyone with the link can view the report without needing WordPress access, and the data updates automatically to reflect current information.

Live Share Architecture

The system uses a sophisticated URL rewrite structure:

https://yoursite.com/alpha-insights/reports/[report-slug]/?secret_key=[unique-key]

Custom Rewrite Rules: WordPress handles pretty URLs via rewrite tags
Secure Secret Keys: Randomly generated, impossible-to-guess tokens
Public Access: No WordPress login required
Real-Time Data: Reports fetch live data on every page load

How to Create a Live Share Link

Open the report you want to share
Click Share button in the report toolbar
Click Create Share Link
Configure settings:
- Link name (for your reference)
- Expiry date (optional)
- Password protection (optional)
Click Generate Link
Copy the URL and share it

Live Share Link Configuration

Link Name:

Internal label to identify the link
Shown on password entry screen
Displayed in the live share header

Expiry Date:

Optional expiration date/time
Link automatically stops working after expiry
Set to null or far-future date for permanent links
Format: YYYY-MM-DD HH:MM:SS in site timezone

Password Protection:

Optional password requirement
Users must enter password before viewing report
Passwords are hashed using WordPress’s wp_hash_password()
Password prompt displays link name for context

Live Share Link Storage

Links are stored in the report configuration option:

Option: wpd_dashboard_config_[report-slug]
Structure:
{
  "live_share_links": [
    {
      "id": "unique-id",
      "name": "Board Meeting Link",
      "secret_key": "abc123xyz789",
      "created_date": "2024-10-23 14:30:00",
      "expiry_date": "2024-11-23 14:30:00",
      "require_password": true,
      "password": "$2y$10$hashed..."
    }
  ]
}

Live Share Security Features

Secret Key Generation:

Uses PHP’s uniqid() with more_entropy parameter
Cryptographically secure random string
Impossible to guess or brute-force

Password Hashing:

Uses WordPress’s wp_hash_password() function
Bcrypt hashing algorithm
Never stored in plain text

HTTPS Encryption:

All live share pages use HTTPS
Data transmitted securely
No sensitive data exposed in URLs (except secret key)

Expiration Checking:

Server-side validation on every request
Uses DateTime comparison in site timezone
Shows “link has expired” error after expiry

Live Share Page Structure

The live share page is a minimal HTML page with:

Header Section:
- Alpha Insights logo and branding
- Report name and date range
- Link name (for context)
Report Content:
- Full React dashboard rendering
- All widgets and visualizations
- Real-time data fetching via AJAX
Scripts Loaded:
- jQuery (from WordPress core)
- React Dashboard bundle
- Localized data with special live share nonce

Live Share Data Fetching

Live share pages use AJAX mode instead of REST API:

Force AJAX Mode: Set to true in localized data
Live Share Nonce: Special nonce that doesn’t require user authentication
Live Share Auth: Passed as [report-slug]:[secret-key] for validation
AJAX Endpoint: Uses admin-ajax.php with nopriv action hooks

Managing Live Share Links

View Active Links:

Open the report
Click Share button
See all active links with details:
- Link name
- Created date
- Expiry date (if set)
- Password status

Delete a Link:

Find the link in the share dialog
Click Delete icon
Confirm deletion
Link immediately stops working

Regenerate a Link:

Delete the old link
Create a new link with same settings
Old URL will no longer work
New URL will have different secret key

Live Share Use Cases

Board/Investor Access:

Create permanent link with password protection
Share with board members for always-current data
No need to email updated reports monthly

Team Collaboration:

Share with marketing/sales teams
Everyone sees the same real-time data
No WordPress accounts needed for team members

Client Reporting (Agencies):

Give clients 24/7 access to their store performance
Set expiration date at end of engagement
Password protect for client security

Temporary Sharing:

Create 7-day link for specific meeting or review
Link auto-expires after the event
No need to manually revoke access

Live Share Best Practices

Use Descriptive Names: Helps you identify links later
Set Expiration Dates: For temporary access needs
Password Protect: For sensitive financial data
Regular Cleanup: Delete unused links periodically
Monitor Usage: Keep track of who has access to what

Troubleshooting Live Share Links

Error: “Invalid URL parameters”

URL is malformed or incomplete
Ensure full URL including secret_key parameter
Re-copy the URL from the share dialog

Error: “Report not found”

Report may have been deleted
Report configuration is corrupted
Contact site administrator

Error: “Invalid secret key”

Link may have been deleted
Secret key is incorrect or incomplete
Request new link from report owner

Error: “This live share link has expired”

Link expiration date has passed
Contact report owner to create new link
If you own the report, create a new link with later expiry

Error: “Invalid password”

Password entered incorrectly
Passwords are case-sensitive
Contact link creator for correct password

Page shows “Access Denied” icon but no specific message

General error in live share processing
Check WordPress debug logs
Verify rewrite rules are flushed (save Settings → Permalinks)

Export Configuration

Report Configuration Structure

Each report stores its configuration including export settings in WordPress options:

Option Name: wpd_dashboard_config_[slug]

Structure:
{
  "dashboard_id": "report-slug",
  "name": "Report Name",
  "filters": {...},
  "widgets": [...],
  "live_share_links": [...]
}

Filters Configuration

Filters are stored in the report configuration and affect what data is exported:

"filters": {
  "date_preset": "last_30_days",
  "date_from": "2024-09-23",
  "date_to": "2024-10-23",
  "comparison_date_selection": "previous_period",
  "data_filters": {
    "orders": {
      "status": ["wc-completed", "wc-processing"],
      "billing_email": [],
      "product_ids": []
    },
    "products": {
      "category": [],
      "tag": []
    }
  }
}

Export File Locations

All exports are stored in organized directories:

Base Upload Directory:
wp-content/uploads/wp-davies/alpha-insights/

PDF Files:
/exports/pdf_files/

CSV ZIP Files:
/csv/

Temporary CSV Files:
/tmp/ (auto-cleaned after 1 hour)

Export Permissions

Export functionality requires specific WordPress capabilities:

CSV Export: Requires manage_options capability
PDF Export: Requires active license (checked server-side)
Live Share Links: Requires manage_options to create
Viewing Live Shares: No WordPress login required (public access with secret key)

Export API Reference

CSV Export AJAX Action:

Action: wpd_export_all_data_csv
Method: POST
Nonce: wpd_ajax_nonce
Parameters:
  - dashboard_id: Report slug
  - report_name: Optional display name
Response:
  - success: boolean
  - message: string
  - zip_url: download URL
  - filename: ZIP filename

PDF Export AJAX Action:

Action: wpd_export_react_report_to_pdf
Method: POST
Nonce: wpd_ajax_nonce
Parameters:
  - report_slug: Report slug
Response:
  - success: boolean
  - download_link: Public URL
  - file_name: PDF filename
  - file_size: File size in bytes
  - error_messages: Error string if failed

Create Live Share Link AJAX Action:

Action: wpd_create_live_share_link
Method: POST
Nonce: wpd_ajax_nonce
Parameters:
  - dashboard_id: Report slug
  - link_name: Display name
  - expiry_date: YYYY-MM-DD HH:MM:SS (optional)
  - password: Plain text password (optional)
  - require_password: boolean
Response:
  - success: boolean
  - message: string
  - data: {link: {id, secret_key, ...}}

Developer Integration

Developers can programmatically generate exports:

Generate PDF:

$result = wpd_generate_pdf_from_report_slug( 'report-slug' );

if ( $result['success'] ) {
    $pdf_url = $result['download_link'];
    $pdf_path = $result['server_file'];
}

Create CSV Export:

$exporter = new WPD_CSV_Exporter();
$result = $exporter->export_all_data_to_zip(
    $all_data,
    'Report Name'
);

if ( $result['success'] ) {
    $zip_url = $result['zip_url'];
}

Create Live Share Link:

$report = new WPD_React_Report( 'report-slug' );
$result = $report->create_live_share_link(
    'report-slug',
    'Link Name',
    '2024-12-31 23:59:59', // expiry
    'password123',         // password (optional)
    true                   // require_password
);

Technical Considerations

Server Requirements:

PHP 7.4+ with ZipArchive extension for CSV export
Sufficient memory for large data exports (512MB+ recommended)
Outbound HTTPS access for PDF generation API
WordPress rewrite rules enabled for live share URLs

Performance Optimization:

CSV exports process data in chunks to avoid memory limits
PDF generation uses external API to avoid server load
Live share pages cache aggressively on client-side
Auto-cleanup prevents disk space issues

Security Measures:

All AJAX actions verify WordPress nonces
Capability checks ensure proper permissions
Live share secret keys are cryptographically random
Passwords are hashed using WordPress standards
File paths validated to prevent directory traversal