trent_larson/daily-notification-plugin
4
0
Fork 0
Code Issues Pull Requests 2 Projects Releases Wiki Activity

docs(ios): enhance iOS test app SETUP.md with Android app information

Browse Source 
Expanded iOS test app setup guide with comprehensive information:

Added Sections:
- Prerequisites (macOS, Xcode, CocoaPods, Node.js, Ruby)
- Quick Start options (copy existing vs generate new)
- Detailed configuration steps (Podfile, Capacitor, Info.plist)
- iOS-specific permissions and background modes
- Build and run instructions (Xcode, command line, scripts)
- Test interface features (matching Android test app)
- iOS-specific considerations (background execution, notifications, storage)
- Comprehensive troubleshooting guide
- Project structure documentation
- Dependencies list
- Android vs iOS comparison table
- Additional resources and support

Configuration Details:
- Podfile with plugin path
- Capacitor config with plugin options
- Info.plist permissions (UIBackgroundModes, BGTaskScheduler, notifications)
- iOS permission equivalents to Android

Troubleshooting:
- Plugin not found solutions
- CocoaPods encoding and installation issues
- Build errors and cleanup procedures
- Runtime issues (notifications, background tasks, plugin methods)

Comparison Table:
- Side-by-side Android vs iOS equivalents
- Build systems, permissions, storage, etc.

Result: Comprehensive setup guide matching Android test app documentation
This commit is contained in:
Matthew Raymer
2025-11-11 18:08:36 -08:00
parent 530691b863
commit 5f55882b02
1 changed files with 340 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

391
test-apps/ios-test-app/SETUP.md
View File

