This document will guide you through the process of adding AppSpector SDK to your project and tailoring it to your needs. Its simplified but sufficient for a quick setup version can be found in "Setup Guide" section on your project page on our website.

GitHub releaseGitHub release

Installation

To start using AppSpector SDK, visit our site and add a new app (https://app.appspector.com).
It will generate a unique API key for your debug sessions. Navigate to app settings and copy it.

You can add AppSpector SDK to your project manually or via CocoaPods/Carthage

Manually

Download AppSpectorSDK.zip, extract it and drop AppSpectorSDK.framework into your Xcode project.
Then navigate to your project settings, switch to “General” tab and add AppSpectorSDK framework to “Embedded Binaries” section.

If you plan either to submit builds with AppSpector SDK to the Apple TestFlight for testing or archive them for AdHoc distribution, you'll have to perform one more step: select your target in Xcode,
create a new “Run Script Phase” in “Build Phases” section and paste the following script:

file="AppSpectorSDK.framework/AppSpectorSDK"
archs="$(lipo -info "${file}" | rev | cut -d ':' -f1 | rev)"
stripped=""
for arch in $archs; do
    if ! [[ "${VALID_ARCHS}" == *"$arch"* ]]; then
        lipo -remove "$arch" -output "$file" "$file" || exit 1
        stripped="$stripped $arch"
    fi
done
echo "AppSPector: stripped archs: $stripped"

This script is required as a workaround for this Apple AppStore bug

CocoaPods

To use cocoapods, add this line to your podfile and run pod install:

pod 'AppSpectorSDK'

Carthage

  • Install Carthage
  • Add github “appspector/ios-sdk” to your Cartfile
  • Run carthage update
  • Drag AppSpectorSDK.framework from the appropriate platform directory in Carthage/Build/ to the “Linked Frameworks and Libraries” section in “General” settings of your Xcode project.

Join our slack to discuss setup process and features

Configuration

AppSpector uses modules called monitors to track different app activities and gather stats.
We provide a bunch of monitors out of the box which could be used all together or in any combinations.

To start AppSpector debug session, you need to build an instance of AppSpectorConfig and provide your API key.
You can start specific monitors this way:

NSSet *monitorIDs = [NSSet setWithObjects:AS_HTTP_MONITOR, AS_LOG_MONITOR, nil];
AppSpectorConfig *config = [AppSpectorConfig configWithAPIKey:@"API_KEY" monitorIDs:monitorIDs];
[AppSpector runWithConfig:config];
let config = AppSpectorConfig(apiKey: "API_KEY", monitorIDs: [Monitor.http, Monitor.logs])
AppSpector.run(with: config)

Or start all available ones:

AppSpectorConfig *config = [AppSpectorConfig configWithAPIKey:@"API_KEY"];
[AppSpector runWithConfig:config];
let config = AppSpectorConfig(apiKey: "API_KEY")
AppSpector.run(with: config)

Available monitors:

AS_PERFORMANCE_MONITOR
AS_HTTP_MONITOR
AS_SQLITE_MONITOR
AS_SCREENSHOT_MONITOR
AS_LOG_MONITOR
AS_LOCATION_MONITOR
AS_ENVIRONMENT_MONITOR
AS_ANALYTICS_MONITOR
AS_COREDATA_MONITOR
AS_NOTIFICATION_MONITOR
Monitor.performance
Monitor.http
Monitor.sqlite
Monitor.screenshot
Monitor.logs
Monitor.location
Monitor.environment
Monitor.analytics
Monitor.coredata
Monitor.notifications

Starting with selected monitors only:

NSSet *monitorIDs = [NSSet setWithObjects:AS_HTTP_MONITOR, AS_LOG_MONITOR, nil];
AppSpectorConfig *config = [AppSpectorConfig configWithAPIKey:@"API_KEY" monitorIDs:monitorIDs];
[AppSpector runWithConfig:config];
let config = AppSpectorConfig(apiKey: "API_KEY", monitorIDs: [AS_HTTP_MONITOR, AS_LOG_MONITOR])
AppSpector.run(with: config)

Or with all of them at once:

AppSpectorConfig *config = [AppSpectorConfig configWithAPIKey:@"API_KEY"];
[AppSpector runWithConfig:config];
let config = AppSpectorConfig(apiKey: "API_KEY")
AppSpector.run(with: config)

Start/Stop SDK

AppSpector start is a two-step process.
When you link with AppSpector framework, it starts collecting data immediately after load. When you call startWithConfig method, AppSpector opens a connection to the backend. Now you can see your session on the frontend.

You can manually control AppSpector state by calling start and stop methods.
stop tells AppSpector to disable all data collection and close current session.
start starts it again using config you provided at load. This will create a new session, all activity between stop and start calls will not be tracked.

[AppSpector stop];
[AppSpector start];
AppSpector.stop()
AppSpector.start()

Custom device name

You can assign a custom name to your device to easily find needed sessions in the sessions list. To do this you have to add the desired name as a value for AS_DEVICE_NAME_KEY key to the config.metadata dictionary:

AppSpectorConfig *config = [AppSpectorConfig configWithAPIKey:@"API_KEY" monitorIDs:monitorIDs];
config.metadata = @{ AS_DEVICE_NAME_KEY : @"Your device name" };
let config = AppSpectorConfig(apiKey: "API_KEY", monitorIDs: [Monitor.http, Monitor.logs])
config.metadata = [ MetadataKey.DeviceNameKey : "Your device name" ]

Getting session URL

Sometimes you may need to get URL pointing to current session from code. Say you want link crash in your crash reporter with it, write it to logs or display in your debug UI. To get this URL you have to add a session start callback:

AppSpectorConfig *config = [AppSpectorConfig configWithAPIKey:@"API_KEY"];
[config setStartCallback:^(NSURL *sessionURL) {
    // Save url for future use...
}];
[AppSpector runWithConfig:config];
let config = AppSpectorConfig(apiKey: "API_KEY")
config.startCallback = { url in print("Session url: \(url)") }
AppSpector.run(with: config)

Some hints:

  • Callback get called on a non-main thread and not guaranteed to be called on a caller thread so be careful with not thread-safe APIs inside it
  • Callback will be called again upon restart, either when you call stop/start methods or when the ​session was dropped due to networking issues

Feedback

Let us know what you think or what improvements you would like to see: [email protected].