You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

27 KiB

Building the DailyNotification Plugin

Author: Matthew Raymer
Last Updated: 2025-10-21 09:03:53 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.

Table of Contents

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

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:

  1. Compiles TypeScript to JavaScript
  2. Bundles plugin code with Rollup
  3. Builds native Android/iOS code
  4. Handles plugin development project detection
  5. 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/                           # Main Android test app
│   ├── build.gradle               # App build configuration
│   ├── src/main/java/             # MainActivity.java
│   ├── src/main/assets/           # Capacitor assets (HTML/JS)
│   └── build/outputs/apk/         # Built APK files
├── plugin/                        # Plugin library module
│   ├── build.gradle               # Plugin build configuration
│   ├── src/main/java/
│   │   └── com/timesafari/dailynotification/
│   │       ├── DailyNotificationPlugin.java
│   │       ├── DailyNotificationWorker.java
│   │       ├── DailyNotificationScheduler.java
│   │       └── ...
│   └── 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

Note: There's also a separate Vue 3 test app at test-apps/daily-notification-test/android/ with its own Android module.

Important Distinctions

Plugin Module (android/plugin/)

  • Purpose: Contains the actual plugin code
  • No MainActivity - This is a library, not an app
  • No UI Components - Plugins provide functionality to host apps
  • Output: AAR library files

Test App Module (android/app/)

  • Purpose: Test application for the plugin
  • Has MainActivity - Full Capacitor app with BridgeActivity
  • Has UI Components - HTML/JS interface for testing
  • Output: APK files for installation

What You CAN Do in Android Studio

Edit Java/Kotlin code (both plugin and app)
Run unit tests (both modules)
Debug plugin code (plugin module)
Build the plugin AAR (plugin module)
Build test app APK (app module)
Run the test app (app module)
Test notifications (app module)
Test background tasks (app module)
Debug full integration (app module)
Check for compilation errors
Use code completion and refactoring
View build logs and errors

What You CANNOT Do

Run plugin module directly (it's a library)
Test plugin without host app (needs Capacitor runtime)

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'

Test Apps Within Project

Vue 3 Test Application

The project includes a comprehensive Vue 3 test app for interactive plugin testing:

# Navigate to Vue 3 test app
cd test-apps/daily-notification-test

# Install dependencies
npm install

# Build Vue 3 app
npm run build

# Sync with Capacitor
npx cap sync android

# Run on Android device/emulator
npx cap run android

# Run on iOS device/simulator
npx cap run ios

Test App Features:

  • Interactive plugin testing interface
  • Plugin diagnostics and status checking
  • Notification scheduling and management
  • Permission testing and management
  • Comprehensive logging and debugging

Test App Structure:

test-apps/daily-notification-test/
├── src/                    # Vue 3 source code
│   ├── views/              # Test interface views
│   ├── components/         # Reusable UI components
│   └── stores/             # Pinia state management
├── android/                # Android Capacitor app
├── docs/                   # Test app documentation
└── scripts/                # Test app build scripts

Android Test Apps

The project includes two separate Android test applications:

1. Main Android Test App (/android/app)

A Capacitor-based Android test app with full plugin integration:

# Build main Android test app
cd android
./gradlew :app:assembleDebug

# Install on device
adb install app/build/outputs/apk/debug/app-debug.apk

# Run tests
./gradlew :app:test

# Run in Android Studio
# File → Open → /path/to/daily-notification-plugin/android
# Select 'app' module and run

App Structure:

android/app/
├── src/
│   ├── main/
│   │   ├── AndroidManifest.xml      # App manifest with permissions
│   │   ├── assets/                   # Capacitor web assets
│   │   │   ├── capacitor.config.json # Capacitor configuration
│   │   │   ├── capacitor.plugins.json # Plugin registry
│   │   │   └── public/               # Web app files
│   │   │       ├── index.html        # Main test interface
│   │   │       ├── cordova.js        # Cordova compatibility
│   │   │       └── plugins/          # Plugin JS files
│   │   ├── java/
│   │   │   └── com/timesafari/dailynotification/
│   │   │       └── MainActivity.java # Capacitor BridgeActivity
│   │   └── res/                      # Android resources
│   │       ├── drawable/             # App icons and images
│   │       ├── layout/               # Android layouts
│   │       ├── mipmap/               # App launcher icons
│   │       ├── values/               # Strings, styles, colors
│   │       └── xml/                  # Configuration files
│   ├── androidTest/                  # Instrumented tests
│   └── test/                         # Unit tests
├── build.gradle                      # App build configuration
├── capacitor.build.gradle            # Auto-generated Capacitor config
└── proguard-rules.pro               # Code obfuscation rules

Key Files Explained:

MainActivity.java - Entry point extending Capacitor's BridgeActivity:

public class MainActivity extends BridgeActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    }
}

AndroidManifest.xml - App permissions and configuration:

  • Notification permissions
  • Background execution permissions
  • Exact alarm permissions
  • Capacitor plugin declarations

assets/public/index.html - Main test interface:

  • Interactive plugin testing buttons
  • Plugin diagnostics and status checking
  • Notification scheduling interface
  • Permission management UI

capacitor.plugins.json - Plugin registry:

{
  "plugins": {
    "DailyNotification": {
      "class": "com.timesafari.dailynotification.DailyNotificationPlugin"
    }
  }
}

