Native Widgets

Overview

Despia now supports smart widgets - a highly requested feature that allows you to transform your app icon into a dynamic widget displaying charts, text, data, or previews from your backend. These widgets can be built on your own server and deployed using code or no-code solutions, with full user data integration capabilities.

How Smart Widgets Work

Smart widgets are SVG-based widgets that:

• Display dynamic content from your backend

• Update automatically at specified intervals

• Can show user-specific data

• Work with any backend provider

• Support both code and no-code implementations

Widget States

1. Fallback Widget: The default state showing when no user data is configured (e.g., "Click into the app to configure your widget")

2. Custom Widget: User-specific widget showing personalized data from your backend

Setting Up Smart Widgets

Step 1: Enable Widgets in Despia Editor

1. Open the Despia editor

2. Navigate to Targets (conditional SDKs)

3. Enable the widgets option

4. Click "Open Smart Widget Editor"

Step 2: Configure Your Widget

Fill in the following fields:

• Widget Name: e.g., "Email Preview", "My Portfolio"

• Widget Description: e.g., "Made in Despia"

• SVG Server URL: Your hosted fallback widget URL

• Refresh Rate: How often the widget updates (in minutes)

  • 1 minute (for testing)

  • 5 minutes (quick updates)

  • 15 minutes (balanced)

  • 30-60 minutes (cost-effective)

Step 3: Create a Fallback Widget

The fallback widget is an SVG file hosted on your server. You can:

• Use GitHub with JSDelivr for free hosting

• Host on your own backend for full control

Sample Widget Examples

Fallback Widget

Copy<svg xmlns="http://www.w3.org/2000/svg" width="360" height="169" viewBox="0 0 360 169">
  <defs>
    <linearGradient id="bgGradient" x1="0%" y1="0%" x2="0%" y2="100%">
      <stop offset="0%" stop-color="#2c2c2e" stop-opacity="1"/>
      <stop offset="100%" stop-color="#1c1c1e" stop-opacity="1"/>
    </linearGradient>
  </defs>
  
  <rect width="360" height="169" fill="url(#bgGradient)"/>
  
  <g transform="translate(33, 32)">
    <circle cx="18" cy="6" r="3" fill="#ffffff" opacity="0.9"/>
    <path d="M13 6c0-.712.153-1.387.422-2H6c-1.103 0-2 .897-2 2v12c0 1.103.897 2 2 2h12c1.103 0 2-.897 2-2v-7.422A4.962 4.962 0 0 1 18 11a5 5 0 0 1-5-5z" fill="#ffffff" opacity="0.9"/>
  </g>
  
  <text x="65" y="51" font-size="24" font-weight="700" fill="#ffffff">Despia</text>
  
  <text x="30" y="100" font-size="16" font-weight="600" fill="#ffffff">Dynamic Smart Widget (SSR)</text>
  
  <text x="30" y="125" font-size="13" font-weight="400" fill="#8e8e93">Powered by Despia's Hybrid Widget Kit Framework</text>
</svg>

Dynamic Widget Template

Copy<svg xmlns="http://www.w3.org/2000/svg" width="360" height="169" viewBox="0 0 360 169">
  <defs>
    <linearGradient id="bgGradient" x1="0%" y1="0%" x2="0%" y2="100%">
      <stop offset="0%" stop-color="#2c2c2e" stop-opacity="1"/>
      <stop offset="100%" stop-color="#1c1c1e" stop-opacity="1"/>
    </linearGradient>
  </defs>
  
  <rect width="360" height="169" fill="url(#bgGradient)"/>
  
  <text x="28" y="51" font-size="24" font-weight="700" fill="#ffffff">Hey {NAME}</text>
  
  <text x="30" y="100" font-size="16" font-weight="600" fill="#ffffff">Current Score: {SCORE}</text>
  
  <text x="30" y="125" font-size="13" font-weight="400" fill="#8e8e93">Powered by Despia's Hybrid Widget Kit Framework</text>
</svg>

Backend Setup Example

1. Create a GET API endpoint

2. Return the SVG content

3. Set content header: Content-Type: image/svg+xml

Example Backend Implementation

When serving the dynamic widget, replace the placeholders with actual data:

