17 KiB

Raw Blame History

Building the DailyNotification Plugin

Author: Matthew Raymer
Last Updated: 2025-10-12 04:57:00 UTC
Version: 1.0.0

Overview

This document provides comprehensive instructions for building the DailyNotification Capacitor plugin using various methods, including Android Studio, command line, and integration testing.

Quick Start
Prerequisites
Build Methods
Android Studio Setup
Command Line Building
Testing Strategies
Development Workflow
Troubleshooting
Project Structure

Quick Start

For Plugin Development

# Build plugin source code
./scripts/build-native.sh --platform android

# Test in Capacitor app
cd /path/to/test-capacitor-app
npx cap sync android
npx cap run android

For Android Studio

# 1. Open Android Studio
# 2. File → Open → /path/to/daily-notification-plugin/android
# 3. Wait for Gradle sync
# 4. Build → Make Project (Ctrl+F9)

Prerequisites

Required Software

Android Studio (latest stable version)
Java 11+ (for Kotlin compilation)
Android SDK with API level 21+
Node.js 16+ (for TypeScript compilation)
npm or yarn (for dependency management)

Required Tools

Gradle Wrapper (included in project)
Kotlin (configured in build.gradle)
TypeScript (for plugin interface)

System Requirements

RAM: 4GB minimum, 8GB recommended
Storage: 2GB free space
OS: Windows 10+, macOS 10.14+, or Linux

Build Methods

Method 1: Automated Build Script (Recommended)

The project includes an automated build script that handles both TypeScript and native compilation:

# Build all platforms
./scripts/build-native.sh

# Build specific platform
./scripts/build-native.sh --platform android
./scripts/build-native.sh --platform ios

# Build with verbose output
./scripts/build-native.sh --verbose

What it does:

Compiles TypeScript to JavaScript
Bundles plugin code with Rollup
Builds native Android/iOS code
Handles plugin development project detection
Provides helpful warnings and guidance

Method 2: Manual Command Line

TypeScript Compilation

# Clean previous builds
npm run clean

# Build TypeScript and bundle
npm run build

# Watch mode for development
npm run build:watch

Android Native Build

# Navigate to Android directory
cd android

# Build plugin library (recommended for plugin development)
./gradlew :plugin:assembleRelease

# Build test app (requires proper Capacitor integration)
./gradlew :app:assembleRelease

# Build all modules
./gradlew build

# Run tests
./gradlew test

iOS Native Build

# Navigate to iOS directory
cd ios

# Install CocoaPods dependencies
pod install

# Build using Xcode (command line)
xcodebuild -workspace DailyNotificationPlugin.xcworkspace -scheme DailyNotificationPlugin -configuration Release

Method 3: Android Studio

See Android Studio Setup for detailed instructions.

Android Studio Setup

Opening the Project

Important: Open the Correct Directory

# ✅ CORRECT: Open the android/ folder
File → Open → /path/to/daily-notification-plugin/android

# ❌ WRONG: Don't open the root project folder
# This will cause Gradle sync issues

Initial Configuration

1. Gradle Sync

Android Studio will prompt to sync Gradle
Click "Sync Now" or use the sync button in the toolbar
Wait for sync to complete (may take a few minutes)

2. SDK Configuration

File → Project Structure → SDK Location
- Android SDK: /path/to/Android/Sdk
- JDK Location: /path/to/jdk-11

3. Gradle Settings

File → Settings → Build → Gradle
- Use Gradle from: 'gradle-wrapper.properties' file
- Gradle JVM: Project SDK (Java 11)

4. Kotlin Configuration

File → Settings → Languages & Frameworks → Kotlin
- Target JVM version: 1.8
- Language version: 1.5

Building in Android Studio

Build Commands

# Build the project
Build → Make Project (Ctrl+F9)

# Clean and rebuild
Build → Clean Project
Build → Rebuild Project

# Generate signed APK/AAR
Build → Generate Signed Bundle / APK

Build Output

The built plugin AAR will be located at:

android/plugin/build/outputs/aar/plugin-release.aar

Project Structure in Android Studio

When opened correctly, you'll see:

