Appxiom Core Plugin #

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.

Installation #

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

dependencies:
  appxiomcoreplugin: ^version

Then run:

flutter pub get

Quick Start #

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();
  
  runApp(MyApp());
}

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>

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
}

App Startup Delay Monitoring #

In your first screen (initial screen/splash screen), use AxInitialState instead of regular State to monitor cold startup delays:

// For the FIRST screen/initial screen only
class InitialScreen extends StatefulWidget {
  @override
  _InitialScreenState createState() => _InitialScreenState();
}

class _InitialScreenState extends AxInitialState<InitialScreen> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Text('Initial Screen'),
    );
  }
}

Memory Leak Detection #

Use AxState instead of regular State for memory leak detection.

// For all OTHER screens, use AxState
class MyWidget extends StatefulWidget {
  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends AxState<MyWidget> {
  @override
  Widget build(BuildContext context) {
    return Container(
      child: Text('Hello World'),
    );
  }
}

Goal/ User Journey Tracking #

Appxiom Plugin's Goal Friction Impact (GFI) feature enables you to track user journeys through critical app flows and understand how bugs and performance issues impact your business metrics. 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

Activity Markers #

Set activity markers for debugging:

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

Network Monitoring #

// The plugin automatically intercepts HTTP calls
// Use AxClient for monitored HTTP requests
AxClient().get(Uri.parse('<url>'));

Custom Issue Reporting #

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

Custom Error Reporting #

// 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);
}

Advanced Usage #

HTTP Interceptor #

Use AxHttpInterceptor for HTTP monitoring when not using AxClient:

// The interceptor automatically tracks:
// - Request/response times
// - HTTP status codes
// - Request/response payloads
// - API endpoint patterns

AxHttpInterceptor.get(
    Uri.parse('<url>'),
    headers: {'Content-Type': 'application/json'},
);

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 "*" in 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

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.