---
title: "Migrate Adapty React Native SDK to v4.1"
description: "Migrate to Adapty React Native SDK v4.1: enable Adapty Attribution explicitly, adopt the renamed external attribution APIs, and re-download your fallback file."
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skill. Claude Code (self-updating via plugin): `claude plugin marketplace add adaptyteam/adapty-skills && claude plugin install adapty-skills@adapty` — other tools: `npx skills add adaptyteam/adapty-skills --all`

Adapty React Native SDK 4.1 changes how Adapty Attribution is enabled, renames the external attribution APIs, and changes the fallback file format. It also lets your app take over App Store promoted in-app purchases and brings back the `hasViewConfiguration` flag on `AdaptyFlow`.

:::warning
The renamed APIs are a hard break. The old names are removed outright — there are no deprecated aliases to bridge them. Code that type-checks against 4.0.x fails on 4.1 until you rename every call site listed below.
:::

If you're still on 3.x, start with [Migrate to v4.0](migration-to-react-native-sdk-v4) and then follow this guide.

## Quick reference

| v4.0 | v4.1 |
|---|---|
| Adapty Attribution enabled automatically | Adapty Attribution disabled by default; opt in with `adaptyAttributionEnabled: true` |
| `adapty.updateAttribution(attribution, source)` | `adapty.updateExternalAttribution(attribution, provider)` |
| `AttributionSource` | `AdaptyExternalAttributionProvider`, with a new `'custom'` value |
| `AdaptyProfile.appliedAttributionSources` | `AdaptyProfile.appliedExternalAttributionProviders` |
| Fallback file downloaded for 4.0 | New fallback file format; download the file again |
| Promoted in-app purchases completed automatically, with no way to intercept them | The `'onPromotedPurchaseReceived'` event and `adapty.makePromotedPurchase(product)` hand completion to your app |
| `hasViewConfiguration` absent from `AdaptyFlow` | `hasViewConfiguration` back on `AdaptyFlow` |
| iOS project integrated with CocoaPods | CocoaPods, or React Native's SPM integration in a pure React Native project |

## Installation

Update the `react-native-adapty` package:

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

The runtime requirements are unchanged from 4.0: **iOS 15.0** and **React Native 0.75**. See [Install Adapty SDK](sdk-installation-reactnative) for the full setup.

4.1 also supports React Native's SPM integration, which replaces CocoaPods for your iOS project and needs **React Native 0.87** or later. It covers pure React Native projects only, CocoaPods remains the default, and moving over is optional — see [Set up your iOS project](sdk-installation-react-native-pure#set-up-your-ios-project). If your app uses [Kids Mode](kids-mode-react-native), each package manager applies it differently.

## ⚠️ Adapty Attribution is disabled by default \{#adapty-attribution-is-disabled-by-default\}

:::warning
If you update to SDK 4.1 and don't opt in, [Adapty Attribution](user-acquisition) breaks silently — installs stop registering, and nothing warns you.
:::

In 4.0 and earlier, the SDK registered installs for [Adapty Attribution](user-acquisition) automatically. Starting from 4.1, this is off by default: the SDK doesn't register installs, the `'onInstallationDetailsSuccess'` and `'onInstallationDetailsFail'` events never fire, and `getCurrentInstallationStatus` returns the `not_available` status.

If you use Adapty Attribution, enable it when activating the SDK:

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

If you don't use Adapty Attribution, no changes are needed.

## Renamed external attribution APIs

The APIs that pass attribution data from an external provider (Adjust, AppsFlyer, Branch, Tenjin, or a custom one) are renamed to match the native SDKs.

### updateAttribution → updateExternalAttribution

The method is renamed and its second parameter is renamed from `source` to `provider`. Attribution data is still a plain object:

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

### AttributionSource → AdaptyExternalAttributionProvider

The provider type is renamed. It stays an open union — the predefined values are `'apple_search_ads'`, `'adjust'`, `'appsflyer'`, `'branch'`, `'tenjin'`, and a new `'custom'` for providers Adapty doesn't integrate with directly. Any other string is accepted too, so a provider Adapty adds later works without an SDK update:

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

### AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

The profile property that lists the attribution providers applied to the profile is renamed, and its element type changes accordingly:

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

Code that reads it needs updating — see [Show an Apple Ads targeted paywall](react-native-show-aa-targeted-paywall).

## Fallback files

The [fallback file](fallback-flows) format changed in SDK 4.1. Download the file again from **[Placements](https://app.adapty.io/placements)** > **Fallbacks** and bundle it in your app, even if you already downloaded one for 4.0.

:::warning
This step produces no build error. If you skip it, `setFallback` rejects the outdated file and every placement loses its fallback.
:::

## hasViewConfiguration returns to AdaptyFlow

4.0 dropped `hasViewConfiguration` when `AdaptyPaywall` became `AdaptyFlow`. 4.1 restores it on `AdaptyFlow`, so a v3-era `hasViewConfiguration` branch works again once you rename the function and the object it reads:

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

On 4.0, where the flag is absent, `createFlowView` throws an `AdaptyError` for a flow with no view configuration. That's still true on 4.1 — the flag is an alternative to catching, not a replacement. See [Fetch the view configuration](react-native-get-pb-paywalls#fetch-the-view-configuration).

## App Store promoted in-app purchases

On 4.0, an [in-app purchase promoted on your App Store product page](react-native-making-purchases#in-app-purchases-from-the-app-store) completed on its own and Adapty recorded the transaction like any other, but your app had no way to intercept it. 4.1 adds that hook, so this is a new capability rather than a migration step: without code of your own, the SDK still completes promoted purchases for you.

Write code only to take over completion yourself — for example to show a screen first. Register a listener for the new `'onPromotedPurchaseReceived'` event, and complete the purchase with `adapty.makePromotedPurchase`. While that listener is registered, the SDK stops completing promoted purchases for you.

:::warning
The hook is built on StoreKit 2 and requires **iOS 16.4** or later. Below iOS 16.4, the event never fires and promoted purchases complete the way they did on 4.0. The event never fires on Android either.
:::