Smart Widgets

Overview

Smart widgets allow your app to display information on the iOS home screen without users opening the app. These widgets can show real-time data, statistics, or any content served as an SVG or PNG image, updating automatically at specified intervals.

Prerequisites

Despia Configuration

1. Open your Despia editor

2. Navigate to Targets

3. Enable Smart Widget

   

4. Configure widget settings:

   • Name: Your widget display name

   • Description: Widget description for users

   • Server Fallback URL: Default widget content URL

   • Refresh Rate: Update frequency (e.g., 1, 5, or 10 minutes)

     

5. Rebuild and republish your application

WeWeb Setup

1. Install the Despia plugin from WeWeb Marketplace

2. Verify installation: Assets → Library → check for "Despia"

Implementation Steps

Step 1: Add Despia Plugin Component

1. Click Add in WeWeb editor

2. Navigate to Assets panel

3. Find Despia native → Despia plugin component

4. Drag to the top of your page

Step 2: Create Widget Update Trigger

Add a trigger for updating the widget URL (typically after user login):

• Button for manual update

• On successful authentication

• After user preferences change

• When user data updates

Step 3: Configure Widget Update Workflow

1. Select your trigger element

2. Go to Workflows → Add workflow

3. Add action: Execute component action

   • Component: Despia plugin

   • Action: "Set widget, no callback"

   • Refresh Time: Minutes between updates (e.g., 60)

   • Endpoint: URL serving your widget content

Widget Content Requirements

Supported Formats

• SVG: Recommended for scalable, dynamic content

• PNG: Static images with fixed dimensions

Dynamic Content Strategy

Your server endpoint should:

• Accept user ID as query parameter

• Fetch relevant user data from database

• Generate personalized SVG/PNG

• Return updated content on each request

Example Use Cases

• Sales dashboards with revenue numbers

• Fitness stats showing daily progress

• Task counters displaying pending items

• Weather data for user's location

• Stock portfolio values

Server Setup Considerations

Endpoint Requirements

• Must be publicly accessible

• Should handle authentication tokens

• Return proper content-type headers

• Optimize for quick response times

Implementation Options

• Cloudflare Workers for edge computing

• Xano endpoints with dynamic SVG generation

• Supabase functions with database queries

• Custom backend API endpoints

Dynamic Widget Updates

Setting User-Specific Widgets

After user authentication, update the widget URL to include user context:

• Base URL + user ID parameter

• Authenticated endpoint with token

• Personalized content based on preferences

Refresh Strategies

• Static Content: Longer refresh intervals (60+ minutes)

• Real-time Data: Shorter intervals (1-5 minutes)

• Battery Consideration: Balance update frequency with battery usage

Publishing & Deployment

• Widget configuration changes use over-the-air updates

• No App Store resubmission required for URL changes

• Instant deployment to all users

• Widget setup requires initial app rebuild

Best Practices

1. Fallback Content

   • Always provide default widget for logged-out state

   • Show placeholder when data unavailable

   • Handle network errors gracefully

2. Performance

   • Keep widget content lightweight

   • Optimize image file sizes

   • Cache when appropriate

   • Minimize server response time

3. User Experience

   • Make widgets visually appealing

   • Display most relevant information

   • Use clear, readable fonts

   • Consider different widget sizes

4. Security

   • Don't expose sensitive data without authentication

   • Use secure HTTPS endpoints

   • Validate user permissions

   • Implement rate limiting

Widget Sizes & Layout

iOS supports multiple widget sizes:

• Small: Limited space, key metrics only

• Medium: More detail, basic charts

• Large: Full dashboard views

Design your SVG content to scale appropriately for each size.

Testing Your Widget

1. Deploy widget configuration in Despia

2. Install app on test device

3. Long-press home screen

4. Add widget from your app

5. Verify initial display

6. Trigger update from WeWeb app

7. Confirm widget refreshes

Troubleshooting

Widget not appearing:

• Verify widget enabled in Despia

• Check app was rebuilt after enabling

• Ensure iOS version supports widgets

Widget not updating:

• Verify endpoint is accessible

• Check refresh rate settings

• Test endpoint returns valid content

• Confirm workflow triggers correctly

Content display issues:

• Validate SVG/PNG format

• Check image dimensions

• Verify content-type headers

• Test with static content first