Appxiom Core Plugin

Important

This package has been renamed and moved to appxiom_flutter.

Version 1.0.5+ of appxiomcoreplugin is for redirection purposes only. Please migrate to the new package to receive updates and new features.

A Flutter plugin for detecting and reporting bugs in mobile applications. This plugin helps developers track user journeys (Goal tracking), memory leaks, crashes, exceptions, and performance issues.

Bridge the gap between technical stability and business success with Appxiom. A Flutter plugin that connects every bug, crash, and performance bottleneck directly to its impact on your user journeys / business goals.

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  appxiomcoreplugin: ^version

Replace 'version' with the latest version at the top of the screen.

Then run:

pod repo update

flutter pub get

Quick Start

Quickly integrate Appxiom into your Flutter app. Learn to initialize the plugin, configure iOS & Android, connect StatefulWidgets, and test your setup for immediate bug reporting.

1. Initialize the Plugin

import 'package:appxiomcoreplugin/appxiomcoreplugin.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize for Android
  Ax.init("android_app_key", "android_platform_key");
  
  // Initialize for iOS
  Ax.initIOS();
  
  //Instead of runApp(MyApp()); use AxApp.run().
  AxApp.run(
    child: MyApp(),
    screenName: 'App',
    widgetName: 'MyApp',
  );
}

2. Setting iOS and iPad keys in info.plist

Open your Info.plist file and add the following keys:

<key>AX</key>
<dict>
  <!-- Keys for iOS -->
  <key>AppKey</key> 
  <string>ios_app_key</string>
  <key>PlatformKey</key>
  <string>ios_platform_key</string>


  <!-- Keys for iPadOS -->
  <key>AppKeyIpad</key>
  <string>ipados_app_key</string>
  <key>PlatformKeyIpad</key>
  <string>ipados_platform_key</string>
</dict>

Replace ios_app_key, ios_platform_key, ipados_app_key, and ipados_platform_key with the actual keys from your Appxiom dashboard.

In case of SwiftUI projects, the info.plist file can be access via info tab in your app target.

3. Setting up Android

Open your project level build.gradle file and add the following inside the repositories block:

maven {
    url = uri("https://appxiom-android.s3.us-west-1.amazonaws.com") //Appxiom Maven repo link
}

4. Connecting StatefulWidgets to Appxiom

  1. Extend your initial screen/splash screen StatefulWidget, with AxInitialState instead of regular State.
  2. Extend all other StatefulWidgets with AxState instead of State.
  3. Set a unique name for the stateClassName property in each of the StatefulWidgets to get meaningful screen names in issue reports in release builds.
// For the FIRST screen/initial screen only
class InitialScreen extends StatefulWidget {
  @override
  _InitialScreenState createState() => _InitialScreenState();
}

class _InitialScreenState extends AxInitialState<InitialScreen> {

  @override
  String? get stateClassName => "InitialScreen"; //Set value for stateClassName to get meaningful screen name in issue reports in release builds.

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Text('Initial Screen'),
    );
  }
}

To set a custom identifier for the device, refer the Setting Custom Identifier section.

5. Test Integration

Use the Ax.test() API to raise a test issue. Once the appxiom is initialized, the test issue will be raised in the dashboard.

Ax.test();

Make sure to remove this API once the integration is successfull.

In order to track user journeys, refer the Goal/ User Journey Tracking section.

Isolate Tracking

Appxiom allows you to monitor background isolates for crashes and unexpected terminations. This is useful for tracking background tasks and multi processing where errors might otherwise go unnoticed.

How to use Isolate Tracking

  1. Replace Isolate.spawn() with AxIsolate.spawn() to start a tracked isolate.
  2. Set a name for the isolate using the name parameter.
import 'package:appxiomcoreplugin/appxiomcoreplugin.dart';

void mainTasks() async {
  // Spawn a tracked isolate
  await AxIsolate.spawn(
    name: 'batch_sync_isolate', //Give your isolate a meaningful name.
    entryPoint: myIsolateEntryPoint,
    message: 'initial_payload',
  );
}

// The isolate entry point
void myIsolateEntryPoint(String message) {
  // Isolate logic here
  // Any uncaught error will be automatically reported to Appxiom
}

