appambit_sdk_flutter 1.2.0

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

AppAmbit Flutter 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

---

Contents

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

---

Features

• Session analytics with automatic lifecycle tracking
• Event tracking with custom properties
• Error logging for quick diagnostics
• Crash capture with stack traces and threads
• Offline support with batching, retry, and queue
• Cloud SQLite database access with raw SQL, batch/transaction support, and a fluent query builder
• Cloud Code HTTP function calls with dynamic and typed responses
• Create mutliple app profiles for staging and production
• Small footprint

---

Requirements

• Flutter SDK >=3.3.0
• Dart SDK >=3.9.0
• Android SDK with:
  • Android 7.0+ (API 24)
  • compileSdkVersion 36
  • minSdkVersion 24
• iOS SDK with:
  • iOS 13.0+
  • Xcode 15+ (for iOS)
  • macOS 13+

---

Install

Add the AppAmbit Flutter SDK to your app’s pubspec.yml.

dependencies:
  flutter:
    sdk: flutter
  appambit_sdk_flutter: ^1.2.0

and then

flutter pub get

Or add it using

flutter pub add appambit_sdk_flutter

---

Quickstart

Initialize the SDK with your API key.

Dart

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

   await AppAmbitSdk.start(appKey: '<YOUR-APPKEY>');

  runApp(const MyApp());
}

---

Android App Requirements

Add these permissions to your AndroidManifest.xml:

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

---

Usage

• Session activity – automatically tracks user session starts, stops, and durations
• Track events – send structured events with custom properties
• Remote Config – dynamic configuration values fetched and applied at runtime

Dart

await AppAmbitSdk.trackEvent('ButtonClicked', <String, String>{'Count': '41'});

Dart

try {
    throw Exception('Test with Properties');
} catch (e, st) {
    await AppAmbitSdk.logError(
    exception: e,
    stackTrace: st,
    properties: <String, String>{'user_id': '1'}
    );
}

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  AppAmbitSdk.enableConfig();
  AppAmbitSdk.start(appKey: '<YOUR-APPKEY>');

  runApp(const MyApp());
}

// String
String variable = await AppAmbitSdk.getString("<key_name>");
// Long
int variable = await AppAmbitSdk.getLong("<key_name>");
// Double
double variable = await AppAmbitSdk.getDouble("<key_name>");
// Boolean
bool variable = await AppAmbitSdk.getBoolean("<key_name>");

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

---

Cloud Code

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.

Before calling a function, configure an active Cloud Function with an enabled HTTP trigger and a slug in the AppAmbit Dashboard. The slug is the first argument passed to CloudCode.call.

import 'package:appambit_sdk_flutter/appambit_sdk_flutter.dart';

final request = CloudCode.call(
  'hello',
  method: CloudCodeHttpMethod.post,
  query: {'source': 'flutter'},
  body: {'name': 'Ada'},
  headers: {'X-Client': 'flutter'},
);

try {
  final response = await request.future;
  debugPrint('HTTP ${response.statusCode}: ${response.data}');
} on CloudCodeError catch (error) {
  debugPrint('${error.code}: ${error.message}');
}

Requests can be cancelled while they are pending. The request object also preserves the response status, headers, duration, and request ID returned by the native SDK:

final request = CloudCode.call('hello');
await request.cancel();

For typed responses, provide a converter matching the JSON returned by the function. This function is expected to return {"number": 42}:

import 'package:appambit_sdk_flutter/appambit_sdk_flutter.dart';

final result = await CloudCode.callTyped<int>(
  'hello',
  fromJson: (value) => (value as Map)['number'] as int,
).future;

Cloud Code calls are request/response operations and are not queued for offline upload. The SDK forwards authentication, rejects reserved headers, and applies the native 60-second timeout. It does not manage tokens, URLs, or retries in Dart.

Optionally pass a shorter timeout to give up sooner and cancel the native call early; it cannot extend past the native 60-second limit, and it's a Flutter-only addition (not part of the Android, iOS, or .NET API):

final request = CloudCode.call('hello', timeout: const Duration(seconds: 10));

See the Cloud Code mobile guide for function setup, HTTP triggers, typed and dynamic responses, errors, request IDs, cancellation, timeouts, and backend examples. The example app includes the complete Database, CMS, Push, and HTTP Cloud Code catalog used by the native Android and iOS samples.

---

Release Distribution

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

---

Privacy and Data

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

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

---

Troubleshooting

• No data in dashboard → check API key, endpoint, and network access
• Flutter dependency not resolving → run flutter clean and flutter pub get and verify again
• Crash not appearing → crashes are sent on next launch

---

Contributing

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 Dart API design guidelines and document public APIs.

---

Versioning

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

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

---

Security

If you find a security issue, please contact us at [e-mail] rather than opening a public issue.

---

License

Open source under the terms described in the LICENSE file.

---

Links

• Docs: docs.appambit.com
• Dashboard: appambit.com
• Discord: discord.gg
• Examples: Sample Flutter test app included in repo.