Getting Started with AppAmbit SDK

This guide walks you through setting up the AppAmbit SDK in your application, focusing on AppAmbit Analytics and Crash Reporting.

The package you install here also covers CMS content, the Database, and Remote Config, so none of this setup has to be redone when you start using them. Push Notifications add one package and a short setup, covered in their own guide.

SDK Resources

Our SDKs are fully open source on GitHub:

Prerequisites

Before getting started, ensure you meet the following requirements:

.NET MAUIiOSAndroidFlutterReact NativeDOTNETAvalonia

Language: C#

Supported Platforms: iOS, Android, Windows, macOS

Minimum Requirements:

iOS 11.0+
Android 5.0 (API level 21)+
Windows 10+
macOS 10.13+

Note

Xamarin is currently not supported by the AppAmbit library.

Windows Considerations

When developing for Windows, ensure you initialize the SDK in the OnStartup method.

iOS/macOS Considerations

Remember to configure Info.plist with the required NSAppTransportSecurity exceptions.

Android Considerations

Don't forget to add the required permissions to AndroidManifest.xml.

Language: Swift, Objective-C

Minimum iOS Version: 12.0+

Minimum Xcode Version: 13.0+

Package Manager: Swift Package Manager, CocoaPods

The iOS project is set up in Xcode 13 or later.
You are targeting devices running iOS 12.0 or later.
You are not using any other libraries that offer crash reporting functionality.
If you are using CocoaPods to integrate AppAmbit, you need CocoaPods version 1.10 or later.

CocoaPods Setup

Make sure you have CocoaPods 1.10 or later installed.

App Transport Security

Remember to configure Info.plist with NSAppTransportSecurity exceptions for AppAmbit.com.

Breadcrumbs

AppAmbit automatically tracks screen navigation. Set navigationTitle in SwiftUI or title property in UIKit for proper screen names.

Crash Reporting

Ensure you're not using other crash reporting libraries that might conflict with AppAmbit.

Language: Kotlin, Java

Minimum Android Version: 5.0 (API level 21)

Build System: Gradle

Package Repository: Maven Central

Your project is configured in Android Studio
The target devices run Android 5.0 (API level 21) or higher.
You are not using another SDK for crash reporting.

Gradle Configuration

Add the AppAmbit dependency to your app-level build.gradle file and sync your project.

Required Permissions

Don't forget to add these permissions to AndroidManifest.xml:

ACCESS_NETWORK_STATE
INTERNET

Initialization

Initialize AppAmbit in the onCreate method of your main Activity.

ProGuard/R8

If you're using code obfuscation, make sure to add the appropriate ProGuard rules (if needed).

Language: Dart

Supported Platforms: iOS, Android

Package Repository: pub.dev

Minimum Requirements:

iOS 11.0+
Android 5.0 (API level 21)+
Flutter SDK installed
Dart SDK compatible version

Installation

Add the package to your pubspec.yaml and run flutter pub get.

Initialization

Initialize AppAmbit in your main() function before calling runApp().

Platform Channels

The SDK uses platform channels to communicate with native iOS and Android code.

Language: JavaScript, TypeScript

Supported Platforms: iOS, Android

Package Manager: npm, yarn

Minimum Requirements:

iOS 11.0+
Android 5.0 (API level 21)+
React Native environment set up

Installation

Install via npm or yarn and link the native modules.

TypeScript Support

The SDK includes TypeScript type definitions out of the box.

Native Modules

The SDK uses native modules to access iOS and Android functionality.

Language: C#

Supported Platforms: Windows (WPF & WinUI)

Minimum Requirements:

Windows 10+

Windows Considerations

When developing for Windows, ensure you initialize the SDK in the OnStartup method.

Language: C#

Supported Platforms: iOS, Android, Windows, macOS

Minimum Requirements:

iOS 11.0+
Android 5.0 (API level 21)+
Windows 10+
macOS 10.13+

Note

Xamarin is currently not supported by the AppAmbit library.

Windows Considerations

When developing for Windows, ensure you initialize the SDK in the OnStartup method.

iOS/macOS Considerations

Remember to configure Info.plist with the required NSAppTransportSecurity exceptions.

Android Considerations

Don't forget to add the required permissions to AndroidManifest.xml.

