迁移 Adapty Capacitor SDK 至 v4.3

Adapty Capacitor SDK 4.3 默认显示 Google Play 应用内消息,从 getOnboardingForDefaultAudience 中移除了一个未使用的参数,扩宽了错误码的类型,并要求从事件中获取推广产品。请查阅本指南中的每项变更,以保持应用行为不变,并确保 TypeScript 构建顺利通过。

如果你仍在使用 3.x,请先参阅迁移至 v4.1.1,再按本指南操作。

快速参考

v4.2v4.3
params: undefined 或 fetchPolicy: undefined 会报错应用默认值
不请求 Google Play 消息Android 上默认显示 Google Play 消息
getOnboardingForDefaultAudience 接受 params.loadTimeoutMs 但忽略它params.loadTimeoutMs 已从其类型中移除
error.adaptyCode 的类型为已知错误码其类型同时允许当前 SDK 版本未知的错误码
在 iOS 上,makePromotedPurchase 接受你自行构建的产品需要使用来自 'onPromotedPurchaseReceived' 事件的产品
accessLevel.android.offerId已弃用 — 请读取顶层的 offerId

传入 undefined 的选项将回退至默认值

在 4.2 版本中,向 getFlow、getOnboarding 或其默认目标受众变体传入 params: undefined 会抛出 TypeError,且 fetchPolicy: undefined 会在原生侧报错。从 4.3 版本起,传入 undefined 的选项将保留其默认值:fetchPolicy 回退至 'reload_revalidating_cache_data',loadTimeoutMs 回退至 5000 毫秒。如果你之前通过省略这些键来规避该错误,现在可以直接将配置中的可选值原样传入。

默认显示 Google Play 消息

从 4.3 版本开始,SDK 会在每次 Activity 于 activate 后启动时(包括应用从后台返回时)请求 Google Play 应用内消息,例如支付拒绝通知。这些消息可能会覆盖在付费墙上方显示。

如果这对您的应用没有影响,则无需任何更改。在 'auto' 模式下,消息不会在冷启动时显示:请参阅 在 Android 上于启动时显示消息。如需保持 4.2 的行为,请在 Android 上使用手动处理方式,并且不要调用 showStoreMessages。如果您希望自行控制消息的显示时机,请在 Android 上以手动处理方式初始化 SDK,并在适合您应用的时机调用 showStoreMessages:


await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    storeMessagesHandling: Capacitor.getPlatform() === 'android' ? 'manual' : 'auto',
  },
});

仅在 Android 上设置手动处理,以保持 iOS 不变:在 iOS 16 及更高版本上,手动处理同样会暂存 App Store 消息,直到您的应用调用 showStoreMessages。完整 API 请参阅控制商店消息。

Warning

在手动模式下,应用商店不会自动显示消息。如果你的应用从未调用 showStoreMessages,用户将永远看不到付款失败的通知。

loadTimeoutMs 已从 getOnboardingForDefaultAudience 中移除

getOnboardingForDefaultAudience 从未使用过 params.loadTimeoutMs:默认受众请求没有超时机制。从 4.3 版本起,该参数也已从类型定义中移除,因此在对象字面量中传入该参数会导致 TypeScript 构建失败。无论如何请将其删除:SDK 会忽略它。

  const onboarding = await adapty.getOnboardingForDefaultAudience({
    placementId: 'YOUR_PLACEMENT_ID',
    params: {
      fetchPolicy: 'reload_revalidating_cache_data',
-     loadTimeoutMs: 5000,
    },
  });

getOnboarding 保留 loadTimeoutMs。

错误码类型支持未知错误码

原生 SDK 返回的错误码可能比你当前使用的 Capacitor SDK 更新。从 4.3 版本起,ErrorCode 类型也支持这些未知错误码,因此 ErrorCode[error.adaptyCode] 这样的查找操作,或对 error.adaptyCode 进行穷举 switch 的代码可能无法通过编译。请改用 error.codeName、getErrorCodeName() 或 isKnownErrorCode()。而 error.adaptyCode === ErrorCodeName.paymentCancelled 这类比较操作,或带有 default 分支的 switch,无需做任何修改。

4.3 还为早期版本中报告为未知的错误代码补充了名称,因此 getErrorPrompt(1050) 现在返回 'paymentPendingError',而不是 'Unknown code: 1050'。有关错误处理辅助函数的详细信息,请参阅处理错误。

按原样传入推广产品

在 iOS 上,makePromotedPurchase 现在需要使用 'onPromotedPurchaseReceived' 事件中产品携带的 App Store 购买意图。自行构建的产品,或通过 getPaywallProducts 获取的产品,在 4.2 中可以正常使用,但在 4.3 中会失败。请直接传入事件中的产品:

await adapty.addListener('onPromotedPurchaseReceived', async ({ product }) => {
  const result = await adapty.makePromotedPurchase({ product });
});

请参阅从 App Store 推广应用内购买。

android.offerId 已弃用

访问等级和订阅现在新增了顶级字段 offerId,用于标识购买订阅时所使用的 Google Play 优惠。访问等级上的 android.offerId 仍可使用,但已弃用。请改用顶级字段 offerId:它取决于购买时所使用的商店,而非设备的操作系统。

4.3 版本新增内容

以下新增功能均为可选接入,您现有的代码无需任何改动即可继续正常运行:

  • 控制应用商店消息:选择 App Store 和 Google Play 消息的显示时机。
  • 预加载版位:preloadFlows 和 preloadFlowsForDefaultAudience 可预热流程缓存。
  • 保留已关闭的流程:view.dismiss({ destroy: false }) 可保留流程以便再次展示,view.destroy() 则释放流程。
  • 12 个月承诺计划:product.subscription?.ios?.pricingTerms 属性描述 iOS 上的计划详情,访问等级还会上报 billingPlan 和 commitmentInfo。
  • 观察者模式:reportTransaction 接受可选参数 ios.jwsTransaction。
  • 4.3 新增错误码:billingPlanUnavailable(1060)、operationInProgress(3201)和 resolverFailure(3202),均仅限 iOS。详见错误处理。
  • 调试日志级别:'debug' 可记录原生 SDK 的底层内部详情。详见日志记录。