多端接入指南

CommonSrv 服务端、用户、积分、订阅和业务 API 只有一套；各平台只替换登录容器、安全存储和商店购买。现有 Web 应用不需要迁移。请先选平台，不要把 Web iframe、localStorage 或 Web 数字商品支付复制到原生 App。

购买链路结论：iOS/Android 的订阅项与积分包不使用 WebView。 CommonSrv catalog 只下发允许售卖的 Product ID；商品名称、当地价格、币种、周期和购买确认必须来自 StoreKit 2 / Google Play Billing。商店扣款后，CommonSrv 服务端复核交易并发放订阅或积分。只有 Web 端继续使用现有 Web 支付页。

平台	登录	Session	订阅与积分购买
Web	Browser SDK 托管登录	SDK localStorage	CommonSrv Web 支付页
iOS	原生 Apple/Google/Facebook；邮箱/手机走系统认证会话	Keychain	StoreKit 2 原生商品与购买
Android	Credential Manager Google；邮箱/手机走 Custom Tabs	Keystore	Google Play Billing
macOS	原生 Apple 或系统认证会话	Keychain	按分发渠道：StoreKit 或 Web
Windows	系统浏览器 OAuth + 回调	Credential Locker	按分发渠道：Microsoft Store 或 Web

Web

推荐：已有 Web 项目继续使用现有 Browser SDK，零迁移。

<script src="https://<your-commonsrv-host>/sdk/commonsrv-browser.js"></script>
<script>
  CommonSrv.configure({ clientId: "cli_xxx" });
  login.onclick   = () => CommonSrv.auth.openLogin();
  billing.onclick = () => CommonSrv.billing.open();
</script>

• React、Vue、Angular、Svelte和传统 HTML 共用同一个 SDK。
• 现有 client_id、用户、积分、订阅、localStorage key 和 API 保持不变。
• 完整 Web 能力继续查看 /docs；服务端与其它语言查看 /docs-rest。

iOS / App Store

推荐：Apple、Google、Facebook 使用原生 Provider；邮箱、手机、注册和找回密码使用 ASWebAuthenticationSession 承载托管认证页。

const commonsrv = createReactNativeCommonSrv({
  clientId: "cli_xxx",
  baseUrl: "https://<your-commonsrv-host>",
  platform: "ios",
  bundleId: "com.example.app",
  secureStorage: keychainStorage,
  providers: { apple: appleProvider, google: googleProvider, facebook: facebookProvider },
  purchases: storeKit2Provider,
});

await commonsrv.auth.signIn("apple");
const { products } = await commonsrv.store.catalog();
await commonsrv.store.purchase(products[0].productId);

• Sign in with Apple 使用 AuthenticationServices，并把 identityToken + nonce 交给 CommonSrv。
• Google 使用官方 iOS Provider；不要在普通 WKWebView 中完成 OAuth。
• 商品名称、价格、周期与可售状态来自 StoreKit；禁止 WebView 商品页和 Web 数字商品支付。
• 支持账号创建时，宿主 App 必须提供账号删除入口。

Android / Google Play

推荐：Google 使用 Credential Manager；邮箱与手机登录通过 Custom Tabs打开 CommonSrv 托管认证页。

const commonsrv = createReactNativeCommonSrv({
  clientId: "cli_xxx",
  baseUrl: "https://<your-commonsrv-host>",
  platform: "android",
  bundleId: "com.example.app",
  secureStorage: keystoreStorage,
  providers: { google: googleProvider, facebook: facebookProvider },
  purchases: playBillingProvider,
});

await commonsrv.auth.signIn("google");
const { products } = await commonsrv.store.catalog();
await commonsrv.store.purchase(products[0].productId);

• Google ID token 必须由 CommonSrv 服务端校验，客户端不能自行信任 claims。
• 购买结果上传 purchase token；CommonSrv 使用 Android Publisher API 复核后入账。
• 处理 pending purchase、恢复购买和退款；价格只使用 Play Billing 返回值。
• refresh token 使用 Keystore 保护的存储，不写明文 AsyncStorage。

macOS

推荐：业务 Core 与移动端共用；登录和购买由实际分发渠道决定。

const commonsrv = createDesktopCommonSrv({
  clientId: "cli_xxx", baseUrl: "https://<your-commonsrv-host>", platform: "macos",
  bundleId: "com.example.mac",
  secureStorage: createKeytarSessionStorage(keytar, "com.example.mac"),
  authSession, store: storeKitProvider,
});

await commonsrv.auth.signInHosted({ redirectUri: "example-mac://auth/callback" });
const { products } = await commonsrv.store.catalog();

• Mac App Store：Apple 登录优先 AuthenticationServices；数字商品使用 StoreKit。
• 官网分发：系统浏览器认证；符合业务与地区规则时可继续 Web 支付。
• Session 保存到 Keychain。Tauri/Electron 只做薄壳，不复制认证与积分逻辑。

Windows

推荐：使用 SDK Core 或 REST；登录通过系统浏览器 OAuth 回调，不维护第二套 CommonSrv。

const commonsrv = createDesktopCommonSrv({
  clientId: "cli_xxx", baseUrl: "https://<your-commonsrv-host>", platform: "windows",
  bundleId: "9EXAMPLEAPP",
  secureStorage: createKeytarSessionStorage(keytar, "ExampleApp"),
  authSession, store: microsoftStoreProvider,
});

const ticket = await commonsrv.store.windowsCollectionsTicket();
// 把 ticket.service_ticket + ticket.publisher_user_id 交给 Windows native bridge

• Session 保存到 Windows Credential Locker/DPAPI，禁止明文文件。
• Microsoft Store 使用 Windows.Services.Store + User Collections ID；CommonSrv 服务端通过 Entra 和 Collections API 验权。官网分发可使用系统浏览器 Web 支付。
• 桌面 UI 可以是 React/Tauri/Electron，但 token 刷新和 CommonSrv API 仍只来自 SDK Core。

CommonSrv 后台配置

推荐：每个原生 App 配置一次；密钥只放部署环境变量，数据库只保存环境变量名。

• 登记 CommonSrv project/client_id、platform、Bundle ID 或 Package Name。
• 登记 Apple/Google OAuth Client ID，以及可选 Facebook App ID。
• 将 Store Product ID 映射到 CommonSrv 套餐或积分包。
• 配置 Apple App Store Server API、Google Play 服务账号或 Microsoft Entra 环境变量。
• 先在独立测试项目使用 Apple Sandbox、Google License Tester 或 Microsoft Store Sandbox，随后再启用正式商品。

React Native 的完整可执行规范随 SDK 包提供：AI-INTEGRATION.md；平台核对与测试分别见 INTEGRATION.md 和 TESTING.md。规范包含准确请求字段、 adapter 契约、商品 UI 数据源、购买/恢复顺序、错误表和 AI 验收清单。