Documentation
StreamsPlaybackEncodingBitmovin Dashboard

Migrating to Bitmovin React Native SDK v1.0.0

Learn how to migrate from versions prior to 1.0.0 to the new Expo SDK-based configuration

Suggest Edits

Migrating to v1.0.0

This guide helps you migrate from versions prior to 1.0.0 to v1.0.0 or newer, which introduces Expo SDK support for automatic native configuration.

Overview of Changes

Version 1.0.0 introduces the Expo Config Plugin, which automatically manages native configuration that previously required manual setup. This includes:

  • Background modes configuration (iOS)
  • Picture-in-Picture attributes (Android)
  • Google Cast setup for both platforms
  • Offline playback configuration
  • AirPlay support (iOS)

Prerequisites

For Bare React Native Apps

If you're using a bare React Native app (not managed by Expo), you must first install Expo modules:

# Install and configure the expo package automatically
npx install-expo-modules@latest

If this fails, follow the official Expo SDK guide here.

This adds the minimal Expo infrastructure needed to use config plugins, without converting your entire app to Expo.

For Expo Apps

If you're already using Expo, no additional prerequisites are needed.

Step 1: Update Dependencies

Update to the latest version of the SDK:

npx expo install bitmovin-player-react-native

Step 2: Remove Old Native Code

Remove all manual native configurations that are now handled by the Expo plugin.

iOS - Info.plist

Remove the following entries from ios/YourApp/Info.plist:

<!-- Remove these background modes -->
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

<!-- Remove Google Cast configuration -->
<key>NSBonjourServices</key>
<array>
    <string>_googlecast._tcp</string>
    <string>_YOUR_CAST_APP_ID._googlecast._tcp</string>
</array>

iOS - Build Files

Remove from ios/Podfile:

# Remove manual Google Cast SDK (now handled by plugin)
pod 'google-cast-sdk', '~> 4.x.x'

Android - AndroidManifest.xml

Remove from android/app/src/main/AndroidManifest.xml:

<!-- Remove Picture-in-Picture configuration -->
<activity
    android:supportsPictureInPicture="true"
    android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation">
</activity>

<!-- Remove Google Cast metadata -->
<meta-data
    android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
    android:value="com.bitmovin.player.reactnative.extensions.cast.CastOptionsProvider"/>

Android - Build Files

Remove from android/build.gradle:

allprojects {
    repositories {
        // Remove Bitmovin repository
        maven { url 'https://artifacts.bitmovin.com/artifactory/public-releases' }
    }
}

Remove from android/app/build.gradle:

dependencies {
    // Remove Google Cast (now handled by plugin)
    implementation 'com.google.android.gms:play-services-cast-framework:21.x.x'
    
    // Remove IMA SDK (now handled by plugin)
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.x.x'
}

Step 3: Configure via app.config.ts

Create or update your app.config.ts (or app.json for JSON configuration) to use the Expo plugin:

import { ExpoConfig } from 'expo/config';

const config: ExpoConfig = {
  // ... your existing config
  plugins: [
    [
      'bitmovin-player-react-native',
      {
        // Required: Your Bitmovin Player license key
        playerLicenseKey: 'YOUR_PLAYER_LICENSE_KEY',
        
        // Optional: Enable features as needed
        features: {
          // Enable AirPlay support (iOS only)
          airPlay: true,

          // Enable background playback
          backgroundPlayback: true,

          googleCastSDK: {
            android: '21.3.0',
            ios: {
              version: '4.8.1.2'
              appId: 'YOUR_CAST_APP_ID'  // optional, will use default receiver app if not provided
              localNetworkUsageDescription: 'CUSTOM NETWORK USAGE DESCRIPTION' // optional, will use default description if not provided
            }
          }
          
          // Enable offline playback
          offline: true,
          
          // Enable Picture-in-Picture
          pictureInPicture: true,
        },
      },
    ],
  ],
};

export default config;

For more details on configuring your license key, see the Configuring Your License guide.

Step 4: Rebuild Your App

After updating your configuration, rebuild your native projects:

# Clean and regenerate native projects
npx expo prebuild --clean

# Build and run your app
npx expo run:ios
# or
npx expo run:android

The prebuild command regenerates your native project folders with all the necessary configurations applied automatically.

Platform-Specific Notes

Android - Google Cast

Even with the Expo plugin, you still need to call BitmovinCastManager.updateContext() in your code when using Google Cast:

import { BitmovinCastManager } from 'bitmovin-player-react-native';

// Call this when your app initializes
BitmovinCastManager.updateContext();

iOS - Picture-in-Picture

For Picture-in-Picture on iOS, you still need to set the audio category:

import { AudioSession } from 'bitmovin-player-react-native';

// Call this before playing content
await AudioSession.setCategory('playback');

Troubleshooting

Build Errors After Migration

If you encounter build errors after migration:

  1. Ensure you've removed all manual native configurations
  2. Run npx expo prebuild --clean to regenerate native projects

Feature Not Working

If a feature that worked before isn't working after migration:

  1. Check that you've enabled the feature in app.config.ts
  2. Verify the feature name is correct (e.g., airPlay not airplay)
  3. Ensure you've rebuilt the app after changing the configuration via npx expo prebuild --clean

Next Steps

After successfully migrating to v1.0.0, you can:

  • Remove manual native code maintenance from your workflow
  • Configure all features through app.config.ts
  • Take advantage of automatic configuration updates

For specific feature configuration with the new Expo plugin, see:

Updated about 16 hours ago