Native Widgets

Shipnative includes preconfigured native widgets for both iOS and Android platforms, with seamless Supabase integration for real-time data display.

Overview

Widgets allow users to view key information from your app directly on their home screen without opening the app. Shipnative provides:

iOS Widgets - Built with SwiftUI, supporting all widget sizes
Android Widgets - Built with Kotlin, supporting all widget sizes
Supabase Integration - Automatic data fetching with authentication
Easy Styling - Theme-aware widgets that match your app design
Feature Flag - Easily enable/disable widgets via configuration

Quick Start

1. Enable Widgets

Widgets are disabled by default. To enable them, add to your .env file (or run yarn setup and choose Widgets):

EXPO_PUBLIC_ENABLE_WIDGETS=true
APP_GROUP_IDENTIFIER=group.com.yourcompany.yourapp # yarn setup will prompt
APPLE_TEAM_ID=XXXXXXXXXX # Required for iOS widgets

Finding your Apple Team ID: Open Xcode, go to Preferences → Accounts, select your Apple ID, and look for your team. The Team ID is a 10-character alphanumeric string. You can also find it in your Xcode project under Signing & Capabilities after selecting a team.

Or set it in your environment:

export EXPO_PUBLIC_ENABLE_WIDGETS=true
export APPLE_TEAM_ID=XXXXXXXXXX

2. Install Dependencies

The widget package is already included in package.json. If you need to reinstall:

cd apps/app
yarn install

3. Run Prebuild

Widgets require native code, so you need to run prebuild:

yarn prebuild:clean

This will generate the native iOS and Android projects with widget extensions.

4. Build and Run

# iOS
yarn ios

# Android
yarn android

Widgets are located in app/widgets/:

app/widgets/
├── ios/
│   └── ExampleWidget.swift      # iOS SwiftUI widget
├── android/
│   ├── ExampleWidget.kt         # Android Kotlin widget
│   ├── widget_info.xml          # Widget configuration
│   └── example_widget.xml       # Widget layout
├── README.md                     # Widget documentation
└── SECURITY.md                   # Security best practices

Using Widgets in Your App

Use the useWidgetData hook to fetch data for widgets:

import { useWidgetData } from "@/hooks/useWidgetData"

function WidgetSettingsScreen() {
  const { data, loading, error, refetch } = useWidgetData({
    table: "profiles",
    select: "id, first_name, avatar_url",
    filters: { user_id: currentUserId },
    limit: 1,
    requireAuth: true,
    refreshInterval: 15 * 60 * 1000, // 15 minutes
  })

  if (loading) return <Spinner />
  if (error) return <Text>Error: {error.message}</Text>

  return (
    <View>
      <Text>Welcome {data?.first_name}</Text>
      <Button onPress={refetch} title="Refresh" />
    </View>
  )
}

The widget service handles secure data fetching with caching:

import { fetchWidgetData, getWidgetConfig } from "@/services/widgets"

// Fetch data
const { data, error } = await fetchWidgetData({
  table: "posts",
  select: "id, title, created_at",
  filters: { published: true },
  limit: 5,
  orderBy: { column: "created_at", ascending: false },
  requireAuth: false, // Public data
})

// Get widget configuration
const config = getWidgetConfig()
// { supabaseUrl, supabaseKey, isMock }

Supabase Integration

Widgets need access to Supabase session tokens to fetch authenticated data. The app automatically shares tokens via:

iOS: App Groups (UserDefaults)
Android: SharedPreferences

Setting Up App Groups (iOS)

Run yarn setup → enable Widgets → enter your App Group when prompted (saved as APP_GROUP_IDENTIFIER).
In Xcode, select your app target
Go to “Signing & Capabilities”
Add “App Groups” capability
Ensure the group matches APP_GROUP_IDENTIFIER (default: group.<bundleId>). The widget derives the App Group from the bundle ID if no override is set.

Data Fetching in Widgets

Widgets fetch data directly from Supabase using the REST API: iOS (Swift):

// Get shared UserDefaults
let userDefaults = UserDefaults(suiteName: "group.com.yourcompany.yourapp")

// Get Supabase config
let supabaseUrl = userDefaults?.string(forKey: "supabase_url")
let supabaseKey = userDefaults?.string(forKey: "supabase_key")
let sessionToken = userDefaults?.string(forKey: "supabase_session_token")

// Make HTTP request to Supabase
// GET {supabaseUrl}/rest/v1/{table}?select=*
// Headers: apikey, Authorization (if token available)

Android (Kotlin):

// Get shared preferences
val prefs = context.getSharedPreferences("widget_prefs", Context.MODE_PRIVATE)

// Get Supabase config
val supabaseUrl = prefs.getString("supabase_url", null)
val supabaseKey = prefs.getString("supabase_key", null)
val sessionToken = prefs.getString("supabase_session_token", null)

// Make HTTP request to Supabase
// Similar to iOS implementation

Styling Widgets

Widgets use SwiftUI with theme colors:

// Theme colors
private let primaryColor = Color(red: 0.2, green: 0.4, blue: 0.8)
private let backgroundColor = Color(red: 0.95, green: 0.95, blue: 0.97)
private let textColor = Color(red: 0.1, green: 0.1, blue: 0.1)

// Use in views
Text("Title")
    .font(.headline)
    .foregroundColor(textColor)

Widgets use XML layouts with theme colors:

<TextView
    android:text="Title"
    android:textSize="16sp"
    android:textStyle="bold"
    android:textColor="#1a1a1a" />

Update colors in example_widget.xml to match your app theme.

Security Best Practices

1. Row Level Security (RLS)