android/
├── app/                           # Test app (may not be fully configured)
│   ├── build.gradle
│   ├── src/main/
│   └── ...
├── plugin/                        # Plugin library module
│   ├── build.gradle
│   ├── src/main/java/
│   │   └── com/timesafari/dailynotification/
│   │       ├── DailyNotificationPlugin.kt
│   │       ├── FetchWorker.kt
│   │       ├── NotifyReceiver.kt
│   │       └── ...
│   └── build/outputs/aar/
│       └── plugin-release.aar    # Built plugin AAR
├── build.gradle                  # Root build file
├── settings.gradle               # Project settings
├── gradle.properties             # Gradle properties
└── gradle/wrapper/               # Gradle wrapper files

Important Limitations

This is NOT a Full Android App

No MainActivity - This is a plugin, not an app
No UI Components - Plugins provide functionality to host apps
No App Manifest - The host app provides the manifest
No Resources - Plugins use host app resources

What You CAN Do in Android Studio

✅ Edit Kotlin/Java code
✅ Run unit tests
✅ Debug plugin code
✅ Build the plugin AAR
✅ Check for compilation errors
✅ Use code completion and refactoring
✅ View build logs and errors

What You CANNOT Do

❌ Run the app directly (no MainActivity)
❌ Test notifications (needs host app context)
❌ Test background tasks (needs Capacitor runtime)
❌ Debug full integration (needs host app)
❌ Test UI components (plugin has no UI)

Command Line Building

TypeScript Build Process

1. Clean Previous Builds

npm run clean
# Removes: dist/, build/, out/

2. Compile TypeScript

npm run build
# Compiles: src/ → dist/
# Bundles: dist/plugin.js, dist/esm/index.js

3. Watch Mode (Development)

npm run build:watch
# Automatically rebuilds on file changes

Android Native Build Process

1. Navigate to Android Directory

cd android

2. Build Commands

# Build all variants
./gradlew build

# Build debug variant
./gradlew assembleDebug

# Build release variant
./gradlew assembleRelease

# Clean build
./gradlew clean build

# Run tests
./gradlew test

3. Build Outputs

# Plugin AAR files
android/build/outputs/aar/
├── android-debug.aar
└── android-release.aar

# Test results
android/build/reports/tests/test/index.html

iOS Native Build Process

1. Navigate to iOS Directory

cd ios

2. Install Dependencies

pod install

3. Build Commands

# Build using Xcode command line
xcodebuild -workspace DailyNotificationPlugin.xcworkspace \
           -scheme DailyNotificationPlugin \
           -configuration Release \
           -destination generic/platform=iOS

# Build for simulator
xcodebuild -workspace DailyNotificationPlugin.xcworkspace \
           -scheme DailyNotificationPlugin \
           -configuration Debug \
           -destination 'platform=iOS Simulator,name=iPhone 14'

Testing Strategies

Unit Testing

Android Unit Tests

# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests "DailyNotificationPluginTest"

# Run tests with coverage
./gradlew test jacocoTestReport

iOS Unit Tests

# Run tests using Xcode
xcodebuild test -workspace DailyNotificationPlugin.xcworkspace \
                -scheme DailyNotificationPlugin \
                -destination 'platform=iOS Simulator,name=iPhone 14'

Integration Testing

1. Create Test Capacitor App

# Create new Capacitor app
npx @capacitor/create-app@latest TestApp
cd TestApp

# Install your plugin
npm install /path/to/daily-notification-plugin

# Add platforms
npx cap add android
npx cap add ios

# Sync with Capacitor
npx cap sync android
npx cap sync ios

2. Test in Android Studio

# Open test app in Android Studio
File → Open → TestApp/android

# Now you can:
# - Run the app
# - Test notifications
# - Debug full integration
# - Test background tasks

3. Test on Device

# Run on Android device
npx cap run android

# Run on iOS device
npx cap run ios

Manual Testing Checklist

Basic Functionality

Plugin loads without errors
DailyNotification.configure() works
Background fetching works
Notifications appear
Settings are persisted

Integration Testing

ActiveDid change handling
Settings synchronization
Request pattern matching
Error handling
Network failure recovery

Edge Cases

