@justrandomnickname/capacitor-app-version-manager

A Capacitor plugin for checking app versions and showing smart update notifications with intelligent scheduling.

Features

✅ Version Management - Get current and App Store versions
✅ Semantic Versioning - Proper version comparison (1.2.3 < 1.2.4)
✅ Native Alerts - Beautiful native update dialogs
✅ Smart Scheduling - Show notifications at controlled intervals (daily, weekly, monthly)
✅ Customizable UI - Custom messages, titles, and button texts with placeholders
✅ Auto Country Detection - Automatic region detection or manual override

Platform Support

| Platform | Status | |----------|--------| | iOS | ✅ Full support | | Android | ⏳ Coming soon | | Web | ❌ Not supported |

Install

npm install @justrandomnickname/capacitor-app-version-manager
npx cap sync

Usage Examples

Basic Usage

import { AppVersionManager } from '@justrandomnickname/capacitor-app-version-manager';

// Simple check and notify
const { notified } = await AppVersionManager.notifyNewRelease();
if (notified) {
  console.log('User was notified about the update');
}

Check for Updates (No UI)

// Check if update is available without showing any UI
const { updateAvailable, app } = await AppVersionManager.checkForUpdate();

if (updateAvailable) {
  console.log(`New version ${app.release.version} is available!`);
  console.log(`Current version: ${app.current.version}`);
  
  // Show your custom UI or handle the update
}

Get Version Information

// Get detailed version info
const { app } = await AppVersionManager.getCurrentVersion();

console.log('Current version:', app.current.version);        // "1.2.3"
console.log('Current build:', app.current.buildNumber);      // "42"
console.log('Latest version:', app.release.version);         // "1.3.0"
console.log('Bundle ID:', app.bundleIdentifier);             // "com.example.app"

Custom Messages with Placeholders

// Use #current and #release placeholders
await AppVersionManager.notifyNewRelease({
  options: {
    title: "Update Available",
    message: "Version #release is now available! You're using #current.",
    buttonUpdateText: "Download Now",
    buttonCloseText: "Maybe Later"
  }
});

// Result: "Version 2.0.0 is now available! You're using 1.5.0."

Smart Scheduling

// Show notification at most once per week
await AppVersionManager.notifyNewRelease({
  options: {
    frequency: "weekly",
    message: "A new version (#release) is available!"
  }
});

// When user closes or clicks update → timer resets
// Won't show again for 7 days

Check Scheduler Status

// Get detailed information when notification is skipped
const result = await AppVersionManager.notifyNewRelease({
  options: { frequency: "monthly" }
});

if (result.skippedByScheduler) {
  console.log('Notification skipped by scheduler');
  console.log('Last shown:', result.schedulerDebugInfo?.lastNotificationDate);
  console.log('Days since:', result.schedulerDebugInfo?.daysSinceNotification);
}

Force Notification

// Show notification regardless of version comparison
await AppVersionManager.notifyNewRelease({
  options: {
    forceNotify: true, // Show even if versions are equal
    frequency: "daily",
    message: "Check out the new features!"
  }
});

Custom App Store Link

// Use a custom App Store URL
await AppVersionManager.notifyNewRelease({
  options: {
    appStoreLink: "https://apps.apple.com/us/app/myapp/id123456789",
    message: "Update available!"
  }
});

Specify Country and Bundle ID

// Useful for testing or multi-app scenarios
await AppVersionManager.notifyNewRelease({
  iosBundleId: "com.example.myapp",
  country: "us",
  options: {
    forceCountry: true, // Use specified country instead of auto-detect
    frequency: "weekly"
  }
});

Complete Example

import { AppVersionManager } from '@justrandomnickname/capacitor-app-version-manager';

async function checkAppUpdate() {
  try {
    const result = await AppVersionManager.notifyNewRelease({
      country: "us",
      options: {
        frequency: "weekly",
        title: "Update Available",
        message: "Version #release is available! You have #current installed.",
        buttonUpdateText: "Update",
        buttonCloseText: "Later",
        forceCountry: false
      }
    });
  } catch (error) {
    console.error('Error checking for updates:', error);
  }
}

And actually you can you plugin something like this..

import { AppVersionManager } from '@justrandomnickname/capacitor-app-version-manager';

async function notifyAboutCoffee() {
  try {
    const result = await AppVersionManager.notifyNewRelease({
      country: "us",
      options: {
        frequency: "weekly",
        title: "Wanna try delicious coffee?",
        message: "Go and buy it! Near you!",
        buttonUpdateText: "Buy coffee!",
        buttonCloseText: "No thanks...",
        appStoreLink: "https://coffeenearyou.coffeecompany.com"
        forceCountry: false
      }
    });
  } catch (error) {
    console.error('Error checking for updates:', error);
  }
}

How It Works

Notification Scheduling