Copy// Example with string replacement
const svgTemplate = `<svg xmlns="http://www.w3.org/2000/svg" width="360" height="169" viewBox="0 0 360 169">
  <defs>
    <linearGradient id="bgGradient" x1="0%" y1="0%" x2="0%" y2="100%">
      <stop offset="0%" stop-color="#2c2c2e" stop-opacity="1"/>
      <stop offset="100%" stop-color="#1c1c1e" stop-opacity="1"/>
    </linearGradient>
  </defs>
  
  <rect width="360" height="169" fill="url(#bgGradient)"/>
  
  <text x="28" y="51" font-size="24" font-weight="700" fill="#ffffff">Hey {NAME}</text>
  
  <text x="30" y="100" font-size="16" font-weight="600" fill="#ffffff">Current Score: {SCORE}</text>
  
  <text x="30" y="125" font-size="13" font-weight="400" fill="#8e8e93">Powered by Despia's Hybrid Widget Kit Framework</text>
</svg>`;

// Replace placeholders with actual data
const dynamicSvg = svgTemplate
  .replace('{NAME}', userData.name)
  .replace('{SCORE}', userData.score);

// Return with proper content type
response.headers['Content-Type'] = 'image/svg+xml';
return dynamicSvg;

Step 4: Publish Your Application

After configuring the widget, publish your Despia application to apply the changes.

Dynamic Widget Implementation

Creating Dynamic Widgets

To show user-specific data:

1. Create a Custom Endpoint

   CopyGET /custom/:id
   

2. Fetch User Data Query your database based on the user ID

3. Generate Dynamic SVG Replace placeholders with actual user data

4. Return with Proper Headers

   CopyContent-Type: image/svg+xml
   

Setting Widget Source Programmatically

Use Despia's deep linking scheme to update the widget source after user authentication:

Copy// Basic syntax
const svg = "https://your-backend.com/api/widget"
const refresh_time = 10  // in minutes
window.despia = `widget://${svg}?refresh=${refresh_time}`

Complete Implementation Example

Copy// Get user ID (from your auth system, variables, etc.)
const userId = "user-id-here"

// Construct dynamic widget URL
const svgWidgetUrl = `https://your-backend.com/api/custom/${userId}`

// Set refresh time (in minutes)
const refreshTime = 10

// Update the widget
window.despia = `widget://${svgWidgetUrl}?refresh=${refreshTime}`

Framework Integration

General Implementation

Regardless of your framework, the integration follows the same pattern:

Copy// Get user ID from your auth system or state management
const userId = "user-id-here"

// Construct dynamic widget URL
const svgWidgetUrl = `https://your-backend.com/api/custom/${userId}`

// Set refresh time (in minutes)
const refreshTime = 10

// Update the widget
window.despia = `widget://${svgWidgetUrl}?refresh=${refreshTime}`

Integration Tips

• Call the widget update code after user authentication

• Can be triggered on app load, component mount, or user action

• Access user ID from your framework's state management or variables

• Works with any JavaScript framework (React, Vue, Angular, etc.)

• Compatible with no-code platforms that support custom JavaScript

Widget Design Process

Important: Despia currently only supports medium-sized widgets at 360x169 pixels. Make sure your SVG widgets are designed with these exact dimensions.

Supported Backend Providers

• Xano

• Supabase

• Cloudflare Workers

• Any backend that can serve SVG content with proper headers

Tools and Resources

• SVG Viewer: svgviewer.dev - Preview and test SVG code

• Template Libraries: Mustache.js for dynamic content

• AI Assistance: Use Claude or similar tools for widget design

Troubleshooting

1. Widget Not Updating

   • Check refresh rate settings

   • Verify backend is returning proper Content-Type header

   • Ensure widget URL is accessible

2. Widget Shows Fallback

   • Confirm window.despia code is executing

   • Check user ID is being passed correctly

   • Verify backend endpoint is working

3. SVG Rendering Issues

   • Validate SVG syntax

   • Check dimensions and viewBox settings

   • Test in SVG viewer before deployment

What's Next

Smart widgets open up possibilities for:

• Real-time charts and graphs

• Portfolio tracking

• Email previews

• Activity summaries

• Custom data visualizations

With Despia V3, the possibilities are limitless for creating engaging, dynamic widgets that keep your users connected to their data.