ionic-enterprise-sdk-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ionic Enterprise SDK Migration

Ionic Enterprise SDK 迁移指南

Migrate Capacitor apps from discontinued Ionic Enterprise SDK plugins to Capawesome alternatives.

将Capacitor应用从已停止维护的Ionic Enterprise SDK插件迁移到Capawesome替代插件。

Plugin Mapping

插件映射表

Ionic Enterprise Plugin	Package	Capawesome Replacement	Package(s)
Auth Connect	`@ionic-enterprise/auth`	OAuth	`@capawesome-team/capacitor-oauth`
Identity Vault	`@ionic-enterprise/identity-vault`	Biometrics + Secure Preferences	`@capawesome-team/capacitor-biometrics` + `@capawesome-team/capacitor-secure-preferences`
Secure Storage (key-value)	`@ionic-enterprise/secure-storage`	Secure Preferences	`@capawesome-team/capacitor-secure-preferences`
Secure Storage (SQLite)	`@ionic-enterprise/secure-storage`	SQLite	`@capawesome-team/capacitor-sqlite`

All Capawesome replacement plugins require a Capawesome Insiders license.

Ionic Enterprise 插件	包名	Capawesome 替代插件	包名
Auth Connect	`@ionic-enterprise/auth`	OAuth	`@capawesome-team/capacitor-oauth`
Identity Vault	`@ionic-enterprise/identity-vault`	Biometrics + Secure Preferences	`@capawesome-team/capacitor-biometrics` + `@capawesome-team/capacitor-secure-preferences`
Secure Storage（键值对）	`@ionic-enterprise/secure-storage`	Secure Preferences	`@capawesome-team/capacitor-secure-preferences`
Secure Storage（SQLite）	`@ionic-enterprise/secure-storage`	SQLite	`@capawesome-team/capacitor-sqlite`

所有Capawesome替代插件均需要Capacawesome Insiders许可。

Prerequisites

前置条件

Capacitor 6, 7, or 8 app.
Node.js and npm installed.
A Capawesome Insiders license key.

Capacitor 6、7或8版本的应用。
已安装Node.js和npm。
拥有Capacawesome Insiders许可密钥。

Agent Behavior

Agent 行为规范

Auto-detect dependencies. Scan
```
package.json
```
for Ionic Enterprise packages before asking the user which plugins to migrate.
One plugin at a time. Complete the full migration for one plugin before starting the next.
Use the
capacitor-plugins
skill for installation. Delegate plugin installation and platform configuration to the
```
capacitor-plugins
```
skill. Only handle migration-specific steps (uninstall, code replacement) in this skill.
Preserve existing behavior. When replacing API calls, maintain the same functional behavior (e.g., same scopes, same stored keys, same database schema).

自动检测依赖项：在询问用户要迁移哪些插件之前，先扫描
```
package.json
```
查找Ionic Enterprise包。
逐个迁移插件：完成一个插件的完整迁移后，再开始下一个插件的迁移。
使用
capacitor-plugins
技能完成安装：将插件安装和平台配置工作委托给
```
capacitor-plugins
```
技能。本技能仅处理迁移特定步骤（卸载、代码替换）。
保留现有行为：替换API调用时，保持相同的功能行为（例如相同的权限范围、相同的存储键、相同的数据库架构）。

Procedures

迁移流程

Step 1: Detect Ionic Enterprise Dependencies

步骤1：检测Ionic Enterprise依赖项

Read

package.json

and check for these packages:

```
@ionic-enterprise/auth
```
→ Auth Connect
```
@ionic-enterprise/identity-vault
```
→ Identity Vault
```
@ionic-enterprise/secure-storage
```
→ Secure Storage

If none are found, inform the user that no Ionic Enterprise plugins were detected.

If multiple are found, list them and ask the user which to migrate first, or migrate all sequentially.

读取

package.json

并检查以下包：

```
@ionic-enterprise/auth
```
→ Auth Connect
```
@ionic-enterprise/identity-vault
```
→ Identity Vault
```
@ionic-enterprise/secure-storage
```
→ Secure Storage

如果未找到任何相关包，告知用户未检测到Ionic Enterprise插件。

如果找到多个包，列出所有包并询问用户优先迁移哪一个，或者按顺序迁移所有插件。

Step 2: Set Up the Capawesome npm Registry

步骤2：配置Capawesome npm 仓库

Check if the

@capawesome-team

npm registry is already configured:

bash

npm config get @capawesome-team:registry

If not configured, guide the user through setup:

bash

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

Ask the user for their license key if needed. Wait for confirmation before continuing.

检查

@capawesome-team

npm仓库是否已配置：

bash