• Stores last notification/dismiss date in UserDefaults
• Checks if enough time has passed before showing again
• Timer resets when user interacts with the alert (close or update)
• Frequency options: always, daily, weekly, monthly

App Store Integration

• Automatically retrieves trackId from iTunes API
• Generates App Store URL: itms-apps://itunes.apple.com/{country}/app/id{trackId}
• Fallback to HTTPS URL for simulators
• Supports custom App Store links

API

• getCurrentVersion(...)
• checkForUpdate(...)
• notifyNewRelease(...)
• Interfaces
• Type Aliases

getCurrentVersion(...)

getCurrentVersion(options?: GetCurrentVersionProps | undefined) => any

Get the current app version information.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | --------------------------- | | options | GetCurrentVersionProps | Get current version options |

Returns: any

Since: 1.0.0

checkForUpdate(...)

checkForUpdate(options?: GetCurrentVersionProps | undefined) => any

Check for updates without showing any alert.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------- | --------------------------- | | options | GetCurrentVersionProps | Get current version options |

Returns: any

Since: 1.0.0

notifyNewRelease(...)

notifyNewRelease(options?: NotifyNewReleaseProps | undefined) => any

Check for updates and show a native alert if a new version is available. Supports scheduling to avoid showing notifications too frequently.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | -------------------------- | | options | NotifyNewReleaseProps | Notify new release options |

Returns: any

Since: 1.0.0

Interfaces

GetCurrentVersionProps

| Prop | Type | Description | Since | | ----------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------- | ----- | | iosBundleId | string | iOS Bundle Identifier of the app. | 1.0.0 | | country | string | Country code for App Store link (e.g., "us", "gb", "de"). | 1.0.0 | | options | GetCurrentVersionOptions | Options for getting the current version. | 1.0.0 |

GetCurrentVersionOptions

Options for getting the current app version.

| Prop | Type | Description | Since | | ------------------ | -------------------- | --------------------------------------------------------- | ----- | | country | string | Country code for App Store link (e.g., "us", "gb", "de"). | 1.0.0 | | forceCountry | boolean | Force the use of the specified country code. | 1.0.0 |

AppInfo

Information about the app versions.

| Prop | Type | Description | Since | | ---------------------- | ------------------------------------------- | --------------------------------------------------- | ----- | | current | Version | Current installed version of the app. | 1.0.0 | | release | Version | Latest released version available in the App Store. | 1.0.0 | | bundleIdentifier | string | iOS Bundle Identifier of the app. | 1.0.0 |

Version

Version information of the app.

| Prop | Type | Description | | ------------------- | ------------------- | ------------------------------------------------------ | | buildNumber | string | Build number (e.g., "100"). | | version | string | Version number (e.g., "1.0.0"). | | versionString | string | Full version string (e.g., "1.0.0 (100)"). |

NotifyNewReleaseProps

| Prop | Type | Description | Since | | ----------------- | --------------------------------------------------------------------------- | --------------------------------------------------------- | ----- | | iosBundleId | string | iOS Bundle Identifier of the app. | 1.0.0 | | country | string | Country code for App Store link (e.g., "us", "gb", "de"). | 1.0.0 | | options | NotifyNewReleaseOptions | Options for notifying about a new release. | 1.0.0 |

NotifyNewReleaseOptions

| Prop | Type | Description | Since | | ---------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | message | string | Message of the update alert. | 1.0.0 | | title | string | Title of the update alert. | 1.0.0 | | frequency | Frequency | Frequency of showing update notifications. | 1.0.0 | | buttonCloseText | string | Text for the button that closes the alert. | 1.0.0 | | buttonUpdateText | string | Text for the button that updates the app. | 1.0.0 | | forceNotify | boolean | | | | appStoreLink | string | Link to the app store page for the app. | 1.0.0 | | critical | SemVer | Indicates if the update is critical and should be forced to install. For example if set to 'major', UI will be blocked if: - The current version is less than the latest major version | 1.0.3 |

SchedulerDebugInfo

Debug information about the scheduler used for notifications.

| Prop | Type | Description | Since | | --------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | ----- | | frequency | Frequency | The frequency setting used for scheduling notifications. | 1.0.0 | | shouldShow | boolean | Indicates whether a notification should be shown based on the scheduling rules. | 1.0.0 | | lastNotificationDate | string | The date when the last notification was shown, if available. | 1.0.0 | | lastDismissDate | string | The date when the last notification was dismissed, if available. | 1.0.0 | | daysSinceNotification | number | The number of days since the last notification was shown. | 1.0.0 | | daysSinceDismiss | number | The number of days since the last notification was dismissed. | 1.0.0 |

Type Aliases

Frequency

Frequency options for update notifications. Available options: "always", "daily", "weekly", "monthly".

"always" | "daily" | "weekly" | "monthly"

SemVer

'major' | 'minor' | 'patch'