Installation

If you are upgrading, check our Upgrade Guide before bumping up to a new major version.

Through React-Native

1. Open the command line and navigate to your React Native Directory. Then, run the following command.

npm install instabug-reactnative

If you prefer using Yarn, you can use the following command instead.

yarn add instabug-reactnative

2a. If your React Native version is below 0.60, link the bridging files in the npm package to your iOS project use the following command. Make sure you have Ruby installed before running this last command (you can skip installing Ruby if you're building an Android app only).

react-native link instabug-reactnative

2b. If your React Native version is above 0.60,the library will be linked automatically. However, you'll also need to run the command below:

react-native add-instabug

3. If your React Native version is above 0.60, you'll need to locate your iOS directory and run the following command:

pod install

Upgrading from 2.0.x and from 8.0.3

When upgrading from 2.0.x to 2.1.x or from 8.0.3 to 8.x, please follow these steps:

1. Unlink the project before upgrading to the new version.

react-native unlink instabug-reactnative

2. Install the new version by running the following command.

npm install instabug-reactnative

3. Link the project by running the following command.

react-native link instabug-reactnative

Through CocoaPods

🚧

iOS Only

This method will only install Instabug for iOS.

1. In the terminal, navigate to your React Native directory and install the instabug-reactnative package.

npm install instabug-reactnative

2. Add the following to your Podfile.

pod 'instabug-reactnative', :path => '../node_modules/instabug-reactnative'
pod 'React', :path => '../node_modules/react-native', :subspecs => [
'Core',
'CxxBridge',
'DevSupport'
]
pod 'yoga', :path => '../node_modules/react-native/ReactCommon/yoga'
pod 'DoubleConversion', :podspec => '../node_modules/react-native/third-party-podspecs/DoubleConversion.podspec'
pod 'glog', :podspec => '../node_modules/react-native/third-party-podspecs/GLog.podspec'
pod 'Folly', :podspec => '../node_modules/react-native/third-party-podspecs/Folly.podspec'

3. Add the following post install script at the end of your Podfile.

post_install do |installer|
   installer.pods_project.targets.each do |target|
      if target.name == "React"
         target.remove_from_project
      end
   end
end

4. Install Instabug through CocoaPods.

pod install

Manual Linking

You can follow the steps here if you would like to integrate the SDK using manual linking.

Android

🚧

Compile SDK Version

Please note that the compileSDKVersion should be v29, otherwise you may run into build errors.

1. Append the following lines to android/settings.gradle.

include ':instabug-reactnative'
project(':instabug-reactnative').projectDir = new File(rootProject.projectDir, '../node_modules/instabug-reactnative/android')

2. Add the following line to your module level dependencies in android/app/build.gradle.

implementation project(':instabug-reactnative')

3. Initialize the SDK in android/app/src/main/java/[...]/MainApplication.java by adding the following lines to your getPackages method while adding your application token.

@Override
protected List<ReactPackage> getPackages() {
	return Arrays.<ReactPackage>asList(
	new MainReactPackage(),
	new RNInstabugReactnativePackage.Builder("YOUR_APP_TOKEN", MainApplication.this)
                            .setInvocationEvent("shake", "button", "screenshot")
                            .setPrimaryColor("#1D82DC")
                            .setFloatingEdge("left")
                            .setFloatingButtonOffsetFromTop(250)
                            .build()
}

iOS

1. In your project navigator in XCode, right click on Libraries → Add Files to [your project name]. Navigate to your project node_modules → instabug-reactnative → ios and add RNInstabug.xcodeproj.
2. In your project navigator in XCode, select General and add libRNInstabug.a to your Linked Frameworks and Libraries.
3. In your project navigator in XCode, select Build Settings and add $(SRCROOT)/../node_modules/instabug-reactnative/ios to your Header Search Paths.
4. In your project navigator in XCode, select Build Settings and add ../node_modules/instabug-reactnative/ios to your Framework Search Paths.
5. In your project navigator in XCode, select General → add Embedded Binaries → Add Other → navigate to node_modules/instabug-reactnative/ios → add Instabug.framework.
6. For release: In your project navigator in XCode, select Build Phases → add New Run Script Phase → rename to run script phase to Strip Frameworks → add the following lines to your script.

bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Instabug.framework/strip-frameworks.sh"

Using Instabug

1. To start using Instabug, import it into your index.ios.js and index.android.js file.

import Instabug, { BugReporting, Surveys, FeatureRequests } from 'instabug-reactnative';

2. Then initialize it in the constructor or componentWillMount. This line will let the Instabug SDK work with the default behavior. The SDK will be shown when the device is shaken. You can customize this behavior through APIs (you can skip this step if you are building an Android app only).

Instabug.startWithToken('IOS_APP_TOKEN', [Instabug.invocationEvent.shake]);

3a. If your React Native version is below 0.60, open android/app/src/main/java/[...]/MainApplication.java, locate the getPackages method, and add your Android app token. You can skip this step if you are building an iOS app only.

@Override
protected List<ReactPackage> getPackages() {
	return Arrays.<ReactPackage>asList(
	new MainReactPackage(),
	new RNInstabugReactnativePackage.Builder("TOKEN",MainApplication.this)
							.setInvocationEvent("shake", "button", "screenshot")
							.setPrimaryColor("#1D82DC")
							.setFloatingEdge("left")
							.setFloatingButtonOffsetFromTop(250)
							.build()
}

3b. If your React Native version is above 0.60, add the integration code in step 3a to the onCreate() method instead. You can skip this step if you are building an iOS app only.

@Override
   public void onCreate() {
     new RNInstabugReactnativePackage
             .Builder("APP_TOKEN", MainApplication.this)
             .setInvocationEvent("shake")
             .setPrimaryColor("#1D82DC")
             .setFloatingEdge("left")
             .setFloatingButtonOffsetFromTop(250)
             .build();
     super.onCreate();
     SoLoader.init(this, /* native exopackage */ false);
   }

You can find your app token by selecting SDK Integration in the Settings menu from your Instabug dashboard.

Same Build for Beta and App Store

The following method handles both cases: when your app is running live from the App Store and if it is running from your simulator, Xcode, Fabric Beta, or Test Flight.

Instabug.isRunningLive(function (isLive) {
  if (isLive) {
    Instabug.startWithToken('LIVE_TOKEN', [Instabug.invocationEvent.none]);
  } else {
    Instabug.startWithToken('BETA_TOKEN', [Instabug.invocationEvent.screenshot]);
  }
});

Managing Permissions

Instabug needs access to the device microphone and photo library to be able to let users add audio, image, and video attachments. Starting from iOS 10, apps that don’t provide a usage description for those two permissions will be rejected when submitted to the App Store.

To prevent your app from being rejected, you’ll need to add the following two keys to your app’s info.plist file with text that explains to your app users why those permissions are needed:

• NSMicrophoneUsageDescription
• NSPhotoLibraryUsageDescription

If your app doesn’t already access the microphone or photo library, we recommend usage descriptions like:

• " needs access to your microphone so you can attach voice notes."
• " needs access to your photo library so you can attach images."

The permission alert for accessing the microphone/photo library will NOT appear unless users attempt to attach a voice note/photo while using Instabug.

🚧

Permissions Are Required

The above permissions are required in order for you to receive attachments from your users through the Instabug SDK.