快速开始

5 分钟内完成 SubHub 集成 — 从创建工作区到 SDK 首次购买验证。

前置条件

SubHub 工作区账号（注册后自动创建）
Apple App Store 或 Google Play 开发者账号
iOS / Android 应用项目

1. 创建应用

在 SubHub 中创建一个应用（App），填写应用名称、Bundle ID / Package Name 与目标平台（iOS 或 Android）。

创建完成后获得 Publishable Key（客户端 SDK 用）与 Secret Key（服务端 REST API 用）。每个应用独立一套密钥。

2. 配置商店凭证

在应用详情页配置 Provider 凭证：

Apple：Issuer ID、Key ID、Team ID 与 App Store Connect API 私钥。

Google Play：Service Account JSON 与 Package Name。

商店特定配置仅存在于 Provider Adapter 层，不会泄漏到核心数据模型。

3. 定义商品与权益

先创建权益定义（Entitlement Definition，如 premium），再创建商品（Product）并映射到该权益。

商品为 store-agnostic 目录条目；Entitlement 是鉴权的唯一单元。详见商品与权益文档。

4. 集成 SDK

在 App 入口初始化 SDK，用户登录后可选调用 identify。权益检查永远使用 hasEntitlement，不要查 Product。

import SubHub

// AppDelegate 或 App 入口
SubHub.configure(publishableKey: "pk_live_focustimer_ios_8f3k2m")

// 用户登录后（可选）
try await SubHub.identify("firebase_uid_8a2b")

// 检查权益 — 永远使用 Entitlement，不要查 Product
let isPremium = try await SubHub.hasEntitlement("premium")

5. 完成首次购买

调用 purchase 发起购买。SDK 自动处理 StoreKit / Play Billing 交互，并将凭证提交至平台验证。

验证通过后，Purchase 记录写入平台，Entitlement 自动发放，Webhook 事件推送至你的端点。

let result = try await SubHub.purchase(
    productId: "com.neo.focustimer.promo"
)
// result.entitlements 包含新发放的权益

try await SubHub.restore()

6. 配置 Webhook（可选）

SubHub 通过 HTTPS POST 向你的服务端推送 purchase.completed、entitlement.granted 等事件。Webhook 在工作区级别配置 — 一个端点可接收所有应用的事件。

请求携带 SubHub-Signature 请求头，使用 Webhook Secret 验证 payload 完整性。