To maintain a fluid user experience, it is important to set up fallbacks for your flows, paywalls, and onboardings. This precaution extends the application’s capabilities in case of partial or complete loss of internet connection.

• If the application cannot access Adapty servers:

  It will be able to display a fallback flow or paywall, and access the local onboarding configuration.

• If the application cannot access the internet:

  It will be able to display a fallback flow or paywall. Onboardings include remote content and require an internet connection to function.

The Adapty SDK reads the fallback file from the native bundle — an iOS resource inside the .app package, or an entry under android/app/src/main/assets/. In an Expo project, npx expo prebuild --clean regenerates those directories on every run, so you can’t drop the files in manually. The react-native-adapty config plugin wires the file into the native bundle for you.

Configuration

1. Place the fallback JSON files anywhere in your project — typically next to other assets:

   <your-project>/
   └── assets/
       ├── ios_fallback.json
       └── android_fallback.json

2. Add the fallbackFile option to the react-native-adapty entry in app.json (or app.config.js). Each platform key is optional — wire up only the platforms you need:

   {
     "expo": {
       "plugins": [
         [
           "react-native-adapty",
           {
             "fallbackFile": {
               "ios": "./assets/ios_fallback.json",
               "android": "./assets/android_fallback.json"
             }
           }
         ]
       ]
     }
   }

   Adapty exports a different fallback JSON for each platform — Apple product IDs on iOS, Google Play product IDs on Android. Point each platform to its own file.

3. Regenerate the native projects:

   npx expo prebuild

   The plugin adds the iOS file to the Xcode project’s bundle resources and copies the Android file into android/app/src/main/assets/. The prebuild output includes lines like:

   [react-native-adapty] Registered ios_fallback.json as iOS bundle resource
   [react-native-adapty] Copied android_fallback.json to android assets/

4. Register the file with the SDK at runtime:

   import { adapty } from 'react-native-adapty';
   
   await adapty.activate('PUBLIC_SDK_KEY');
   
   await adapty.setFallback({
     ios: { fileName: 'ios_fallback.json' },
     android: { relativeAssetPath: 'android_fallback.json' },
   });

   The file names passed to setFallback must match the basenames of the files configured under fallbackFile.

Verification

After npx expo prebuild, check both platforms:

• Android: List the contents of android/app/src/main/assets/. The file configured under fallbackFile.android should be present, and the iOS-only filename should not appear here.
• iOS: Search ios/<ProjectName>.xcodeproj/project.pbxproj for the iOS filename. It should appear in PBXFileReference, the Resources group, and PBXResourcesBuildPhase. The Android-only filename should not appear in project.pbxproj.