Build Process:

  1. Web Assets: Capacitor copies assets/public/ to APK
  2. Java Compilation: Compiles MainActivity.java and dependencies
  3. Resource Processing: Processes Android resources and assets
  4. APK Generation: Packages everything into installable APK
  5. Plugin Integration: Links with plugin AAR from android/plugin/

Editing Guidelines:

  • HTML/JS: Edit assets/public/index.html for UI changes
  • Java: Edit src/main/java/ for native Android code
  • Resources: Edit src/main/res/ for icons, strings, layouts
  • Configuration: Edit AndroidManifest.xml for permissions
  • Build: Modify build.gradle for dependencies and build settings

Features:

  • Full Capacitor integration
  • Plugin testing interface (HTML/JS)
  • Native Android testing capabilities
  • Complete app lifecycle testing
2. Vue 3 Test App Android Module (/test-apps/daily-notification-test/android)

Android module within the Vue 3 test application:

# Build Vue 3 test app Android module
cd test-apps/daily-notification-test/android
./gradlew assembleDebug

# Install on device
adb install app/build/outputs/apk/debug/app-debug.apk

# Run tests
./gradlew test

Features:

  • Integrated with Vue 3 frontend
  • Plugin diagnostics and management
  • Interactive testing interface
  • Comprehensive logging and debugging

Integration Testing

1. Create External 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

Build Scripts and Automation

Available Build Scripts

The project includes several automated build scripts in the scripts/ directory:

Core Build Scripts

# Main build script (handles TypeScript + native)
./scripts/build-native.sh --platform android
./scripts/build-native.sh --platform ios
./scripts/build-native.sh --verbose

# TimeSafari-specific builds
node scripts/build-timesafari.js

# Comprehensive testing
./scripts/comprehensive-test-v2.sh

# Capacitor build fixes
./scripts/fix-capacitor-build.sh

Setup and Configuration Scripts

# Gradle setup automation
./scripts/setup-gradle.sh

# Native environment setup
node scripts/setup-native.js

# Environment checking
node scripts/check-environment.js

Testing and Validation Scripts

# Chaos testing for reliability
node scripts/chaos-test.js

# API changes detection
node scripts/check-api-changes.js

# Bundle size monitoring
node scripts/check-bundle-size.js

# Daily notification testing
./scripts/daily-notification-test.sh
node scripts/daily-notification-test.py

Release and Deployment Scripts

# Release notes generation
node scripts/update-release-notes.js

# Type checksum generation
node scripts/generate-types-checksum.js

Deployment to External Projects

1. Publishing to npm Registry

# Build the plugin
npm run build

# Run tests
npm test

# Update version
npm version patch  # or minor, major

# Publish to npm
npm publish

# Verify publication
npm view @timesafari/daily-notification-plugin

2. Installing in External Capacitor Projects

# Install from npm
npm install @timesafari/daily-notification-plugin

# Install from local development
npm install /path/to/daily-notification-plugin

# Install from git repository
npm install git+https://github.com/timesafari/daily-notification-plugin.git

3. Integration in Host Applications

# Add to Capacitor project
npx cap add android
npx cap add ios

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

# Build and run
npx cap run android
npx cap run ios

4. Version Management

# Check current version
npm list @timesafari/daily-notification-plugin

# Update to latest version
npm update @timesafari/daily-notification-plugin

# Install specific version
npm install @timesafari/daily-notification-plugin@1.2.3

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 and automation
├── test-apps/               # Test applications
│   └── daily-notification-test/  # Vue 3 test app
├── 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/
├── app/                     # Main Android test app
│   ├── src/main/java/       # MainActivity.java
│   ├── src/main/assets/     # Capacitor assets
│   ├── build.gradle         # App build configuration
│   └── build/outputs/apk/   # Built APK files
├── plugin/                  # Plugin library module
│   ├── src/main/java/       # Plugin source code
│   ├── build.gradle         # Plugin build configuration
│   └── build/outputs/aar/   # Built AAR files
├── build.gradle             # Root 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

Test Apps Structure

test-apps/
└── daily-notification-test/     # Vue 3 test application
    ├── src/                     # Vue 3 source code
    │   ├── views/               # Test interface views
    │   ├── components/          # Reusable UI components
    │   ├── stores/              # Pinia state management
    │   └── router/              # Vue Router configuration
    ├── android/                 # Android Capacitor app
    │   ├── app/                 # Android app module
    │   ├── dailynotification/   # Plugin module
    │   └── build.gradle         # Android build config
    ├── docs/                    # Test app documentation
    ├── scripts/                 # Test app build scripts
    ├── package.json             # Vue 3 dependencies
    └── vite.config.ts           # Vite build configuration

Scripts Structure

scripts/
├── build-native.sh              # Main build script
├── build-timesafari.js          # TimeSafari-specific builds
├── comprehensive-test-v2.sh     # Full test suite
├── fix-capacitor-build.sh       # Capacitor build fixes
├── setup-gradle.sh              # Gradle setup automation
├── setup-native.js              # Native environment setup
├── check-environment.js         # Environment validation
├── chaos-test.js                # Reliability testing
├── check-api-changes.js         # API change detection
├── check-bundle-size.js         # Bundle size monitoring
├── daily-notification-test.sh   # Notification testing
├── daily-notification-test.py   # Python test runner
├── update-release-notes.js     # Release notes generation
└── generate-types-checksum.js   # Type checksum generation

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.