Network failures
ActiveDid changes during fetch
App backgrounding/foregrounding
Battery optimization settings
Low storage conditions

Development Workflow

For Plugin Development

1. Edit Plugin Code

# Edit TypeScript interface
vim src/definitions.ts

# Edit Android native code
vim android/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.kt

# Edit iOS native code
vim ios/Plugin/DailyNotificationPlugin.swift

2. Build and Test

# Build plugin
./scripts/build-native.sh --platform android

# Test in Capacitor app
cd /path/to/test-capacitor-app
npx cap sync android
npx cap run android

3. Iterate

# Make changes
# Build again
# Test again
# Repeat until working

For Production Testing

1. Test in TimeSafari PWA

# Install plugin in TimeSafari PWA
npm install @timesafari/daily-notification-plugin

# Sync with Capacitor
npx cap sync android
npx cap sync ios

# Test on real devices
npx cap run android
npx cap run ios

2. Monitor and Debug

# Check logs
adb logcat | grep DailyNotification

# Check plugin metrics
# Use observability dashboards

Troubleshooting

Common Issues

Gradle Sync Failures

# Problem: Gradle sync fails
# Solution: Check Java version
java -version  # Should be 11+

# Solution: Clear Gradle cache
./gradlew clean
rm -rf ~/.gradle/caches/

Build Failures

# Problem: Build fails with "Could not read script"
# Solution: This is a plugin development project
# The build script handles this automatically
./scripts/build-native.sh --platform android

# Problem: Build fails with "Could not resolve project :capacitor-cordova-android-plugins"
# Solution: Build the plugin module instead of the test app
./gradlew :plugin:assembleRelease

# Problem: Build fails with "Cannot locate tasks that match ':android:assembleRelease'"
# Solution: Use correct project name - available projects are:
# - :app (test app, may have Capacitor issues)
# - :plugin (plugin library, recommended)
# - :capacitor-android
# - :capacitor-cordova-android-plugins
./gradlew :plugin:assembleRelease

# Problem: Build fails with "Plugin with id 'kotlin-android' not found"
# Solution: The plugin module doesn't need Kotlin plugin for Java/Kotlin code
# Check the plugin/build.gradle file

Capacitor Integration Warnings

# ⚠️  WARNING: capacitor.build.gradle is auto-generated!
# Any manual fixes will be lost when running:
# - npx cap sync
# - npx cap update  
# - npx cap add android

# ⚠️  NOTE: npx cap sync will fail in plugin development projects!
# This is expected - plugin projects don't have www/ directory
# Error: "Could not find the web assets directory: ./www"
# This is normal for plugin development projects

# To fix after Capacitor operations:
./scripts/fix-capacitor-build.sh

# Or use the build script (applies fix automatically):
./scripts/build-native.sh --platform android

Android Studio Issues

# Problem: Android Studio can't find SDK
# Solution: Configure SDK location
File → Project Structure → SDK Location

# Problem: Kotlin compilation errors
# Solution: Check Kotlin version in build.gradle

Capacitor Integration Issues

# Problem: Plugin not found in Capacitor app
# Solution: Check plugin installation
npm list @timesafari/daily-notification-plugin

# Solution: Re-sync Capacitor
npx cap sync android

Debug Commands

Android Debugging

# View Android logs
adb logcat | grep DailyNotification

# Check plugin installation
adb shell pm list packages | grep timesafari

# Test background tasks
adb shell am start -n com.capacitorjs.app/.MainActivity

iOS Debugging

# View iOS logs
xcrun simctl spawn booted log stream --predicate 'subsystem contains "DailyNotification"'

# Check plugin installation
# Use Xcode Organizer or Device Manager

Performance Issues

Build Performance

# Enable Gradle daemon
echo "org.gradle.daemon=true" >> ~/.gradle/gradle.properties

# Increase memory
echo "org.gradle.jvmargs=-Xmx4g" >> ~/.gradle/gradle.properties

# Enable parallel builds
echo "org.gradle.parallel=true" >> ~/.gradle/gradle.properties

Android Studio Performance

# Increase Android Studio memory
# Help → Edit Custom VM Options
-Xmx4g
-XX:ReservedCodeCacheSize=1g

