迁移 Adapty Capacitor SDK 至 v4.3
Adapty Capacitor SDK 4.3 默认显示 Google Play 应用内消息,从 getOnboardingForDefaultAudience 中移除了一个未使用的参数,扩宽了错误码的类型,并要求从事件中获取推广产品。请查阅本指南中的每项变更,以保持应用行为不变,并确保 TypeScript 构建顺利通过。
如果你仍在使用 3.x,请先参阅迁移至 v4.1.1,再按本指南操作。
快速参考
| v4.2 | v4.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 请参阅控制商店消息。
在手动模式下,应用商店不会自动显示消息。如果你的应用从未调用 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 });
});
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 的底层内部详情。详见日志记录。