Creating Your App in the AppAmbit Portal

Visit AppAmbit.com.
Sign in or create an account. Navigate to "Apps" and click on "New App".
Provide a name for your app. Optionally, upload an image via drag-and-drop.
Select the appropriate release type and target OS.
Click "Create" to generate your app.
Retrieve the App Key from the app Info page.
Use this App Key when initializing the SDK.

Adding the SDK to Your Project

.NET MAUIiOSAndroidFlutterReact NativeDOTNETAvalonia

Get the SDK on NuGet (recommended)

Add the package to your MAUI project:

dotnet add package com.AppAmbit.Maui
# or specify version
dotnet add package com.AppAmbit.Maui --version 4.1.1

Or, using Visual Studio:

Right-click your project → Manage NuGet Packages…
Search for AppAmbit and install the latest stable version.

Swift Package Manager

In Xcode, go to File → Add Package Dependencies… and paste the repository URL:

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

Set Dependency Rule to Up to Next Major Version starting at v1.1.1, then add the products to their corresponding targets:

Product	Target	Import
`AppAmbit` — core SDK	Main app target	`import AppAmbit`
`AppAmbitPushNotifications` — push notifications	Main app target	`import AppAmbitPushNotifications`
`AppAmbitPushNotificationsExtension` — Notification Service Extension (NSE)	NSE target	`import AppAmbitPushNotificationsExtension`

Add AppAmbit to the main app target. Add AppAmbitPushNotifications only if your app uses push notifications. If you use a Notification Service Extension, create the NSE target first through File → New → Target → Notification Service Extension, then add AppAmbitPushNotificationsExtension to the NSE target. Do not add the NSE product to the main app target.

Note

Swift Package Manager requires v1.1.1 or later. Earlier tags do not ship a package manifest and cannot be resolved.

If you are declaring the dependency in a Package.swift instead, add the core and push products to the app target:

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

For a Notification Service Extension target, add the extension-safe product instead:

.target(
    name: "NotificationService",
    dependencies: [
        .product(name: "AppAmbitPushNotificationsExtension", package: "appambit-sdk-ios")
    ]
)

CocoaPods

Get the SDK on CocoaPods

Add this to your Podfile:

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

Then run:

pod install

Warning

If you see an error like [!] Unable to find a specification for AppAmbitSdk when running pod install, run pod repo update to get the latest pods from the CocoaPods repository, and then run pod install.

Get the SDK on Maven Central (recommended)

Open the build.gradle file at the project application level (app/build.gradle):

Kotlin DSL

dependencies {
    implementation("com.appambit:appambit:1.1.0")
    ...
}

Groovy

dependencies {
    implementation 'com.appambit:appambit:1.1.0'
    ...
}

Note

Make sure to run a Gradle synchronization in Android Studio.

Add the dependency to your pubspec.yaml:

dependencies:
  appambit_sdk: ^1.1.0

Then run:

flutter pub get

Install via npm:

npm install appambit
# or specify version
npm install appambit@1.1.0

Get the SDK on NuGet (recommended)

Add the package to your MAUI project:

dotnet add package com.AppAmbit.Sdk
# or specify version
dotnet add package com.AppAmbit.Sdk --version 4.1.1

Or, using Visual Studio:

Right-click your project → Manage NuGet Packages…
Search for AppAmbit and install the latest stable version.

Get the SDK on NuGet (recommended)

Add the package to your MAUI project:

dotnet add package com.AppAmbit.Avalonia
# or specify version
dotnet add package com.AppAmbit.Avalonia --version 4.1.1

Or, using Visual Studio:

Right-click your project → Manage NuGet Packages…
Search for AppAmbit and install the latest stable version.

Initializing the SDK

.NET MAUIiOSAndroidFlutterReact NativeDOTNETAvalonia

Import the Namespace

using AppAmbitMaui;

Configure in MauiProgram

Call .UseAppAmbit("<YOUR-APPKEY>") during application initialization:

using AppAmbitMaui;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .UseAppAmbit("<YOUR-APPKEY>");

        return builder.Build();
    }
}

Platform-Specific Initialization

Android

using AppAmbitMaui;

