@simplysm/capacitor-plugin-auto-update 13.0.85 → 13.0.86

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +93 -140
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,187 +1,140 @@
1
1
  # @simplysm/capacitor-plugin-auto-update
2
2
 
3
- Capacitor plugin for automatic APK updates on Android. Provides APK installation with permission management and two update strategies: server-based (via `ServiceClient`) and external-storage-based.
3
+ Capacitor 앱 자동 업데이트 플러그인. 서버에서 최신 APK를 확인하고 다운로드/설치하거나, 외부 스토리지의 APK 파일로 업데이트한다.
4
4
 
5
- ## Installation
5
+ ## 설치
6
6
 
7
7
  ```bash
8
8
  npm install @simplysm/capacitor-plugin-auto-update
9
9
  ```
10
10
 
11
- ### Android Configuration
11
+ **의존성:** `@simplysm/service-client`, `@simplysm/service-common`, `@simplysm/capacitor-plugin-file-system`, `@simplysm/core-common`, `@simplysm/core-browser`, `semver`
12
+ **Peer:** `@capacitor/core` ^7.4.4
12
13
 
13
- Add the `REQUEST_INSTALL_PACKAGES` permission to your `AndroidManifest.xml`:
14
+ ## Export 목록
14
15
 
15
- ```xml
16
- <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
16
+ ```typescript
17
+ // index.ts
18
+ export { ApkInstaller } from "./ApkInstaller";
19
+ export { AutoUpdate } from "./AutoUpdate";
20
+ export type { ApkInstallerPlugin, VersionInfo } from "./ApkInstallerPlugin";
17
21
  ```
18
22
 
19
- Register the plugin in your `MainActivity.java`:
23
+ ## 주요 사용법
20
24
 
21
- ```java
22
- import kr.co.simplysm.capacitor.apkinstaller.ApkInstallerPlugin;
25
+ ### 서버 기반 자동 업데이트
23
26
 
