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 
  

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

Then run:

pod repo update

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>

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.

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 #

Only in your StatefulWidgets (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 in all StatefulWidgets (screens) except the initial StatefulWidget. In the initial screen, use AxInitialState as shown above.

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

Network Monitoring #

....
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();

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

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

Advanced Usage #

Setting Custom Identifier #

AppxiomCorePlugin allows you to assign a unique identifier to each user or device in 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.