@@ -1,22 +1,50 @@
# iOS Test App Setup Guide
**Author**: Matthew Raymer
**Date**: 2025-11-04
**Date**: 2025-11-12
**Status**: Active
## Overview
This guide explains how to set up the standalone iOS test app for the DailyNotification plugin. The iOS test app mirrors the Android test app (`android-test-app`) functionality.
This guide explains how to set up the standalone iOS test app for the DailyNotification plugin. The iOS test app mirrors the Android test app (`android-test-app`) functionality and provides a comprehensive testing environment for all plugin features.
## Option 1: Use Capacitor CLI (Recommended)
## Prerequisites
### Step 1: Generate iOS App
- macOS with Xcode 15.0 or later
- CocoaPods installed (`gem install cocoapods` or via rbenv)
- Node.js 18+ (for Capacitor CLI)
- iOS 13.0+ deployment target
- Ruby 3.1+ (for CocoaPods)
## Quick Start
### Option 1: Use Existing Structure (Recommended)
If `ios/App` already exists, copy it:
```bash
# From project root
cd test-apps/ios-test-app
cp -r ../../ios/App ./App
cd App
export LANG=en_US.UTF-8
~/.rbenv/shims/pod install # or: pod install if in PATH
```
Then update configuration files (see Configuration section below).
### Option 2: Generate with Capacitor CLI
```bash
cd test-apps/ios-test-app
npx @capacitor/create-app@latest App --template blank
```
### Step 2: Configure Plugin
Then follow the configuration steps below.
## Configuration
### Step 1: Podfile Configuration
Edit `App/Podfile`:
@@ -24,6 +52,8 @@ Edit `App/Podfile`:
platform :ios, '13.0'
use_frameworks!
source 'https://cdn.cocoapods.org/'
def capacitor_pods
pod 'Capacitor', :path => '../../../node_modules/@capacitor/ios'
pod 'CapacitorCordova', :path => '../../../node_modules/@capacitor/ios'
@@ -35,18 +65,17 @@ target 'App' do
end
```
### Step 3: Install Dependencies
### Step 2: Install CocoaPods Dependencies
```bash
cd App
pod install
cd test-apps/ios-test-app/App
export LANG=en_US.UTF-8 # Required for CocoaPods
~/.rbenv/shims/pod install # or: pod install if in PATH
```
### Step 4: Copy Test Interface
**Note**: If `pod` command is not found, use the full path: `~/.rbenv/shims/pod` or ensure CocoaPods is in your PATH.
Copy the test HTML from `test-apps/android-test-app/app/src/main/assets/public/index.html` to `App/App/public/index.html`.
### Step 5: Configure Capacitor
### Step 3: Capacitor Configuration
Edit `App/App/capacitor.config.json`:
@@ -55,51 +84,106 @@ Edit `App/App/capacitor.config.json`:
"appId": "com.timesafari.dailynotification",
"appName": "DailyNotification Test App",
"webDir": "public",
"server": {
"iosScheme": "capacitor"
},
"plugins": {
"DailyNotification": {
"debugMode": true,
"enableNotifications": true
"fetchUrl": "https://api.example.com/daily-content",
"scheduleTime": "09:00",
"enableNotifications": true,
"debugMode": true
}
}
}
```
## Option 2: Copy from ios/App (Quick Start)
### Step 4: Info.plist Configuration
If `ios/App` already exists, you can copy it:
Edit `App/App/Info.plist` to include required permissions and background modes:
```xml
<key>UIBackgroundModes</key>
<array>
<string>background-fetch</string>
<string>background-processing</string>
<string>remote-notification</string>
</array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>com.timesafari.dailynotification.fetch</string>
<string>com.timesafari.dailynotification.notify</string>
</array>
<key>NSUserNotificationsUsageDescription</key>
<string>This app uses notifications to deliver daily updates and reminders.</string>
```
**Key iOS Permissions** (equivalent to Android):
- **Notifications**: `NSUserNotificationsUsageDescription` (like Android's `POST_NOTIFICATIONS`)
- **Background Fetch**: `UIBackgroundModes` with `background-fetch` (like Android's WorkManager)
- **Background Processing**: `UIBackgroundModes` with `background-processing`
- **Exact Alarms**: Always supported on iOS via `UNUserNotificationCenter` (no permission needed)
### Step 5: Copy Test Interface
Copy the test HTML from Android test app:
```bash
# From project root
cp -r ios/App test-apps/ios-test-app/App
cd test-apps/ios-test-app/App
pod install
cp test-apps/android-test-app/app/src/main/assets/public/index.html \
test-apps/ios-test-app/App/App/public/index.html
```
Then update:
- `App/Info.plist` - Bundle ID: `com.timesafari.dailynotification`
- `App/capacitor.config.json` - App ID and name
- `App/public/index.html` - Copy test interface from Android test app
The test interface provides:
- Plugin availability testing
- Configuration management
- Status checking
- Notification scheduling
- Permission management
- Channel/notification settings (iOS: app-level)
- Comprehensive status checks
## Build and Run
### Using Xcode
### Using Xcode (Recommended for Development)
```bash
cd test-apps/ios-test-app/App
open App.xcworkspace
# Then build and run in Xcode
# Then build and run in Xcode (⌘R)
```
**Important**: Always open the `.xcworkspace` file, not the `.xcodeproj` file, when using CocoaPods.
### Using Command Line
```bash
cd test-apps/ios-test-app/App
export LANG=en_US.UTF-8
# List available simulators
xcrun simctl list devices available | grep -i iphone
# Build for simulator
xcodebuild -workspace App.xcworkspace \
-scheme App \
-configuration Debug \
-sdk iphonesimulator \
-destination 'platform=iOS Simulator,name=iPhone 15 Pro' \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
clean build
# Build and run on simulator
xcodebuild -workspace App.xcworkspace \
-scheme App \
-configuration Debug \
-sdk iphonesimulator \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
build \
&& xcrun simctl boot "iPhone 17 Pro" 2>/dev/null || true \
&& xcrun simctl install booted "$(xcodebuild -workspace App.xcworkspace -scheme App -configuration Debug -sdk iphonesimulator -showBuildSettings | grep -m 1 "BUILT_PRODUCTS_DIR" | sed 's/.*= *//')/App.app" \
&& xcrun simctl launch booted com.timesafari.dailynotification
```
### Using Build Script
@@ -111,46 +195,251 @@ cd test-apps/ios-test-app
## Plugin Registration
The plugin is automatically registered via Capacitor when included in `Podfile`. No manual registration needed.
The plugin is automatically registered via Capacitor when included in `Podfile`. No manual registration needed in:
- `AppDelegate.swift` (Android equivalent: `PluginApplication.java`)
- `ViewController.swift` (Android equivalent: `MainActivity.java`)
## Test Interface
Capacitor automatically discovers and registers plugins from CocoaPods.
The test interface (`App/App/public/index.html`) provides buttons for:
## Test Interface Features
- Plugin availability testing
- Configuration
- Status checking
- Notification scheduling
- Permission management
The test interface (`App/App/public/index.html`) provides comprehensive testing for:
### Basic Plugin Tests
- **Test Plugin**: Verify plugin is loaded and accessible
- **Configure Plugin**: Set plugin configuration
- **Check Status**: Get current plugin status
### Notification Tests
- **Test Notification**: Send immediate test notification
- **Schedule Notification**: Schedule daily notification
- **Show Reminder**: Display reminder notification
### Permission Management
- **Check Permissions**: Check notification authorization status
- **Request Permissions**: Request notification permissions
- **Exact Alarm Settings**: Open notification settings (iOS: app-level settings)
### Channel Management (iOS: App-Level)
- **Check Channel Status**: Check if notifications are enabled
- **Open Channel Settings**: Open app notification settings
- **Comprehensive Status**: Get full status including permissions, schedules, and battery
## iOS-Specific Considerations
### Background Execution
iOS handles background execution differently than Android:
- **Background Fetch**: Uses `BGTaskScheduler` (similar to Android's WorkManager)
- **Background Processing**: Limited time budget (typically 30 seconds)
- **Background App Refresh**: User-controlled system setting (cannot be checked programmatically)
### Notification Scheduling
- **UNUserNotificationCenter**: Always supports exact alarms (no permission needed)
- **Daily Repeats**: Use `UNCalendarNotificationTrigger` with `repeats: true`
- **Background Tasks**: Use `BGAppRefreshTask` for prefetch operations
### Permissions
- **Notifications**: Single app-level permission (no channels like Android)
- **Exact Alarms**: Always supported, no permission needed
- **Battery Optimization**: Not applicable (Background App Refresh is system setting)
### Storage
- **UserDefaults**: For schedules and configuration (like Android's SharedPreferences)
- **Core Data**: For content cache and history (like Android's Room database)
## Troubleshooting
### Plugin Not Found
Ensure plugin is built:
```bash
./scripts/build-native.sh --platform ios
```
1. **Ensure plugin is built**:
```bash
cd ../../ios
export LANG=en_US.UTF-8
xcodebuild -workspace DailyNotificationPlugin.xcworkspace \
-scheme DailyNotificationPlugin \
-sdk iphonesimulator \
-destination 'generic/platform=iOS Simulator' \
GENERATE_INFOPLIST_FILE=YES \
clean build
```
2. **Verify Podfile includes plugin**:
```bash
grep DailyNotificationPlugin test-apps/ios-test-app/App/Podfile
```
3. **Check plugin registration**:
```bash
# Plugin should be in Pods project
ls -la test-apps/ios-test-app/App/Pods/Local\ Podspecs/
```
### CocoaPods Issues
```bash
cd test-apps/ios-test-app/App
pod deintegrate
pod install
```
1. **Encoding errors**:
```bash
export LANG=en_US.UTF-8
~/.rbenv/shims/pod install
```
2. **Clean reinstall**:
```bash
cd test-apps/ios-test-app/App
pod deintegrate
rm -rf Pods Podfile.lock
pod install
```
3. **Ruby version issues**:
```bash
# Ensure Ruby 3.1+ is available
ruby --version
# Use rbenv if needed
rbenv install 3.1.0
rbenv local 3.1.0
```
### Build Errors
1. Clean build folder in Xcode (⌘⇧K)
2. Delete derived data: `rm -rf ~/Library/Developer/Xcode/DerivedData`
3. Rebuild
1. **Clean build folder**:
```bash
# In Xcode: Product > Clean Build Folder (⌘⇧K)
# Or command line:
xcodebuild clean -workspace App.xcworkspace -scheme App
```
2. **Delete derived data**:
```bash
rm -rf ~/Library/Developer/Xcode/DerivedData
```
3. **Reset CocoaPods cache**:
```bash
pod cache clean --all
pod install
```
4. **Info.plist errors**:
- Ensure `GENERATE_INFOPLIST_FILE=YES` is set for framework targets
- Verify all required keys are present in `Info.plist`
### Runtime Issues
1. **Notifications not appearing**:
- Check notification permissions in iOS Settings
- Verify Background App Refresh is enabled
- Check console logs for errors
2. **Background tasks not running**:
- Background App Refresh must be enabled in iOS Settings
- Tasks have limited execution time (typically 30 seconds)
- System may delay or skip tasks based on usage patterns
3. **Plugin methods not found**:
- Verify plugin is built and included in Pods
- Check Capacitor bridge is initialized
- Review console logs for registration errors
## Project Structure
```
test-apps/ios-test-app/
├── App/
│ ├── App/
│ │ ├── AppDelegate.swift # App lifecycle (Android: PluginApplication.java)
│ │ ├── ViewController.swift # Main view (Android: MainActivity.java)
│ │ ├── SceneDelegate.swift # Scene lifecycle (iOS 13+)
│ │ ├── Info.plist # Permissions & config (Android: AndroidManifest.xml)
│ │ ├── capacitor.config.json # Capacitor config
│ │ └── public/
│ │ └── index.html # Test interface
│ ├── App.xcworkspace # Workspace (includes Pods)
│ ├── Podfile # CocoaPods dependencies
│ └── Podfile.lock # Locked versions
├── scripts/
│ └── build-and-deploy.sh # Build automation
├── README.md # Overview
└── SETUP.md # This file
```
## Dependencies
The iOS test app requires:
- **Capacitor**: Core framework
- **CapacitorCordova**: Cordova compatibility
- **DailyNotificationPlugin**: The plugin being tested
Additional iOS dependencies (managed by plugin):
- **UserNotifications**: Notification scheduling
- **BackgroundTasks**: Background execution
- **CoreData**: Persistent storage
## Comparison with Android Test App
| Feature | Android | iOS |
|---------|---------|-----|
| **App Entry** | `MainActivity.java` | `ViewController.swift` |
| **Lifecycle** | `PluginApplication.java` | `AppDelegate.swift` |
| **Manifest** | `AndroidManifest.xml` | `Info.plist` |
| **Build System** | Gradle | Xcode + CocoaPods |
| **Dependencies** | `build.gradle` | `Podfile` |
| **Permissions** | Runtime + Manifest | Info.plist + Runtime |
| **Background** | WorkManager | BGTaskScheduler |
| **Notifications** | NotificationManager | UNUserNotificationCenter |
| **Storage** | Room + SharedPreferences | Core Data + UserDefaults |
| **Channels** | Multiple channels | App-level only |
## Next Steps
1. Build plugin: `./scripts/build-native.sh --platform ios`
2. Generate or copy iOS app structure
3. Install CocoaPods dependencies
4. Build and run in Xcode or simulator
5. Test plugin functionality
1. **Build plugin**:
```bash
cd ../../ios
./scripts/build-native.sh --platform ios
```
2. **Set up test app**:
```bash
cd test-apps/ios-test-app
# Follow Quick Start section above
```
3. **Install dependencies**:
```bash
cd App
export LANG=en_US.UTF-8
~/.rbenv/shims/pod install
```
4. **Build and run**:
```bash
open App.xcworkspace
# Build and run in Xcode
```
5. **Test functionality**:
- Use test interface to verify all plugin methods
- Test notification scheduling
- Verify permissions work correctly
- Test background tasks (requires Background App Refresh enabled)
## Additional Resources
- [iOS Plugin Implementation Guide](../../docs/IOS_IMPLEMENTATION_COMPLETE.md)
- [iOS Build Quick Reference](../../docs/IOS_BUILD_QUICK_REFERENCE.md)
- [CocoaPods Installation Guide](../../docs/COCOAPODS_INSTALLATION.md)
- [iOS Setup Requirements](../../docs/IOS_SETUP_REQUIREMENTS.md)
- [Android Test App](../../android-test-app/) - For comparison
## Support
For issues or questions:
1. Check troubleshooting section above
2. Review iOS plugin documentation
3. Compare with Android test app implementation
4. Check Xcode console logs for detailed errors