AppAmbit iOS SDK

Track. Debug. Distribute. AppAmbit: track, debug, and distribute your apps from one dashboard.

Lightweight SDK for analytics, events, logging, crashes, and offline support. Simple setup, minimal overhead.

Full product docs live here: docs.appambit.com

• Features
• Requirements
• Install
• Quickstart
• Usage
• Cloud Code
• Release Distribution
• Privacy and Data
• Troubleshooting
• Contributing
• Versioning
• Security
• License

• Session analytics with automatic lifecycle tracking
• Ambit Trail records detailed navigation for debugging
• Event tracking with custom properties
• Remote Config – dynamic configuration values fetched and applied at runtime
• Error logging for quick diagnostics
• Crash capture with stack traces and threads
• Offline support with batching, retry, and queue
• Database – query, insert, update and delete remote data with a fluent builder
• Cloud Code – invoke authenticated HTTP functions with JSON, typed results, cancellation, and request correlation
• Create mutliple app profiles for staging and production
• Small footprint, modern Swift API with full Objective-C support

• iOS 12.0 or newer
• Xcode 16 or newer
• Swift 6.0 or newer

Requires v1.2.0 or newer. Earlier tags do not include Cloud Code support.

1. Go to File → Add Package Dependencies…

2. Paste the repository URL into the search field:

   https://github.com/AppAmbit/appambit-sdk-ios
   

3. Set Dependency Rule to Up to Next Major Version starting at v1.2.0.

4. Click Add Package, then attach each product to the target that needs it:

Add the package repository once, then link products to the target that uses them:

Adding the package does not automatically link every product to every target. In Xcode, select the target and add its product under General > Frameworks, Libraries, and Embedded Content. You can also verify the product under Build Phases > Link Binary With Libraries.

Do not link AppAmbitPushNotificationsExtension to the main app, and do not link AppAmbitPushNotifications to the extension. The full push product uses app-only APIs such as UIApplication; the extension product is the app-extension-safe implementation.

If you only need push notifications, stop after configuring the main app. Create an NSE only when you need to modify or process a notification before display.

See the Push Notifications guide for the complete setup, including SwiftUI, UIKit, CocoaPods, Objective-C, and NSE troubleshooting.

dependencies: [
    .package(url: "https://github.com/AppAmbit/appambit-sdk-ios", from: "1.2.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "AppAmbit", package: "appambit-sdk-ios")
        ]
    )
]

Add this to your Podfile:

pod 'AppAmbitSdk'
# or specify version
pod 'AppAmbitSdk', '~> 1.2.0'

Then run:

pod install

Open the generated .xcworkspace project.

(If you get an error like “Unable to find a specification for AppAmbitSdk”: run pod repo update, then pod install.)

Configure the SDK at app launch with your API Key.

// AppDelegate
AppAmbit.start(appKey: "<YOUR-APPKEY>")

// AppDelegate
[AppAmbit startWithAppKey:@"<YOUR-APPKEY>"];

• Session activity – automatically tracks user session starts, stops, and durations

• Ambit Trail – records detailed navigation of user and system actions leading up to an issue for easier debugging

• Track events – send structured events with custom properties

  Swift

    Analytics.trackEvent(eventTitle: "Test TrackEvent", data: ["test1":"test1"])

  Objective-C

    [Analytics trackEventWithEventTitle:@"Test TrackEvent" data:@{ @"test1": @"test1" } createdAt:nil completion:nil];
  

• Logs: add structured log messages for debugging

  Swift

    let properties: [String: String] = ["user_id": "1"]
    let message = "Error NullPointerException"
    Crashes.logError(message: message, properties: properties, exception: error)

  Objective-C

    [props setObject:@"123" forKey:@"userId"];
    NSDictionary *userInfo = @{ NSLocalizedDescriptionKey: exception.reason };
    NSError *error = [NSError errorWithDomain:exception.name code:0 userInfo:userInfo];
    [Crashes logErrorWithMessage:(@"Error ArrayIndex") properties:props classFqn:nil exception:nil fileName:nil lineNumber:0 createdAt:nil completion:nil];
  

• Crash Reporting: uncaught crashes are automatically captured and uploaded on next launch

• Breadcrumbs: automatic screen-change breadcrumbs (push/pop, present/dismiss). To display the intended screen name, set a navigation title (navigationTitle in SwiftUI / title in UIKit/Objective-C). Without a title, it will appear in the dashboard using the default view/controller name.

  Swift

    NavigationStack {
      MyMview()
        .navigationTitle("MyMview")
    }

  Objective-C

    UIViewController *vc = [UIViewController new];
    vc.title = @"MyMview";
    [self.navigationController pushViewController:vc animated:YES];
  