Project Structure

Root Directory

daily-notification-plugin/
├── android/                 # Android native code
├── ios/                     # iOS native code
├── src/                     # TypeScript plugin interface
├── dist/                    # Built plugin files
├── scripts/                 # Build scripts
├── docs/                    # Documentation
├── examples/                # Usage examples
├── tests/                   # Test files
├── package.json             # Node.js dependencies
├── tsconfig.json            # TypeScript configuration
├── rollup.config.js         # Bundler configuration
└── BUILDING.md              # This file

Android Structure

android/
├── src/main/java/           # Kotlin plugin code
├── build.gradle             # Android build configuration
├── settings.gradle          # Gradle settings
├── gradle.properties        # Gradle properties
└── gradle/wrapper/          # Gradle wrapper files

iOS Structure

ios/
├── Plugin/                  # Swift plugin code
├── DailyNotificationPlugin.xcodeproj/  # Xcode project
├── DailyNotificationPlugin.xcworkspace/ # Xcode workspace
├── Podfile                  # CocoaPods dependencies
└── Tests/                   # iOS unit tests

TypeScript Structure

src/
├── definitions.ts           # TypeScript definitions
├── index.ts                 # Plugin entry point
├── android/                 # Android-specific code
├── ios/                     # iOS-specific code
├── web/                     # Web-specific code (legacy)
└── utils/                   # Utility functions

Best Practices

Code Organization

Keep plugin code modular and testable
Use consistent naming conventions
Document all public APIs
Follow platform-specific coding standards

Build Optimization

Use incremental builds when possible
Cache build artifacts
Parallelize builds where supported
Monitor build times and optimize

Testing Strategy

Write unit tests for all plugin logic
Test on real devices, not just simulators
Test edge cases and error conditions
Monitor performance and memory usage

Documentation

Keep BUILDING.md updated
Document all build requirements
Provide troubleshooting guides
Include examples and best practices

Support

Getting Help

Contributing

Follow the contributing guidelines
Test all changes thoroughly
Update documentation as needed
Submit pull requests with clear descriptions

Remember: This is a Capacitor plugin development project. For full functionality testing, use it in a Capacitor host application, not as a standalone Android/iOS app.

17 KiB Raw Blame History

Building the DailyNotification Plugin

Overview

Table of Contents

Quick Start

For Plugin Development

For Android Studio

Prerequisites

Required Software

Required Tools

System Requirements

Build Methods

Method 1: Automated Build Script (Recommended)

Method 2: Manual Command Line

TypeScript Compilation

Android Native Build

iOS Native Build

Method 3: Android Studio

Android Studio Setup

Opening the Project

Important: Open the Correct Directory

Initial Configuration

1. Gradle Sync

2. SDK Configuration

3. Gradle Settings

4. Kotlin Configuration

Building in Android Studio

Build Commands

Build Output

Project Structure in Android Studio

Important Limitations

This is NOT a Full Android App

What You CAN Do in Android Studio

What You CANNOT Do

Command Line Building

TypeScript Build Process

1. Clean Previous Builds

2. Compile TypeScript

3. Watch Mode (Development)

Android Native Build Process

1. Navigate to Android Directory

2. Build Commands

3. Build Outputs

iOS Native Build Process

1. Navigate to iOS Directory

2. Install Dependencies

3. Build Commands

Testing Strategies

Unit Testing

Android Unit Tests

iOS Unit Tests

Integration Testing

1. Create Test Capacitor App

2. Test in Android Studio

3. Test on Device

Manual Testing Checklist

Basic Functionality

Integration Testing

Edge Cases

Development Workflow

For Plugin Development

1. Edit Plugin Code

2. Build and Test

3. Iterate

For Production Testing

1. Test in TimeSafari PWA

2. Monitor and Debug

Troubleshooting

Common Issues

Gradle Sync Failures

Build Failures

Capacitor Integration Warnings

Android Studio Issues

Capacitor Integration Issues

Debug Commands

Android Debugging

iOS Debugging

Performance Issues

Build Performance

Android Studio Performance

17 KiB

Raw Blame History