App Update Management

Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28

---

Overview

The App Update Management domain provides comprehensive software deployment capabilities for terminal applications across the 400,000+ device fleet. It enables controlled, staged rollouts of Android application updates with rollback capabilities, device targeting, and mandatory update enforcement. The system supports multiple deployment strategies from beta testing to full production releases while maintaining operational stability through gradual rollouts and health monitoring.

Table of Contents

• Purpose
• App Version Entity
• Rollout Strategy
• Device Update Check
• API Endpoints

---

Purpose

Manage Android app versions and control rollout to SmartPOS devices.

---

App Version Entity

The App Version entity represents a specific release of a terminal application with all necessary metadata for distribution and installation.

{
  "id": 1,
  "app_name": "business-app|qr-app|credit-card-app",
  "version_code": 123,
  "version_name": "2.3.0",
  "apk_url": "https://s3.amazonaws.com/mpac-apps/business-app-2.3.0.apk",
  "apk_size": 45678901,
  "apk_checksum": "sha256:abc123...",
  "release_notes": "- Bug fixes\n- Performance improvements",
  "min_os_version": "Android 8.0",
  "is_mandatory": false,
  "rollout_percentage": 10,
  "release_status": "beta|stable|deprecated",
  "created_at": "2026-01-20T00:00:00Z",
  "published_at": "2026-01-22T00:00:00Z"
}

Key Attributes:

• app_name: Target application identifier
• version_code: Numeric version for comparison
• version_name: Human-readable version string
• apk_url: Download location for APK file
• apk_checksum: SHA-256 hash for integrity verification
• is_mandatory: Force installation flag
• rollout_percentage: Gradual deployment control (0-100%)
• release_status: Lifecycle stage indicator

---

Rollout Strategy

The platform supports four distinct rollout strategies to balance rapid deployment with operational safety:

1. Beta Release (rollout_percentage: 0)

└─ Manual enrollment only
└─ Selected test devices
└─ Collect feedback

Use Case: Initial testing with opt-in devices before wider release

2. Canary Release (rollout_percentage: 10)

└─ 10% of devices randomly selected
└─ Monitor crash reports, performance
└─ Can rollback if issues detected

Use Case: Limited production exposure to detect issues early

3. Gradual Rollout (rollout_percentage: 50, 100)

└─ Increase percentage over days
└─ 50% → wait 2 days → 100%
└─ Final: All devices receive update

Use Case: Standard production deployment with progressive rollout

4. Mandatory Update (is_mandatory: true)

└─ Device cannot operate without update
└─ Forced install on next app launch
└─ Used for critical security fixes

Use Case: Critical security patches or breaking API changes

---

Device Update Check

Devices periodically check for available updates using the following flow:

Device startup or periodic check
  └─ GET /app-updates/check
     Query: {app_name, current_version_code, device_id}

  └─ Response: {
       update_available: true,
       version_name: "2.3.0",
       version_code: 123,
       apk_url: "https://...",
       apk_size: 45678901,
       apk_checksum: "sha256:abc123...",
       is_mandatory: false,
       release_notes: "..."
     }

Device downloads APK
  └─ Verify checksum
  └─ Install APK
  └─ POST /app-updates/install-confirm
     {device_id, version_code, install_status: success}

Update Check Logic:

1. Device queries with current version and identity
2. Server determines eligibility based on rollout percentage
3. Server returns update metadata if available
4. Device downloads, verifies checksum, and installs
5. Device confirms successful installation

Security Measures:

• SHA-256 checksum verification prevents corrupted/tampered APKs
• HTTPS-only download URLs
• Device authentication required for update checks
• Installation confirmation for deployment tracking

---

API Endpoints

Portal Management:

• POST /app-updates - Upload new app version
• GET /app-updates - List app versions
• PATCH /app-updates/{id} - Update rollout settings
• POST /app-updates/{id}/publish - Publish version

Device Operations:

• GET /app-updates/check - Check for updates (device)
• POST /app-updates/install-confirm - Confirm installation (device)

Rollout Control:

• Incrementally increase rollout_percentage to control deployment speed
• Set is_mandatory: true for critical security updates
• Change release_status to manage version lifecycle

---

See Also

Related Domains:

• Device Management - Target device inventory and health monitoring
• Merchant Hierarchy - Organizational scoping for targeted deployments

Technical Implementation:

• Security Architecture - APK signing and checksum verification
• Database Architecture - App version data model

API Reference:

• API Endpoints - Complete API specification for app update management

---

Navigation: ← Previous: Settlement | ↑ Back to Domain Catalog | Next: Reporting & Analytics →