In order to report caught errors, please refer the section at Custom Error Reporting

Memory Leak Detection

Detect memory leaks in both development and production builds of your Flutter app with Appxiom. Learn how to use AxState and AxInitialState to monitor memory usage and prevent performance degradation.

If you have already completed the integration step Connecting StatefulWidgets to Appxiom, you can skip this step.

  1. Extend your initial screen/splash screen StatefulWidget, with AxInitialState instead of regular State.
  2. Extend all other StatefulWidgets with AxState instead of State.
  3. Set a unique name for the stateClassName property in each of the StatefulWidgets to get meaningful screen names in issue reports in release builds.
// For all OTHER screens, use AxState
class MyWidget extends StatefulWidget {
  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends AxState<MyWidget> {

  @override
  String? get stateClassName => "HomeScreen"; //Set value for stateClassName to get meaningful screen name in issue reports in release builds.

  @override
  Widget build(BuildContext context) {
    return Container(
      child: Text('Hello World'),
    );
  }
}

App Startup Delay Monitoring

Improve your app's first impression by monitoring startup delays. See how Appxiom's AxInitialState helps you track your Flutter application's launch performance.

If you have already completed the integration step Connecting StatefulWidgets to Appxiom, you can skip this step.

  • Extend your initial screen/splash screen StatefulWidget, with AxInitialState instead of regular State.

Network Monitoring

Appxiom provides network monitoring capabilities to track HTTP request performance and failures. To monitor your network calls, use AxClient in place of the standard http.Client.


....
var client = http.Client(); //Regular http client to make calls.

// The plugin intercepts HTTP calls
// Use AxClient instead of http.Client() to monitor HTTP requests
var client = AxClient();

This will track API calls for errors, latency and other performance metrics and reports them to Appxiom dashboard.

Custom Issue Reporting

Go beyond automatic crash detection. Learn to use Ax.reportIssue() to log custom business logic failures in Flutter.

// Report custom issues
Ax.reportIssue("LoginScreen","Login failed", "User authentication failed with invalid credentials");

Custom Error Reporting

To report custom exceptions or errors that are caught using try-catch blocks, use the Ax.reportError method:


// Report custom exceptions with stack trace
try {
  // Some code that may throw an error
} catch (error, stackTrace) {
  // Report the error using Ax.reportError API
  Ax.reportError(error, stackTrace);
}

Goal/ User Journey Tracking

Understand how bugs impact your business with Goal Friction Impact (GFI). Track user journeys, measure conversion funnels, and get auto prioritized issue reports that will help you improve your app's goals.

Define goals for key user flows like signup, purchase, onboarding, or any other, and Appxiom will monitor completion rates, identify friction points, and calculate customer loss when issues occur.

How Goal Friction Impact Works

GFI transforms traditional bug reporting into business intelligence:

  • Define Goals: Mark the start and end of important user flows
  • Track Completion: Monitor how many users successfully complete each goal
  • Identify Friction: Detect when crashes, freezes, API failures or any other issues interrupt user journeys
  • Measure Impact: Calculate completion rates, drop-off points, and potential customer loss
  • Prioritize Fixes: Focus on bugs that have the highest business impact

Use the beginGoal() and completeGoal() methods to track user journeys through your app's critical flows.

// Begin a goal and get the goal ID
int goalId = await Ax.beginGoal("user_signup");

// Complete the goal
await Ax.completeGoal(goalId);

Best Practices for Goal Tracking

1. Choose Meaningful Goals

  • Focus on business-critical user flows
  • Track complete end-to-end journeys
  • Use descriptive goal names

2. Strategic Placement

  • Call beginGoal() at the start of the user flow
  • Call completeGoal() only when the user successfully completes the entire journey
  • Don't call completeGoal() for partial completions

3. Goal Naming Convention

Important: Goal names are automatically filtered and have the following restrictions:

