This page covers how to install the Instabug SDK into your iOS application. Whether you are using Objective-C or Swift, you can follow the steps below.


Below are the ways you can use to add Instabug to your project so you can start squashing bugs.


To integrate Instabug into your Xcode project using Cocoapods, add it to your Podfile.

pod 'Instabug'

Then, run the following command.

pod install

CocoaPods will download and install the SDK and add all the required dependencies into your Xcode project.

Pod Update

Since CocoaPods might not always download the latest version of the SDK when using pod install, it's recommended that you also run pod update Instabug after the installation has completed or whenever you would like to update Instabug.


To integrate Instabug into your Xcode project using Carthage, add it to your Cartfile.

binary ""

Then, run the following command.

carthage update

Then drag Instabug.framework into your Xcode project.


Before Updating

If you are updating from SDK version < 7.3.x, please make sure to re-check the manual integration steps below as they have been changed starting from 7.4.x.

  1. Download Instabug SDK.
  2. Extract it then drag & drop Instabug.framework to your project's Embedded Binaries section under the "General" tab, and make sure that the "Copy items if needed" checkbox is checked.
  3. Create a new "Run Script Phase" in your project’s target "Build Phases" and add the following snippet.
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/Instabug.framework/"
  1. Make sure that the "Run script only when installing" is checked.
  1. To symbolicate Instabug's frames in your crash reports, follow the steps below (SDK version >= 7.3.12):
  • Add Instabug's DSYMs and bcSymbolMap files to your project directory. You will find them within Instabug's folder. Please, sure to uncheck the app target while copying the files.
  • Add the script below to your post-actions Build.
SCRIPT_SRC=$(find "$PROJECT_DIR" -name '' | head -1)
if [ ! "${SCRIPT_SRC}" ]; then
echo "Instabug: err: script not found. Make sure that you're including Instabug.bundle in your project directory"
exit 0
source "${SCRIPT_SRC}"
#--- SCRIPT END ---

If you're using Xcode 10, you will need to add the previous script to the Build Post-actions.

Using Instabug

Instabug doesn't use any private APIs and is absolutely safe to be included in your App Store builds, however, if you'd like to only include it in beta builds, that can be done in 2 different ways, depending on how you create your builds.

Including Instabug in App Store Builds

Different Builds for Beta and Production

If you create the builds you distribute to your beta tester using a different build configuration from the ones you submit to the App Store, then you can only initialize Instabug if you're building using that profile. You can setup multiple invocation events to invoke Instabug with.
The code below only enables Instabug for the DEBUG build profile.

#ifdef DEBUG
[Instabug startWithToken:@"YOUR-TOKEN-HERE" invocationEvents: IBGInvocationEventShake | IBGInvocationEventScreenshot]
Instabug.start(withToken: "YOUR-TOKEN-HERE", invocationEvents: [.shake, .screenshot])

Same Build for Beta and App Store

The following method returns YES in case the app is running live from the AppStore and NO if it is running from the simulator, Xcode, Fabric Beta or TestFlight.

- (BOOL) isRunningLive {
         return NO;
        BOOL isRunningTestFlightBeta = [[[[NSBundle mainBundle] appStoreReceiptURL] lastPathComponent] isEqualToString:@"sandboxReceipt"];
        BOOL hasEmbeddedMobileProvision = !![[NSBundle mainBundle] pathForResource:@"embedded" ofType:@"mobileprovision"];
        if (isRunningTestFlightBeta || hasEmbeddedMobileProvision)
            return NO;
       return YES;

if ([self isRunningLive])
   [Instabug startWithToken:@"YOUR-LIVE-TOKEN-HERE" invocationEvents: IBGInvocationEventShake | IBGInvocationEventScreenshot]

    [Instabug startWithToken:@"YOUR-BETA-TOKEN-HERE" invocationEvents: IBGInvocationEventShake | IBGInvocationEventScreenshot]
func isRunningLive() -> BOOL {
		return false
    let isRunningTestFlightBeta  = (Bundle.main.appStoreReceiptURL?.lastPathComponent == "sandboxReceipt")
    let hasEmbeddedMobileProvision = !Bundle.main.path(forResource: "embedded", ofType: "mobileprovision");
    if (isRunningTestFlightBeta || hasEmbeddedMobileProvision) {
      return false
    } else {
      return true

if (self.isRunningLive()) {
Instabug.start(withToken: "YOUR-LIVE-TOKEN-HERE", invocationEvents: [.shake, .screenshot])
} else {
Instabug.start(withToken: "YOUR-BETA-TOKEN-HERE", invocationEvents: [.shake, .screenshot])


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

Microphone and Photo Library Usage Description

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

For your app not to be rejected, you’ll need to add the following 2 keys to your app’s info.plist file with text explaining to the user why those permissions are needed:

  • NSMicrophoneUsageDescription
  • NSPhotoLibraryUsageDescription

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

  • "<app name> needs access to the microphone to be able to attach voice notes."
  • "<app name> needs access to your photo library for you to be able to 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.