protected override void OnCreate(Bundle? savedInstanceState)
{
    base.OnCreate(savedInstanceState);
    AppAmbitSdk.Start("<YOUR-APPKEY>");
    ...
}

iOS and macOS

using AppAmbitMaui;

public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
{
    AppAmbitSdk.Start("<YOUR-APPKEY>");
    ...
}

Windows

using AppAmbitMaui;

protected override void OnStartup(StartupEventArgs e)
{
    base.OnStartup(e);
    AppAmbitSdk.Start("<YOUR-APPKEY>");
}

Android Requirements

Add the following permissions in your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

iOS and macOS Requirements

Add the required URL exceptions in your Info.plist file:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>appambit.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSThirdPartyExceptionAllowsInsecureHTTPLoads</key>
            <true/>
        </dict>
    </dict>
</dict>

Import the SDK

Swift

import AppAmbit;

Objective-C

#import "AppAmbitSdk/AppAmbitSdk-Swift.h"

Initialize

Swift

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

Objective-C

[AppAmbit start:@"<YOUR-APPKEY>"];

Warning

It is not recommended to insert the secret API key directly into the code.

Breadcrumbs (Screen Navigation)

AppAmbit records screen-change breadcrumbs automatically. To display the intended screen name, set a navigation title:

SwiftUI

NavigationStack {
  MyView()
    .navigationTitle("My View")
}

Objective-C

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

Import the SDK

Java

import com.appambit.sdk.AppAmbit;

Kotlin

import com.appambit.sdk.AppAmbit

Initialize

Add the following line inside the onCreate callback of your app's main Activity class:

Java

AppAmbit.start(getApplicationContext(), "<YOUR-APPKEY>");

Kotlin

AppAmbit.start(this, "<YOUR-APPKEY>")

Warning

It is not recommended to insert the secret API key directly into the code.

Android App Requirements

Add the following permissions in your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

Import the SDK

import 'package:appambit_sdk/appambit_sdk.dart';

Initialize

void main() {
  AppAmbitSdk.start("<YOUR-APPKEY>");
  runApp(MyApp());
}

Import the SDK

import * as AppAmbit from "appambit";

Initialize

AppAmbit.start("<YOUR_APPKEY>");

Import the Namespace

using AppAmbit;

Initialize the SDK

using AppAmbit;

public partial class App : Application
{
    protected override void OnStartup(StartupEventArgs e)
    {
        base.OnStartup(e);
        AppAmbitSdk.Start("<YOUR-APPKEY>");
    }
}

Import the Namespace

using AppAmbitAvalonia;

Initialize the SDK

using AppAmbitAvalonia;

public partial class App : Application
{
    public override void OnFrameworkInitializationCompleted()
    {
        AppAmbitSdk.Start("<YOUR-APPKEY>");
        ...
        base.OnFrameworkInitializationCompleted();
    }
}

Platform-Specific Initialization

Android

using AppAmbitAvalonia;

public class MainActivity : AvaloniaMainActivity<App>
{
    protected override AppBuilder CustomizeAppBuilder(AppBuilder builder)
    {
        AppAmbitSdk.Start("<YOUR_APPKEY>");
        return base.CustomizeAppBuilder(builder)
            .WithInterFont();
    }
}

iOS

using AppAmbitAvalonia;

[Register("AppDelegate")]
public partial class AppDelegate : AvaloniaAppDelegate<App>
{
    protected override AppBuilder CustomizeAppBuilder(AppBuilder builder)
    {
        AppAmbitSdk.Start("<YOUR-APPKEY>");
        return base.CustomizeAppBuilder(builder)
            .WithInterFont();
    }
}

Windows and MacOS (Desktop Avalonia Multiplatform)

using AppAmbitAvalonia;

public partial class App : Application
{
    public override void OnFrameworkInitializationCompleted()
    {
        AppAmbitSdk.Start("<YOUR-APPKEY>");
        ...
        base.OnFrameworkInitializationCompleted();
    }
}

Android Requirements

Add the following permissions in your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />

iOS and macOS Requirements

Add the required URL exceptions in your Info.plist file:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>appambit.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSThirdPartyExceptionAllowsInsecureHTTPLoads</key>
            <true/>
        </dict>
    </dict>
</dict>

The SDK is now initialized and will automatically manage sessions for your application.