将 Adapty React Native SDK 迁移至 v4.1

Adapty React Native SDK 4.1 更改了 Adapty Attribution 的启用方式，重命名了外部归因 API，并更改了备用文件格式。此外，它还支持应用接管 App Store 推广应用内购买，并恢复了 AdaptyFlow 上的 hasViewConfiguration 标志。

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

快速参考

安装

更新 react-native-adapty 包：

npm install react-native-adapty@latest
# or
yarn add react-native-adapty@latest

运行时要求与 4.0 版本相同：iOS 15.0 和 React Native 0.75。完整配置步骤请参阅安装 Adapty SDK。

4.1 版本还支持 React Native 的 SPM 集成，可替代 iOS 项目中的 CocoaPods，需要 React Native 0.87 或更高版本。该集成仅适用于纯 React Native 项目，CocoaPods 仍为默认选项，迁移为可选操作——详见设置 iOS 项目。如果您的应用使用了儿童模式，不同的包管理器在处理方式上有所差异。

⚠️ Adapty 归因默认已禁用

在 4.0 及更早版本中，SDK 会自动为 Adapty Attribution 注册安装记录。从 4.1 开始，此功能默认关闭：SDK 不再注册安装，'onInstallationDetailsSuccess' 和 'onInstallationDetailsFail' 事件不会触发，getCurrentInstallationStatus 返回 not_available 状态。

如果你使用 Adapty Attribution，请在激活 SDK 时启用该功能：

  adapty.activate('YOUR_PUBLIC_SDK_KEY', {
+   adaptyAttributionEnabled: true,
  });

如果你未使用 Adapty Attribution，则无需做任何更改。

重命名的外部归因 API

用于从外部提供商（Adjust、AppsFlyer、Branch、Tenjin 或自定义来源）传入归因数据的 API 已重命名，以与原生 SDK 保持一致。

updateAttribution → updateExternalAttribution

该方法已重命名，第二个参数也从 source 改为 provider。归因数据仍为普通对象：

- await adapty.updateAttribution(attribution, 'adjust');
+ await adapty.updateExternalAttribution(attribution, 'adjust');

AttributionSource → AdaptyExternalAttributionProvider

提供者类型已重命名。它仍然是一个开放联合类型——预定义值为 'apple_search_ads'、'adjust'、'appsflyer'、'branch'、'tenjin'，以及新增的 'custom'（用于 Adapty 未直接集成的提供者）。同时也接受任意其他字符串，因此 Adapty 后续新增的提供者无需更新 SDK 即可使用：

- import type { AttributionSource } from 'react-native-adapty';
+ import type { AdaptyExternalAttributionProvider } from 'react-native-adapty';

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

该用户画像属性用于列出已应用到用户画像的归因提供商，现已重命名，其元素类型也相应更改：

- if (profile.appliedAttributionSources?.includes('apple_search_ads')) {
+ if (profile.appliedExternalAttributionProviders?.includes('apple_search_ads')) {
      // Apple Ads attribution has been applied
  }

读取该属性的代码需要更新——请参阅展示 Apple Ads 定向付费墙。

备用文件

备用文件的格式在 SDK 4.1 中有所变更。即使你已为 4.0 下载过备用文件，也请重新从 Placements > Fallbacks 下载并打包进你的应用。

hasViewConfiguration 恢复至 AdaptyFlow

4.0 在 AdaptyPaywall 更名为 AdaptyFlow 时移除了 hasViewConfiguration。4.1 将其恢复至 AdaptyFlow，因此只要将函数名和读取的对象重命名，v3 时代的 hasViewConfiguration 分支即可重新正常工作：

- if (paywall.hasViewConfiguration) {
-   const view = await createPaywallView(paywall);
+ if (flow.hasViewConfiguration) {
+   const view = await createFlowView(flow);
    await view.present();
  }

在 4.0 版本中，当标志不存在时，createFlowView 会对没有视图配置的流程抛出 AdaptyError。4.1 版本中这一行为依然保持——该标志是捕获异常的替代方案，而非替代品。请参阅获取视图配置。

App Store 推广应用内购买

在 4.0 版本中，在 App Store 产品页面推广的应用内购买会自动完成，Adapty 会像处理普通交易一样记录该交易，但你的应用无法拦截它。4.1 版本新增了这个钩子，因此这是一项新能力，而非迁移步骤：即使不添加任何代码，SDK 仍会自动为你完成推广购买。

仅编写代码以自行接管完成流程——例如先显示一个页面。为新的 'onPromotedPurchaseReceived' 事件注册监听器，并使用 adapty.makePromotedPurchase 完成购买。注册该监听器后，SDK 将不再自动为你完成促销购买。