24
- public class MainActivity extends BridgeActivity {
25
- @Override
26
- protected void init(Bundle savedInstanceState) {
27
- super.init(savedInstanceState);
28
- registerPlugin(ApkInstallerPlugin.class);
29
- }
30
- }
31
- ```
32
-
33
- ## API
34
-
35
- ### `ApkInstaller`
36
-
37
- Abstract utility class for low-level APK installation and permission management.
38
-
39
- - **Android**: Executes APK install intent, manages `REQUEST_INSTALL_PACKAGES` permission.
40
- - **Browser**: Shows an alert message and resolves normally (web fallback).
41
-
42
- #### `ApkInstaller.checkPermissions()`
43
-
44
- Check whether install permission is granted and declared in the manifest.
45
-
46
- ```ts
47
- const result = await ApkInstaller.checkPermissions();
48
- // result.granted — true if the app can install packages
49
- // result.manifest — true if REQUEST_INSTALL_PACKAGES is declared in AndroidManifest.xml
50
- ```
51
-
52
- **Returns:** `Promise<{ granted: boolean; manifest: boolean }>`
53
-
54
- #### `ApkInstaller.requestPermissions()`
55
-
56
- Navigate the user to the system settings page to grant the `REQUEST_INSTALL_PACKAGES` permission (Android 8.0+).
27
+ 서버의 `AutoUpdateService`를 통해 최신 버전을 확인하고 APK를 다운로드/설치한다.
57
28
 
58
- ```ts
59
- await ApkInstaller.requestPermissions();
60
- ```
61
-
62
- **Returns:** `Promise<void>`
63
-
64
- #### `ApkInstaller.install(apkUri)`
65
-
66
- Install an APK file from the given `content://` URI (FileProvider URI).
29
+ ```typescript
30
+ import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
31
+ import type { ServiceClient } from "@simplysm/service-client";
67
32
 
68
- ```ts
69
- await ApkInstaller.install("content://com.example.provider/files/latest.apk");
33
+ await AutoUpdate.run({
34
+ serviceClient, // ServiceClient 인스턴스
35
+ log: (messageHtml) => {
36
+ // 진행 상태를 HTML로 표시 (에러, 다운로드 진행률 등)
37
+ },
38
+ });
70
39
  ```
71
40
 
72
- | Parameter | Type | Description |
73
- |-----------|------|-------------|
74
- | `apkUri` | `string` | A `content://` URI pointing to the APK file |
75
-
76
- **Returns:** `Promise<void>`
77
-
78
- #### `ApkInstaller.getVersionInfo()`
79
-
80
- Get the current app version information.
81
-
82
- ```ts
83
- const info = await ApkInstaller.getVersionInfo();
84
- // info.versionName — e.g. "1.2.3"
85
- // info.versionCode — e.g. "10"
41
+ 동작 흐름:
42
+ 1. 서버에서 최신 버전 조회 (`AutoUpdateService.getLastVersion("android")`)
43
+ 2. `REQUEST_INSTALL_PACKAGES` 권한 확인/요청 (매니페스트 미선언 시 재설치 유도)
44
+ 3. 현재 앱 버전과 semver 비교 (최신이면 조기 반환)
45
+ 4. APK 다운로드 (`fetchUrlBytes`, 진행률 콜백)
46
+ 5. `appCache` 경로에 `latest.apk`로 저장
47
+ 6. APK 설치 인텐트 실행 후 앱 정지 (`await new Promise(() => {})`)
48
+
49
+ 서버 서비스 인터페이스 (`@simplysm/service-common`):
50
+ ```typescript
51
+ interface AutoUpdateService {
52
+ getLastVersion(platform: string): Promise<{ version: string; downloadPath: string } | undefined>;
53
+ }
86
54
  ```
87
55
 
88
- **Returns:** `Promise<VersionInfo>`
89
-
90
- ---
91
-
92
- ### `AutoUpdate`
56
+ ### 외부 스토리지 기반 업데이트
93
57
 
94
- Abstract utility class that orchestrates the full update flow: version check, download, permission handling, and APK installation. Provides two update strategies.
58
+ USB 또는 SD카드 등 외부 스토리지의 APK 파일로 업데이트한다. 파일명이 semver 형식이어야 한다 (예: `1.2.3.apk`).
95
59
 
96
- #### `AutoUpdate.run(opt)`
97
-
98
- Server-based update strategy. Connects to the server via `ServiceClient`, compares versions using semver, downloads the APK, and triggers installation.
99
-
100
- ```ts
101
- import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
102
-
103
- await AutoUpdate.run({
60
+ ```typescript
61
+ await AutoUpdate.runByExternalStorage({
62
+ dirPath: "updates", // 외부 스토리지 루트 기준 상대 경로
104
63
  log: (messageHtml) => {
105
- // Display progress/status messages (may contain HTML)
106
- document.getElementById("status")!.innerHTML = messageHtml;
64
+ // 진행 상태 HTML 표시
107
65
  },
108
- serviceClient: myServiceClient,
109
66
  });
110
67
  ```
111
68
 
112
- | Parameter | Type | Description |
113
- |-----------|------|-------------|
114
- | `opt.log` | `(messageHtml: string) => void` | Callback for progress/status messages (may include HTML) |
115
- | `opt.serviceClient` | `ServiceClient` | Service client instance connected to a server that implements `AutoUpdateService` |
69
+ 동작 흐름:
70
+ 1. `REQUEST_INSTALL_PACKAGES` 권한 확인/요청
71
+ 2. 외부 스토리지의 `dirPath`에서 `.apk` 파일 목록 조회
72
+ 3. 파일명(`1.2.3.apk` -> `1.2.3`)을 semver로 파싱하여 최신 버전 선택
73
+ 4. 현재 앱 버전과 비교 후 설치
116
74
 
117
- **Returns:** `Promise<void>`
75
+ ### APK 설치 (저수준 API)
118
76
 
119
- **Flow:**
120
- 1. Queries `AutoUpdateService.getLastVersion("android")` for latest version info.
121
- 2. Checks and requests install permissions if needed.
122
- 3. Compares server version with current app version using semver.
123
- 4. Downloads the APK with progress reporting.
124
- 5. Triggers APK installation and freezes the app until restart.
77
+ `ApkInstaller`는 `AutoUpdate` 내부에서 사용되지만, 직접 호출도 가능하다.
125
78
 
126
- #### `AutoUpdate.runByExternalStorage(opt)`
79
+ ```typescript
80
+ import { ApkInstaller } from "@simplysm/capacitor-plugin-auto-update";
127
81
 
128
- External-storage-based update strategy. Scans a directory on external storage for APK files named by semver version (e.g., `1.2.3.apk`), finds the latest, and triggers installation if newer than the current version.
82
+ // 권한 확인 (granted: 설치 허용됨, manifest: 매니페스트에 권한 선언됨)
83
+ const perms = await ApkInstaller.checkPermissions();
84
+ // { granted: boolean; manifest: boolean }
129
85
 
130
- ```ts
131
- import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
86
+ // 권한 요청 (Android 8+: 설정 화면으로 이동)
87
+ await ApkInstaller.requestPermissions();
132
88
 
133
- await AutoUpdate.runByExternalStorage({
134
- log: (messageHtml) => {
135
- document.getElementById("status")!.innerHTML = messageHtml;
136
- },
137
- dirPath: "updates/my-app",
138
- });
89
+ // APK 설치 (content:// URI 필요, FileProvider URI)
90
+ await ApkInstaller.install(apkUri);
91
+
92
+ // 앱 버전 정보 조회
93
+ const info = await ApkInstaller.getVersionInfo();
94
+ // { versionName: "1.0.0", versionCode: "1" }
139
95
  ```
140
96
 
141
- | Parameter | Type | Description |
142
- |-----------|------|-------------|
143
- | `opt.log` | `(messageHtml: string) => void` | Callback for progress/status messages (may include HTML) |
144
- | `opt.dirPath` | `string` | Relative path within external storage containing versioned APK files |
97
+ ## API 레퍼런스
98
+
99
+ ### `AutoUpdate` (abstract class, static 메서드)
145
100
 
146
- **Returns:** `Promise<void>`
101
+ | 메서드 | 시그니처 | 설명 |
102
+ |--------|----------|------|
103
+ | `run` | `(opt: { log: (messageHtml: string) => void; serviceClient: ServiceClient }) => Promise<void>` | 서버 기반 자동 업데이트 |
104
+ | `runByExternalStorage` | `(opt: { log: (messageHtml: string) => void; dirPath: string }) => Promise<void>` | 외부 스토리지 기반 업데이트 |
147
105
 
148
- **Flow:**
149
- 1. Checks and requests install permissions if needed.
150
- 2. Reads the external storage directory for `.apk` files with semver-formatted names.
151
- 3. Finds the highest version using semver comparison.
152
- 4. Compares with the current app version.
153
- 5. Triggers APK installation and freezes the app until restart.
106
+ ### `ApkInstaller` (abstract class, static 메서드)
154
107
 
155
- ---
108
+ | 메서드 | 시그니처 | 설명 |
109
+ |--------|----------|------|
110
+ | `checkPermissions` | `() => Promise<{ granted: boolean; manifest: boolean }>` | 설치 권한 확인 |
111
+ | `requestPermissions` | `() => Promise<void>` | 설치 권한 요청 |
112
+ | `install` | `(apkUri: string) => Promise<void>` | APK 설치 (content:// URI) |
113
+ | `getVersionInfo` | `() => Promise<VersionInfo>` | 앱 버전 정보 조회 |
156
114
 
157
- ### `VersionInfo`
115
+ ### `VersionInfo` (interface)
158
116
 
159
- ```ts
117
+ ```typescript
160
118
  interface VersionInfo {
161
- versionName: string; // Semantic version string, e.g. "1.2.3"
162
- versionCode: string; // Android numeric version code, e.g. "10"
119
+ versionName: string; // semver 문자열 (예: "1.0.0")
120
+ versionCode: string; // 빌드 번호 문자열
163
121
  }
164
122
  ```
165
123
 
166
- ### `ApkInstallerPlugin`
124
+ ## 플랫폼 지원
167
125
 
168
- Low-level Capacitor plugin interface. Use the `ApkInstaller` static class instead of calling this directly.
169
-
170
- ```ts
171
- interface ApkInstallerPlugin {
172
- install(options: { uri: string }): Promise<void>;
173
- checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>;
174
- requestPermissions(): Promise<void>;
175
- getVersionInfo(): Promise<VersionInfo>;
176
- }
177
- ```
126
+ | 기능 | Android | Web |
127
+ |------|---------|-----|
128
+ | APK 설치 | FileProvider URI + ACTION_VIEW 인텐트 | alert 표시 후 정상 반환 |
129
+ | 버전 확인 | PackageManager API | `import.meta.env.__VER__` (기본값 `"0.0.0"`) |
130
+ | 권한 관리 | REQUEST_INSTALL_PACKAGES (Android 8+) | 항상 granted/manifest = true |
131
+ | 권한 설정 이동 | ACTION_MANAGE_UNKNOWN_APP_SOURCES | no-op |
178
132
 
179
- ## Dependencies
133
+ ## Android 네이티브 구현
180
134
 
181
- - `@simplysm/capacitor-plugin-file-system` -- File system access for reading/writing APK files
182
- - `@simplysm/core-browser` -- `fetchUrlBytes` for downloading APK files with progress
183
- - `@simplysm/core-common` -- Utility functions (`html`, `wait`, `path`)
184
- - `@simplysm/service-client` -- Server communication for the server-based update strategy
185
- - `@simplysm/service-common` -- `AutoUpdateService` type definition
186
- - `semver` -- Semantic version comparison
187
- - `@capacitor/core` -- Capacitor plugin system (peer dependency)
135
+ - **패키지:** `kr.co.simplysm.capacitor.apkinstaller`
136
+ - **플러그인명:** `ApkInstaller`
137
+ - `install`: `ACTION_VIEW` 인텐트로 APK 설치 (`FLAG_GRANT_READ_URI_PERMISSION`)
138
+ - `checkPermissions`: `canRequestPackageInstalls()` (Android 8+) + 매니페스트 검사
139
+ - `requestPermissions`: `ACTION_MANAGE_UNKNOWN_APP_SOURCES` 설정 화면 이동
140
+ - `getVersionInfo`: `PackageManager.getPackageInfo`로 versionName/versionCode 조회
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simplysm/capacitor-plugin-auto-update",
3
- "version": "13.0.85",
3
+ "version": "13.0.86",
4
4
  "description": "Simplysm Package - Capacitor Auto Update Plugin",
5
5
  "author": "simplysm",
6
6
  "license": "MIT",
@@ -19,11 +19,11 @@
19
19
  ],
20
20
  "dependencies": {
21
21
  "semver": "^7.7.4",
22
- "@simplysm/capacitor-plugin-file-system": "13.0.85",
23
- "@simplysm/core-browser": "13.0.85",
24
- "@simplysm/core-common": "13.0.85",
25
- "@simplysm/service-client": "13.0.85",
26
- "@simplysm/service-common": "13.0.85"
22
+ "@simplysm/capacitor-plugin-file-system": "13.0.86",
23
+ "@simplysm/core-browser": "13.0.86",
24
+ "@simplysm/service-client": "13.0.86",
25
+ "@simplysm/core-common": "13.0.86",
26
+ "@simplysm/service-common": "13.0.86"
27
27
  },
28
28
  "devDependencies": {
29
29
  "@capacitor/core": "^7.6.0",