  • Only alphanumeric characters (A-Z, a-z, 0-9) and underscores (_) are allowed. All other characters are removed.
  • Maximum length is 64 characters. Names longer than 64 characters will be truncated.
// Original goal name → Filtered goal name
"user_registration_flow" → "user_registration_flow"  // Underscores preserved
"premium-subscription-purchase" → "premiumsubscriptionpurchase"  // Hyphens removed
"first.time.user.onboarding" → "firsttimeuseronboarding"  // Dots removed
"user@signup#flow" → "usersignupflow"  // Special characters removed

// Length limit example
"very_long_goal_name_that_exceeds_the_maximum_allowed_length_limit_of_64_characters_will_be_truncated" 
→ "very_long_goal_name_that_exceeds_the_maximum_allowed_length_li"  // Truncated at 64 chars

Advanced Usage

Provide Geo location data

Appxiom allows you to attach geographic context to reported issues. This is optional and only be set if the Flutter application is using location data. Appxiom will not ask for location permissions.

To set the user's current position:

// Set the current latitude and longitude
Ax.setCurrentPosition(latitude, longitude);

Appxiom does not automatically fetch the location.

Setting Custom Identifier

AppxiomCorePlugin allows you to assign a unique identifier to each user or device of your Flutter application. By setting a custom device or user ID, you can track and associate all issue reports with specific users or devices in the Appxiom dashboard. This feature is ideal for effective troubleshooting and user support.

  • Simple Integration: Set a custom ID for the device or user with a single line of code.
  • Flexible Identifier: Use any string up to 256 characters as the identifier.
  • Automatic Tagging: Once set, all issue reports will include the custom ID for precise tracking.
  • Latest ID Used: If you call the setCustomId() multiple times, the most recent ID will be used for all future reports.
Ax.setCustomId("user_12345"); //Set a custom identifier for the user device.

Regular API call without Client

Use AxHttp for HTTP monitoring when not using AxClient:


// Regular API call without using Client.
http.get(Uri.parse('<url>'));

// AxHttp tracks:
// - Request/response times
// - HTTP status codes
// - Request/response headers.
// - Request payloads
// - API endpoint patterns
AxHttp.get(
    Uri.parse('<url>'),
    headers: {'Content-Type': 'application/json'},
); // Replace http with AxHttp to monitor the request/response.

Customize Network Monitoring

Configure URL patterns and masked headers for better network monitoring:

import 'package:appxiomcoreplugin/observe.dart';

// Configure URL patterns to group dynamic segments together
// This ensures URLs like /users/123 and /users/456 are grouped as a single ticket.
Observe().setUrlPatterns([
  '/users/{id}',        // Groups /users/123, /users/456, etc.
  '/posts/{id}'        // Groups /posts/abc, /posts/xyz, etc.
]);

// Mask sensitive headers in requests and responses
// These headers will be replaced with "*" from the plugin itself before sending to the Appxiom dashboard
Observe().setMaskedHeaders([
  'X-API-KEY'          // API keys
]);

Benefits:

  • URL Patterns: Reduces noise by grouping similar API calls with dynamic IDs
  • Masked Headers: Protects sensitive authentication data from being logged
  • Better Analytics: Cleaner dashboard with meaningful API endpoint groupings

Activity Markers

Activity markers are custom events that you can set throughout your Flutter application to track user interactions, business logic flow, and important application states. Activity markers provide a complete picture of your app's behavior when issues occur.

To set custom activity markers, use the setActivityMarker() method in your codebase. Each marker consists of a name and an optional description.

// Set an activity marker
Ax.setActivityMarker("button_clicked", "Login button pressed");

Configure R8/Proguard Rules for Appxiom Plugin in Flutter (Android platform)

To ensure Appxiom Plugin functions correctly in your Android release builds, you must configure R8/Proguard rules to prevent essential classes and annotations from being obfuscated. Proper configuration also preserves stacktrace details for effective debugging and error analysis in the Appxiom dashboard.

Required Proguard Rules

Add the following rules to your proguard-rules.pro file:

-keep class tech.appxiom.android.core.* { *; }

-keepclassmembers class * {
    @tech.appxiom.android.core.annotation.AX *;
}

-keepclassmembers class androidx.lifecycle.** {
    *;
}

About Appxiom

Appxiom helps developers build more reliable mobile applications with comprehensive monitoring and debugging tools. Visit appxiom.com to learn more.

Libraries

appxiomcoreplugin
ax_client
observe
state_custom