npm config get @capawesome-team:registry

如果未配置，引导用户完成设置：

bash

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

如果需要，向用户索要许可密钥。等待用户确认后再继续。

Step 3: Migrate Each Plugin

步骤3：迁移每个插件

For each detected Ionic Enterprise plugin, read the corresponding reference file and follow the migration steps:

Auth Connect → Read
```
references/auth-connect-migration.md
```
Identity Vault → Read
```
references/identity-vault-migration.md
```
Secure Storage → Read
```
references/secure-storage-migration.md
```

Each reference file contains:

Feature mapping table (Ionic API → Capawesome API)
Key differences to be aware of
Step-by-step code replacement with before/after examples

For plugin installation and platform-specific configuration (Android permissions, iOS plist entries, Proguard rules, etc.), use the

capacitor-plugins

skill.

对于每个检测到的Ionic Enterprise插件，读取对应的参考文件并遵循迁移步骤：

Auth Connect → 读取
```
references/auth-connect-migration.md
```
Identity Vault → 读取
```
references/identity-vault-migration.md
```
Secure Storage → 读取
```
references/secure-storage-migration.md
```

每个参考文件包含：

功能映射表（Ionic API → Capawesome API）
需要注意的关键差异
带前后示例的分步代码替换指南

插件安装和平台特定配置（Android权限、iOS plist条目、Proguard规则等）请使用

capacitor-plugins

技能。

Step 4: Search for Remaining Ionic Enterprise Imports

步骤4：搜索剩余的Ionic Enterprise导入语句

After completing all migrations, search the codebase for any remaining Ionic Enterprise imports:

bash

grep -r "@ionic-enterprise" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx"

If any are found, replace them with the corresponding Capawesome imports.

完成所有迁移后，搜索代码库中是否存在剩余的Ionic Enterprise导入语句：

bash

grep -r "@ionic-enterprise" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx"

如果找到任何相关导入，将其替换为对应的Capawesome导入语句。

Step 5: Clean Up and Verify

步骤5：清理和验证

Remove all Ionic Enterprise packages from
```
package.json
```
:

bash

npm uninstall @ionic-enterprise/auth @ionic-enterprise/identity-vault @ionic-enterprise/secure-storage

Only uninstall packages that were actually installed.

Sync the project:

bash

npx cap sync

Verify the project builds successfully on all platforms.

从
```
package.json
```
中移除所有Ionic Enterprise包：

bash

npm uninstall @ionic-enterprise/auth @ionic-enterprise/identity-vault @ionic-enterprise/secure-storage

仅卸载实际已安装的包。

同步项目：

bash

npx cap sync

验证项目在所有平台上均可成功构建。

Error Handling

错误处理

Capawesome registry not configured: If
```
npm install
```
fails with a 404 or authentication error for
```
@capawesome-team/*
```
packages, verify the npm registry is configured correctly (Step 2).
Missing Capawesome Insiders license: All replacement plugins require a Capawesome Insiders license. Direct the user to capawesome.io/insiders to obtain one.
Identity Vault session management: Identity Vault's built-in auto-lock, timeout, and lock/unlock events have no direct equivalent. These must be rebuilt using application logic. See the session management section in
```
references/identity-vault-migration.md
```
.
Secure Storage encryption: Ionic Secure Storage has built-in encryption. Capawesome SQLite encryption requires additional platform configuration (SQLCipher). If the user needs database encryption, guide them through the SQLite encryption setup in the
```
capacitor-plugins
```
skill reference.
Web platform limitations: Capawesome Secure Preferences stores values unencrypted in
```
localStorage
```
on the web. This is for development only and should not be used in production.

Capawesome仓库未配置：如果
```
npm install
```
时
```
@capawesome-team/*
```
包出现404或认证错误，请验证npm仓库配置是否正确（步骤2）。
缺少Capawesome Insiders许可：所有替代插件均需要Capawesome Insiders许可。引导用户前往capawesome.io/insiders获取许可。
Identity Vault会话管理：Identity Vault内置的自动锁定、超时和锁定/解锁事件没有直接等效功能。必须使用应用逻辑重新实现这些功能。请查看
```
references/identity-vault-migration.md
```
中的会话管理部分。
Secure Storage加密：Ionic Secure Storage内置加密功能。Capawesome SQLite加密需要额外的平台配置（SQLCipher）。如果用户需要数据库加密，引导他们通过
```
capacitor-plugins
```
技能参考中的SQLite加密设置步骤进行配置。
Web平台限制：Capawesome Secure Preferences在Web平台上会将值以未加密的方式存储在
```
localStorage
```
中。这仅用于开发环境，请勿在生产环境中使用。