Welcome to Instabug's Documentation!
Here you'll find a comprehensive technical guide
to help you start working with the Instabug SDK efficiently.

Get Started

Integrating Instabug

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

Installation

There are three possible ways to integrate Instabug, either using CocoaPods, Carthage, or manually.

CocoaPods

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 to your Xcode project.

Pod Update

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

Carthage

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

binary "https://raw.githubusercontent.com/Instabug/Instabug-iOS/master/Instabug.json"

Then, run the following command.

carthage update

Finally, drag Instabug.framework into your Xcode project.

Manually

  1. Download the Instabug SDK.
  2. Extract it, then drag and 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/strip-frameworks.sh"
  1. Make sure that 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).
  1. Add Instabug's DSYMs and bcSymbolMap files to your project directory. You will find them within the Instabug folder. Please be sure to uncheck the app target while copying the files.

  2. Add the script below to your Archive > Post-actions.

#--- SCRIPT BEGIN ---
SCRIPT_SRC=$(find "$PROJECT_DIR" -name 'Inject_DSYM_Project-Archive.sh' | 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
fi
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

It is absolutely safe to include Instabug in your App Store builds as it doesn't use any private APIs. If you'd like to only include it in beta builds, that can be done two ways depending on how you create your builds, either by having separate builds or the same build for Beta and Production.

Separate Beta and Production Builds

Use this method if you create your development builds for beta testers using a different build configuration than the production builds that you submit to the App Store. You can only initialize Instabug using the profile that you use for your beta builds. To show Instabug, you can set up multiple invocation events.

The code below only enables Instabug for the DEBUG build profile.

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

Same Beta and Production Build

Use this method if you create your beta and production builds using the same configuration.

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

func isRunningLive() -> Bool {
     #if targetEnvironment(simulator)
    return false
    #else
    let isRunningTestFlightBeta  = (Bundle.main.appStoreReceiptURL?.lastPathComponent == "sandboxReceipt")
    let hasEmbeddedMobileProvision = Bundle.main.path(forResource: "embedded", ofType: "mobileprovision") != nil
    if (isRunningTestFlightBeta || hasEmbeddedMobileProvision) {
        return false
    } else {
        return true
    }
    #endif
}

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

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

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

else
    [Instabug startWithToken:@"YOUR-BETA-TOKEN-HERE" invocationEvents: IBGInvocationEventShake | IBGInvocationEventScreenshot]

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

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:

  • "<App Name> needs access to your microphone so you can attach voice notes."
  • "<App Name> 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.


What's Next

Now that you've successfully integrated Instabug, check out how to invoke Instabug using different methods, how to identify your users, or how to customize your SDK.

Invoking Instabug
User Identification
SDK Customizations

Integrating Instabug


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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.