Skip to content

Using Storyteller SDK with Expo#

This guide will help you set up the Storyteller SDK in your Expo project. The configuration depends on which version of the Storyteller SDK you're using.

Choose Your Version#

For Storyteller SDK v11.0.0+#

  • Requires: React Native New Architecture enabled
  • Expo SDK: 53+ recommended

For Storyteller SDK v10.x#

  • Requires: React Native New Architecture disabled
  • Expo SDK: 48 or higher

Installation#

Install the SDK using npm or yarn:

# For latest version (v11.0.0+)
npm install @getstoryteller/react-native-storyteller-sdk

# For v10.x
npm install @getstoryteller/react-native-storyteller-sdk@^10.8.2 # or your desired version

or

# For latest version (v11.0.0+)
yarn add @getstoryteller/react-native-storyteller-sdk

# For v10.x
yarn add @getstoryteller/react-native-storyteller-sdk@^10.8.2 # or your desired version

Configure Expo Plugin#

Add the Storyteller plugin to your app.json or app.config.js:

{
  "expo": {
    "name": "your-app-name",
    "plugins": [
      "@getstoryteller/react-native-storyteller-sdk"
    ]
  }
}

## Architecture Configuration

### For SDK v11.0.0+ (New Architecture Required)

If using Expo 52 or later, the New Architecture is enabled by default. For older Expo versions, enable it in your `app.json`:

```json
{
  "expo": {
    "plugins": [
      "@getstoryteller/react-native-storyteller-sdk"
    ],
    "newArchEnabled": true,
    "ios": {
      "newArchEnabled": true
    },
    "android": {
      "newArchEnabled": true
    }
  }
}

For SDK v10.x (New Architecture Must Be Disabled)#

If using Expo 52 or later, you must explicitly disable the New Architecture:

{
  "expo": {
    "plugins": [
      "@getstoryteller/react-native-storyteller-sdk"
    ],
    "newArchEnabled": false,
    "ios": {
      "newArchEnabled": false
    },
    "android": {
      "newArchEnabled": false
    }
  }
}

Build Your Development Client#

After configuration, rebuild your development client:

# Clean prebuild (recommended when changing architecture settings)
npx expo prebuild --clean

npx expo run:ios
npx expo run:android

Upgrading from 11.0.5 or earlier on Expo apps#

Skip this section if you're installing the SDK for the first time.

If you previously prebuilt your project with Storyteller SDK version 11.0.5 or earlier, the config plugin may have added an Android autolinking exclusion to your project. This exclusion can prevent the TurboModule from registering correctly on newer Expo versions (Expo 52, 53, and 54).

Steps:

1) Open android/settings.gradle in your Expo app and remove any line excluding this package from Expo autolinking, for example:

expoAutolinking.exclude = (expoAutolinking.exclude ?: []) + ['@getstoryteller/react-native-storyteller-sdk']

2) Regenerate native projects so the change persists:

npx expo prebuild --clean

3) Rebuild and run:

npx expo run:android
npx expo run:ios

Troubleshooting#

Gradle codegen dependency error on Android (Expo SDK 52)#

Symptom (example error):

A problem was found with the configuration of task ':getstoryteller-react-native-storyteller-sdk:generateCodegenArtifactsFromSchema'.
Gradle detected a problem with the following location: node_modules/@getstoryteller/react-native-storyteller-sdk/android/build/generated/source/codegen/schema.json.
Reason: Task ':getstoryteller-react-native-storyteller-sdk:generateCodegenArtifactsFromSchema' uses this output of task ':getstoryteller_react-native-storyteller-sdk:generateCodegenSchemaFromJavaScript' without declaring a dependency.

This indicates a mismatch in the React Native codegen task wiring, typically caused by version misalignment between Expo SDK, react-native, and the react-native-gradle-plugin when using New Architecture (required for v11+).

Recommended fix:

  • Update to Expo SDK 53 or later. This aligns the toolchain and resolves the codegen task ordering issue reported on Expo 52.

If you must stay on Expo SDK 52 you can manually set the generateCodegenArtifactsFromSchema task to depend on the generateCodegenSchemaFromJavaScript task. This is not recommended as it will not be automatically updated when the schema changes.

When contacting support, please share:

  • expo version (Expo SDK)
  • react-native version
  • react-native-gradle-plugin version (from android/settings.gradle)
  • Your android/settings.gradle contents

Note: A client reported this error on Expo 52 with react-native 0.77.3 and resolved it by upgrading to Expo 53.

TurboModuleRegistry error on startup (Expo 54)#

Symptom:

Expo 54 error: Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'StorytellerSdk' could not be found.

Checklist:

  • Ensure you are using version 11.0.6 of the Storyteller SDK.
  • Ensure there is no expoAutolinking.exclude line referencing @getstoryteller/react-native-storyteller-sdk in android/settings.gradle.
  • Ensure the Storyteller plugin is present in app.json/app.config as shown above.
  • Clean and regenerate native projects:
npx expo prebuild --clean
npx expo run:android
  • If the issue persists, clear Gradle caches (delete android/.gradle and android/build) and rebuild.

Implementation Examples#

import StorytellerSdk from '@getstoryteller/react-native-storyteller-sdk';

const initializeStoryteller = async () => {
  try {
    await StorytellerSdk.initialize('YOUR_API_KEY', 'USER_ID');
    console.log('Storyteller initialized successfully');
  } catch (error) {
    console.error('Storyteller initialization error:', error);
  }
};

// ...rest of your code

import StorytellerSdk from '@getstoryteller/react-native-storyteller-sdk';

const initializeStoryteller = () => {
  StorytellerSdk.initialize(
    {
      apiKey: 'YOUR_API_KEY',
      externalId: 'USER_ID',
    },
    (callback: { result: boolean, message: string }) => {
      console.log(`Result: ${callback.result}, Message: ${callback.message}`);

      if (callback.result) {
        console.log('Storyteller initialized successfully');
      } else {
        console.error('Failed to initialize:', callback.message);
      }
    }
  );

// ...rest of your code
}

Expo Showcase App#

We provide an Expo Showcase app that demonstrates how to integrate and use the Storyteller SDK with Expo. Visit the Showcase App page for more information.

Next Steps#

Support#