• Remote Config: fetch and apply remote configuration values asynchronously using type-safe methods (getString, getBoolean, getLong, getDouble).

  Swift

  // Enable remote config
  RemoteConfig.enable()

  // Get remote config values with type-safe methods
  let message = RemoteConfig.getString("data")
  let isFeatureEnabled = RemoteConfig.getBoolean("banner")
  let discount = RemoteConfig.getLong("discount")
  let maxUpload = RemoteConfig.getDouble("max_upload")

  Objective-C

  // Enable remote config
  [RemoteConfig enable];

  // Get remote config values with type-safe methods
  NSString *message = [RemoteConfig getString:@"data"];
  BOOL isFeatureEnabled = [RemoteConfig getBoolean:@"banner"];
  NSInteger discount = [RemoteConfig getLong:@"discount"];
  double maxUpload = [RemoteConfig getDouble:@"max_upload"];

• Database: query, insert, update and delete rows in your AppAmbit database with a fluent builder.

  Swift

  // Query rows
  AppAmbitDb.from("users")
    .where("status", value: "active")
    .orderByDesc("created_at")
    .limit(10)
    .get { rows, error in
      print(rows ?? [], error ?? "")
    }
  
  // Insert a row
  AppAmbitDb.from("users")
    .insert(["name": "Jane", "status": "active"]) { result, error in
      print(result ?? "", error ?? "")
    }
  
  // Update requires at least one where()
  AppAmbitDb.from("users")
    .where("id", value: 1)
    .update(["status": "inactive"]) { result, error in
      print(result ?? "", error ?? "")
    }

  Objective-C

  [[AppAmbitDb from:@"users"]
    where:@"status" value:@"active"];
  
  [[[AppAmbitDb from:@"users"] where:@"status" value:@"active"]
    getWithCompletion:^(NSArray<NSDictionary<NSString *, id> *> * _Nullable rows, NSError * _Nullable error) {
      NSLog(@"%@ %@", rows, error);
    }];

Cloud Code lets your app invoke authenticated HTTP functions hosted by AppAmbit. Initialize the SDK as usual; Cloud Code uses the same consumer and Bearer token as the rest of the SDK.

AppAmbit.start(appKey: "<YOUR-APPKEY>")

After configuring an active Cloud Function with an enabled HTTP trigger and slug in the Dashboard, call it from Swift or Objective-C:

CloudCode.call("hello", body: ["name": "Ada"]
) { response, error in
    print(response?.data ?? error ?? "Unknown result")
}

[CloudCode call:@"hello"
           method:CloudCodeHttpMethodPost
            query:nil
             body:@{ @"name": @"Ada" }
          headers:nil
      completion:^(CloudCodeResponse *response, NSError *error) {
    if (error != nil) {
        NSLog(@"Cloud Code error: %@", error);
        return;
    }
    NSLog(@"%@", response.data);
}];

See the complete Cloud Code mobile guide for function setup, HTTP triggers, typed and dynamic responses, errors, request IDs, cancellation, timeouts, and backend examples.

For the dynamic response API, a successful empty body, a 204 No Content response, and an explicit JSON null are represented as NSNull() in CloudCodeResponse.data. Android exposes the equivalent value as null. Typed responses preserve their status and request metadata; an empty successful body produces nil typed data.

• Push the artifact to your AppAmbit dashboard for distribution via email and direct installation.

• The SDK batches and transmits data efficiently
• You control what is sent — avoid secrets or sensitive PII
• Supports compliance with Apple platform policies

For details, see the docs: docs.appambit.com

• No data in dashboard → check API key, endpoint, and network access
• CocoaPods errors → run pod repo update, then pod install
• SPM not resolving → confirm repo URL and tagged release version
• Crash not appearing → crashes are sent on next launch

We welcome issues and pull requests.

• Fork the repo
• Create a feature branch
• Add tests where applicable
• Open a PR with a clear summary

Please follow Swift API design guidelines and document public APIs.

Semantic Versioning (MAJOR.MINOR.PATCH) is used.

• Breaking changes → major
• New features → minor
• Fixes → patch

If you find a security issue, please contact us at hello@appambit.com rather than opening a public issue.

Open source under the terms described in the LICENSE file.

• Docs: docs.appambit.com
• Dashboard: appambit.com
• Discord: discord.gg
• Examples: Sample Swift test app AppAmbit.App.Swift and Objective-C test app AppAmbit.App.ObjC are included in this repo.