@orchard9ai/create-vite-vike-tauri/templates/notifications/NOTIFICATION_SETUP.md

Create Vite + Vike + Tauri applications with Orchard9 design system

# Notification Setup Guide

Your app is configured with native notification support! 🔔

## Overview

This project includes a complete notification system with:

- Cross-platform native notifications (Windows, macOS, Linux, iOS, Android)
- Permission handling and user-friendly prompts
- Multiple notification channels (Android)
- Interactive notification actions
- TypeScript support with full type safety

## Desktop Usage

Notifications work out of the box on desktop platforms. The first time you send a notification, the system may prompt for permission.

### Quick Start

```typescript
import { useNotifications } from './hooks/useNotifications'

function MyComponent() {
  const { notify, permission } = useNotifications()

  const sendNotification = async () => {
    await notify('Hello!', 'This is a test notification')
  }

  return (
    <button onClick={sendNotification} disabled={permission !== 'granted'}>
      Send Notification
    </button>
  )
}
```

## Mobile Configuration

### iOS Setup

1. Notifications are pre-configured in your Tauri app
2. Users will see a permission prompt on first use
3. To customize the permission prompt text, edit `src-tauri/tauri.conf.json`:
   ```json
   {
     "permissions": {
       "notification": {
         "usage-description": "We'll notify you about important updates"
       }
     }
   }
   ```

### Android Setup

1. For Android 13+, permission is requested at runtime
2. Three notification channels are pre-configured:

   - **default**: General notifications (standard priority)
   - **alerts**: High-priority alerts with vibration
   - **messages**: Message notifications with standard priority

3. To add custom notification icons:

   ```
   src-tauri/gen/android/app/src/main/res/
   ├── mipmap-hdpi/ic_notification.png (72x72)
   ├── mipmap-mdpi/ic_notification.png (48x48)
   ├── mipmap-xhdpi/ic_notification.png (96x96)
   └── mipmap-xxhdpi/ic_notification.png (144x144)
   ```

4. To add custom notification sounds:
   ```
   src-tauri/gen/android/app/src/main/res/raw/
   └── notification_sound.mp3
   ```

## API Reference

### useNotifications Hook

The `useNotifications` hook provides a complete interface for managing notifications:

```typescript
const {
  permission, // Current permission state
  isLoading, // Loading state during initialization
  error, // Any errors that occurred
  requestPermission, // Function to request permission
  notify, // Send basic notification
  notifyWithChannel, // Send notification to specific channel (Android)
} = useNotifications();
```

### Basic Notifications

```typescript
// Simple notification
await notify('Title', 'Body text');

// Notification with options
await notify('Title', 'Body text', {
  icon: '/icon.png',
  tag: 'unique-id',
});
```

### Channel-Based Notifications (Android)

```typescript
// Send to alerts channel (high priority)
await notifyWithChannel('alerts', 'Important!', 'This requires attention');

// Send to messages channel with actions
await notifyWithChannel('messages', 'New Message', 'You have a new message', {
  actionTypeId: 'basic-actions',
  data: { url: '/messages' },
});
```

### Permission Handling

```typescript
// Check permission status
if (permission === 'granted') {
  // Can send notifications
} else if (permission === 'denied') {
  // Show instructions to enable in settings
} else {
  // Request permission
  const granted = await requestPermission();
}
```

## Testing Notifications

Use the `NotificationDemo` component included in your app to test:

1. **Request Permission**: Click to request notification permissions
2. **Send Basic Notification**: Test simple notifications
3. **Send Alert**: Test high-priority notifications (Android channels)
4. **Send Message**: Test message notifications with actions

## Troubleshooting

### Common Issues

**Notifications not showing**

- Check system notification settings for your app
- Verify permission is granted
- Look in the system notification center/tray
- Check browser console for errors

**Permission always denied**

- On desktop: Check system notification preferences
- On mobile: Check app-specific notification settings
- Try clearing app data and requesting permission again

**Android notifications not using channels**

- Verify Android version (channels available API 26+)
- Check that channel creation happens before sending notifications
- Use Android Studio logcat to debug channel issues

**iOS notifications not working**

- Ensure app is signed with valid provisioning profile
- Check iOS notification settings in device Settings > Notifications
- Verify Tauri capabilities are properly configured

### Debug Information

Enable debug logging to troubleshoot issues:

```typescript
// The hook automatically logs errors to console
// Check browser/app console for detailed error messages
```

## Advanced Configuration

### Custom Notification Channels (Android)

```typescript
import { createChannel } from '@tauri-apps/plugin-notification';

await createChannel({
  id: 'custom-channel',
  name: 'Custom Notifications',
  description: 'Custom notification channel',
  importance: 4, // High importance
  vibration: true,
  lights: true,
  lightColor: '#FF0000',
  sound: 'custom_sound', // File in res/raw/
});
```

### Custom Action Types

```typescript
import { registerActionTypes } from '@tauri-apps/plugin-notification';

await registerActionTypes([
  {
    id: 'message-actions',
    actions: [
      {
        id: 'reply',
        title: 'Reply',
        requiresAuthentication: false,
        foreground: true,
      },
      {
        id: 'mark-read',
        title: 'Mark as Read',
        requiresAuthentication: false,
        foreground: false,
      },
    ],
  },
]);
```

### Notification Actions Handling

```typescript
import { onAction } from '@tauri-apps/plugin-notification';

const unsubscribe = await onAction((notification) => {
  console.log('Action received:', notification.actionId);

  switch (notification.actionId) {
    case 'reply':
      // Handle reply action
      break;
    case 'mark-read':
      // Handle mark as read
      break;
  }
});

// Don't forget to unsubscribe when component unmounts
return unsubscribe;
```

## Security Considerations

- Notifications may appear even when the app is not in focus
- Be mindful of sensitive information in notification content
- Consider user privacy when implementing notification actions
- Test notification behavior across different system notification settings

## Performance Tips

- Initialize notifications early in your app lifecycle
- Cache permission status to avoid repeated checks
- Use notification tags to prevent duplicate notifications
- Clean up notification listeners when components unmount

## Platform Differences

| Feature               | Windows | macOS | Linux   | iOS | Android |
| --------------------- | ------- | ----- | ------- | --- | ------- |
| Basic notifications   | ✅      | ✅    | ✅      | ✅  | ✅      |
| Notification channels | ❌      | ❌    | ❌      | ❌  | ✅      |
| Custom sounds         | ✅      | ✅    | ✅      | ✅  | ✅      |
| Notification actions  | ✅      | ✅    | ✅      | ✅  | ✅      |
| Rich notifications    | ✅      | ✅    | Limited | ✅  | ✅      |

## Further Reading

- [Tauri Notification Plugin Documentation](https://v2.tauri.app/plugin/notification/)
- [Web Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API)
- [Android Notification Channels](https://developer.android.com/develop/ui/views/notifications/channels)
- [iOS Notification Guidelines](https://developer.apple.com/design/human-interface-guidelines/notifications)