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 away from Ionic Enterprise SDK plugins and onto open alternatives.

将Capacitor应用从Ionic Enterprise SDK插件迁移到开源替代方案。

When to Use This Skill

什么时候使用该Skill

User is replacing
```
@ionic-enterprise/*
```
plugins
User wants to remove Ionic Enterprise dependencies from an app
User needs a migration path for auth, biometric unlock, or secure local storage

用户需要替换
```
@ionic-enterprise/*
```
类插件
用户想要移除应用中的Ionic Enterprise依赖
用户需要认证、生物识别解锁或安全本地存储的迁移路径

Live Project Snapshot

项目实时快照

Detected Ionic Enterprise and replacement packages: !

node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@ionic-enterprise/')||name.startsWith('@capgo/')||name==='@capacitor/preferences')out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

检测到的Ionic Enterprise及替代包： !

node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@ionic-enterprise/')||name.startsWith('@capgo/')||name==='@capacitor/preferences')out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

Replacement Map

替换映射表

Ionic Enterprise plugin	Typical use	Replacement path
Auth Connect	Social or OIDC login	`@capgo/capacitor-social-login` and its OAuth/OIDC compatibility flow
Identity Vault	Biometric gate + protected session state	`@capgo/capacitor-native-biometric` plus app-managed session storage
Secure Storage	Encrypted local data	`@capgo/capacitor-fast-sql` for encrypted local storage and structured persistence

If the app only needs non-sensitive key-value storage, use

@capacitor/preferences

. For encrypted local storage or structured local persistence, prefer

@capgo/capacitor-fast-sql

Ionic Enterprise插件	典型用途	替换方案
Auth Connect	社交或OIDC登录	`@capgo/capacitor-social-login` 及其OAuth/OIDC兼容流程
Identity Vault	生物识别校验+受保护的会话状态	`@capgo/capacitor-native-biometric` 搭配应用层管理的会话存储
Secure Storage	加密本地数据存储	用 `@capgo/capacitor-fast-sql` 实现加密本地存储和结构化持久化

如果应用仅需要非敏感的键值存储，可使用

@capacitor/preferences

。对于加密本地存储或结构化本地持久化场景，优先选择

@capgo/capacitor-fast-sql

。

Agent Behavior

Agent执行规则

Auto-detect Ionic Enterprise dependencies in
```
package.json
```
before asking questions.
Migrate one plugin at a time when the app uses multiple Ionic Enterprise packages.
Preserve behavior: same redirect URIs, same scopes, same session rules, and same stored keys whenever possible.

提问前先自动检测
```
package.json
```
中的Ionic Enterprise依赖
当应用使用多个Ionic Enterprise包时，一次迁移一个插件
尽可能保留原有行为：相同的重定向URI、相同的权限范围、相同的会话规则和相同的存储键

Procedures

操作流程

Step 1: Detect Ionic Enterprise Dependencies

步骤1：检测Ionic Enterprise依赖

Start from the injected package snapshot, then read

package.json

directly and look for:

```
@ionic-enterprise/auth
```
```
@ionic-enterprise/identity-vault
```
```
@ionic-enterprise/secure-storage
```

If none are present, tell the user no Ionic Enterprise plugins were detected.

If multiple are present, list them and migrate them in a clear order.

从注入的包快照开始，直接读取

package.json

查找以下依赖：

```
@ionic-enterprise/auth
```
```
@ionic-enterprise/identity-vault
```
```
@ionic-enterprise/secure-storage
```

如果未检测到以上依赖，告知用户未找到Ionic Enterprise插件。

如果检测到多个依赖，列出所有依赖并按清晰的顺序依次迁移。

Step 2: Replace Auth Connect

步骤2：替换Auth Connect

Move social and enterprise identity flows to

@capgo/capacitor-social-login

For OIDC providers, keep the provider-specific flow aligned with the compatibility wrapper or the plugin's documented OAuth/OIDC path so scopes, redirect URLs, and callback handling stay intact.

将社交和企业身份认证流程迁移到

@capgo/capacitor-social-login

。

对于OIDC提供商，保持提供商专属流程与兼容封装或插件官方文档的OAuth/OIDC路径对齐，确保权限范围、重定向URL和回调处理逻辑保持不变。

Step 3: Replace Identity Vault

步骤3：替换Identity Vault

Identity Vault usually combines biometric unlock with protected app state.

Use

@capgo/capacitor-native-biometric

for device-level unlock checks, then rebuild the session timeout and lock screen behavior in app code.

Keep secrets out of plain client storage. Store only the minimum local state required for UX continuity.

Identity Vault通常结合了生物识别解锁和受保护的应用状态功能。

使用

@capgo/capacitor-native-biometric

实现设备级的解锁校验，然后在应用代码中重新实现会话超时和锁屏行为。

不要将密钥存储在明文客户端存储中，仅存储保证UX连续性所需的最少本地状态。

Step 4: Replace Secure Storage

步骤4：替换Secure Storage

If the app stores encrypted local data, move it to

@capgo/capacitor-fast-sql

If the app uses structured local persistence, keep it on

@capgo/capacitor-fast-sql

so the encrypted and non-encrypted paths stay on the same engine.

If the app only needs non-sensitive key-value storage, move those values to

@capacitor/preferences

Preserve the database schema and migrate the access layer instead of rewriting the data model when the app already relies on SQLite-backed storage.

如果应用存储加密本地数据，将其迁移到

@capgo/capacitor-fast-sql

。

如果应用使用结构化本地持久化，继续使用

@capgo/capacitor-fast-sql

，保证加密和非加密路径使用相同的存储引擎。

如果应用仅需要非敏感的键值存储，将对应值迁移到

@capacitor/preferences

。

当应用已经依赖SQLite支持的存储时，保留数据库结构并迁移访问层，不要重写数据模型。

Step 5: Search for Remaining Enterprise Imports

步骤5：搜索剩余的企业版导入

After the replacement work, search the project for remaining enterprise references:

bash

rg -n "@ionic-enterprise" .

Replace or remove any leftovers before continuing.

完成替换工作后，搜索项目中剩余的企业版引用：

bash

rg -n "@ionic-enterprise" .

继续操作前替换或移除所有残留引用。

Step 6: Clean Up and Verify

步骤6：清理与验证

Remove unused enterprise packages from

package.json

, reinstall dependencies with the repository's existing package manager, and run sync from the app directory that contains

capacitor.config.*

bash

npm install
npx cap sync

Then verify the app builds on every shipped platform.

从

package.json

中移除未使用的企业版包，使用仓库现有包管理器重新安装依赖，然后在包含

capacitor.config.*

的应用目录下执行同步命令：

bash

npm install
npx cap sync

然后验证应用在所有发布平台上都能正常构建。

Error Handling

错误处理

For storage migrations, keep encrypted data on
```
@capgo/capacitor-fast-sql
```
unless the use case is explicitly non-sensitive.
When OIDC behavior changes after migration, compare the before-and-after redirect and token exchange flow before shipping.
Reuse any existing secure native store instead of introducing a second storage model.

对于存储迁移，除非明确是不敏感的使用场景，否则将加密数据保留在
```
@capgo/capacitor-fast-sql
```
中。
如果迁移后OIDC行为发生变化，发布前对比迁移前后的重定向和令牌交换流程。
复用已有的安全原生存储，不要引入第二套存储模型。