Enable RLS policies in Supabase for widget-accessible tables:

-- Example: Allow widgets to read public posts
CREATE POLICY "Widgets can read public posts"
ON posts FOR SELECT
USING (published = true);

2. Token Management

Store session tokens securely in App Groups/SharedPreferences
Tokens are automatically refreshed by the main app
Widgets use read-only access to tokens

3. Data Validation

Always validate data before displaying in widgets:

import { validateWidgetData } from "@/services/widgets"

const isValid = validateWidgetData(data, (d) => {
  return d && typeof d.title === "string" && d.title.length > 0
})

4. Rate Limiting

Widget updates are rate-limited to prevent excessive API calls:

Minimum 5 minutes between updates
15-minute cache duration
Maximum 10 cached items

Creating Custom Widgets

Create a new Swift file in app/widgets/ios/
Implement TimelineProvider protocol
Create SwiftUI view for widget content
Register widget in ExampleWidget.swift

Example structure:

struct MyWidgetProvider: TimelineProvider {
    func placeholder(in context: Context) -> MyEntry {
        // Return placeholder data
    }
    
    func getSnapshot(in context: Context, completion: @escaping (MyEntry) -> Void) {
        // Return snapshot data
    }
    
    func getTimeline(in context: Context, completion: @escaping (Timeline<MyEntry>) -> Void) {
        // Fetch data and create timeline
    }
}

Create a new Kotlin file in app/widgets/android/
Extend AppWidgetProvider
Create XML layout in res/layout/
Register widget in widget_info.xml

Example structure:

class MyWidgetProvider : AppWidgetProvider() {
    override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray
    ) {
        // Update widget
    }
}

Troubleshooting

Check feature flag: Ensure EXPO_PUBLIC_ENABLE_WIDGETS=true
Run prebuild: Widgets require native code generation
Check logs: Look for widget-related errors in Xcode/Android Studio

Data Not Loading

Check Supabase config: Verify URL and key are set
Check session token: Ensure user is authenticated
Check RLS policies: Widgets need appropriate permissions
Check network: Widgets need internet access

Build Errors

iOS: Check App Group identifier matches in app and widget
Android: Check package name matches in widget files
Missing files: Ensure all widget files are in correct locations

Examples

Displaying User Profile

// iOS
struct ProfileWidget: View {
    var entry: ProfileEntry
    
    var body: some View {
        VStack {
            Text(entry.userName)
            Text(entry.email)
        }
    }
}

Displaying Recent Posts

// Android
fun updatePostsWidget(context: Context, posts: List<Post>) {
    val views = RemoteViews(context.packageName, R.layout.posts_widget)
    views.setTextViewText(R.id.post_count, "${posts.size} posts")
    // Update widget
}

API Reference

`useWidgetData` Hook

useWidgetData<T>(options: UseWidgetDataOptions<T>): UseWidgetDataReturn<T>

Options:

table: string - Supabase table name
select?: string - Columns to select (default: ”*”)
filters?: Record<string, any> - Filter conditions
limit?: number - Maximum rows (default: 10)
orderBy?: { column: string; ascending?: boolean } - Sort order
requireAuth?: boolean - Require authentication (default: false)
cacheKey?: string - Custom cache key
refreshInterval?: number - Auto-refresh interval in ms
enabled?: boolean - Enable/disable hook (default: true)

Returns:

data: T | null - Fetched data
loading: boolean - Loading state
error: Error | null - Error if any
refetch: () => Promise<void> - Manual refresh
clearCache: () => void - Clear cache
config: WidgetConfig - Widget configuration

fetchWidgetData<T>(options: FetchOptions): Promise<{ data: T | null; error: Error | null }>
getWidgetConfig(): WidgetConfig
clearWidgetCache(key?: string): void
validateWidgetData<T>(data: T | null, validator?: (data: T) => boolean): boolean

Next Steps

Read Security Guide for security considerations
Check Widget Examples for implementation patterns
Review Troubleshooting for common issues

​Native Widgets

​Overview

​Quick Start

​1. Enable Widgets

​2. Install Dependencies

​3. Run Prebuild

​4. Build and Run

​Widget Structure

​Using Widgets in Your App

​Fetching Widget Data

​Widget Service

​Supabase Integration

​Sharing Session Tokens

​Setting Up App Groups (iOS)

​Data Fetching in Widgets

​Styling Widgets

​iOS Widget Styling

​Android Widget Styling

​Security Best Practices

​1. Row Level Security (RLS)

​2. Token Management

​3. Data Validation

​4. Rate Limiting

​Creating Custom Widgets

​iOS Widget

​Android Widget

​Troubleshooting

​Widget Not Showing

​Data Not Loading

​Build Errors

​Examples

​Displaying User Profile

​Displaying Recent Posts

​API Reference

​useWidgetData Hook

​Widget Service

​Next Steps

Native Widgets

Overview

Quick Start

1. Enable Widgets

2. Install Dependencies

3. Run Prebuild

4. Build and Run

Widget Structure

Using Widgets in Your App

Fetching Widget Data

Widget Service

Supabase Integration

Sharing Session Tokens

Setting Up App Groups (iOS)

Data Fetching in Widgets

Styling Widgets

iOS Widget Styling

Android Widget Styling

Security Best Practices

1. Row Level Security (RLS)

2. Token Management

3. Data Validation

4. Rate Limiting

Creating Custom Widgets

iOS Widget

Android Widget

Troubleshooting

Widget Not Showing

Data Not Loading

Build Errors

Examples

Displaying User Profile

Displaying Recent Posts

API Reference

`useWidgetData` Hook

Widget Service

Next Steps