apptics_flutter 0.0.6

Flutter plugin for Apptics, wrapper around Apptics Native iOS and Android SDK. Supports features likes in-app updates, in-app events, screens and sessions.

Apptics Flutter

Flutter library for Apptics, wrapper around Apptics Native iOS and Android SDK. Supports features likes in-app updates, in-app events, screens and sessions.

Android initialization steps

1. Register your app and download apptics-config.json from Apptics web console.

2. Place apptics-config.json file in app/ directory (Root of the Android Studio app module).

3. Add apptics-plugin classpath and zoho maven url in project level build.gradle

   buildscript {
       repositories {
           maven {
               url "https://maven.zohodl.com/"
           }
       }
       dependencies {
           classpath 'com.zoho.apptics:apptics-plugin:0.1.2'
       }
   }
   allprojects {
    repositories {
        maven {
            url "https://maven.zohodl.com/"
        }
    }
   }
   

4. In the Android environment, our support begins from a minimum SDK version of 23.

Initialization steps for Apple platforms

1. Register your app and download apptics-config.plist from Apptics web console.
2. Once you have created the Project and added your app, download the apptics-config.plist, and move the file into the Xcode project root folder and add the config file to the main target.
3. Add pre-build scripts.

To add a Run Script via podfile.

source 'https://github.com/CocoaPods/Specs.git'
  target 'MAIN TARGET' do

    # Pre build script will register the app version, upload dSYM file to the server and add apptics specific information to the main info.plist which will be used by the SDK.
    script_phase :name => 'Apptics pre build', :script => 'sh "./Pods/Apptics-SDK/scripts/run" --upload-symbols-for-configurations="Release, Appstore"', :execution_position => :before_compile

  end

Or add a Run Script manually.

• In the project navigator, select your project.

• Select the target you want to modify.

• Click the Build Phases tab. Click the Add button (+), then choose “New Run Script Phase” from the pop-up menu and rename it as 'Apptics pre build.'

• Click the disclosure triangle for the newly added Run Script phase.

• In the Shell text field, enter the script below.

  sh "./Pods/Apptics-SDK/scripts/run" --upload-symbols-for-configurations="Release, Appstore"
  

Important:

• Adding pre-build scripts is mandatory.
• In the pre-build script, we upload dSYM to the server (optional), register the app with the Apptics server, and add the necessary information of the app version into the apptics-config.plist which is used by the SDK to send the data to the Apptics server.
• Always make sure 'Copy Bundle Resources' below the 'Compile Sources' and 'Apptics pre build' is above 'Compile Sources'.

Build script usage:

run --upload-symbols-for-configurations="Release, Appstore" --config-file-path="YOUR_PATH/apptics-config.plist" --app-group-identifier="group.com.company.application [Optional]"

• --config-file-path pass your config file path if it is not added to your project root.
• --app-group-identifier if you have enabled app group identifier for your app's target.
• --upload-symbols-for-configurations String, an optional parameter to pass your configuration name debug, release, or add a custom name with comma-separated for which the dSYMs will be uploaded without any prompt during App Store submission process via CI, CT, and CD.

For more details on how to configure for multiple projects please visit iOS user guide

1. Build the Xcode project and check for any issues and skip to 'Event Tracking'.

Create AppticsFlutter instance

import 'package:apptics_flutter/apptics_flutter.dart';

class _YourClassState extends State<YourClass> {
  // initializes AppticsFlutter
 // _appticsFlutterPlugin can be used to track events, screens, user and control tracking settings.
  final _appticsFlutterPlugin = AppticsFlutter();
}

Event Tracking

1. Track the configured event with properties using addEvent method.

  _appticsFlutterPlugin.addEvent("eventName", "eventGroupName") // Without Properties
  (or)
  _appticsFlutterPlugin.addEvent("eventName", "eventGroupName", properties: {"propKey": "propValue"}) // With Propeties
  

Screen Tracking

Use the methods provided to track screen navigation.

// call when screen appears
_appticsFlutterPlugin.screenAttached("screenName")

// call when screen disappears
_appticsFlutterPlugin.screenDetached("screenName")

Track User

Ties user-id with other stats (events, screens etc)

User Id tracking will happen with respect to Tracking Settings. If the tracking settings is " WithoutPII", stats will not be associated with the user id.

_appticsFlutterPlugin.setUser("userid")

Tracking settings

Apptics offer 7 tracking states to control usage and crash tracking.

1. UsageAndCrashTrackingWithPII
2. UsageAndCrashTrackingWithoutPII
3. OnlyUsageTrackingWithPII
4. OnlyUsageTrackingWithoutPII
5. OnlyCrashTrackingWithPII
6. OnlyCrashTrackingWithoutPII
7. NoTracking

UsageAndCrashTrackingWithoutPII is the default state out of the box.

Usage Tracking

Usage tracking generally refers to tracking the Events, APIs, Screens, Sessions.

Crash Tracking

Crash tracking is self-explanatory and refers to the tracking of unhandled exceptions.

PII

The term PII is used to denote the value you set using the _appticsFlutterPlugin.setUser method.

You can use setTrackingState method to change the tracking state.

// to change the tracking settings to track only crash and associate user id with crash.
_appticsFlutterPlugin.setTrackingState(TrackingState.OnlyCrashTrackingWithPII);

// to get the current tracking state
_appticsFlutterPlugin.getTrackingState();

In-app Ratings

Use AppticsInAppRating instance

• To check and show new rating alert pop-up, call checkForRatingPop method.

import 'package:apptics_flutter/rateus/apptics_in_app_rating.dart'';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
// To check and show a new rating alert pop-up, call the checkForRatingPop method.
    AppticsInAppRating.instance.checkForRatingPop(context);

    // return your widget;
  }
}

• To activate the "Send Feedback" option, set isFeedbackEnabled to true. Future<void> checkForRatingPop(BuildContext context, {bool isFeedbackEnabled = false})
• This method should be invoked after setting the theme and creating the navigator in a Flutter application.
• The in-rating pop functionality in Flutter does not currently provide support for Material3.

The in-app rating pop-up will be shown automatically with respect to the configuration in the web console. The default pop-up will have two or three options depending on the availability of Apptics feedback module dependency.

• 'Rate in Playstore' action will redirect the user to the PlayStore where user can add their ratings and reviews.
• 'Later' action will dismiss the rating pop-up and the pop-up will be automatically prompted again after a certain period.
• 'Send Feedback' action will only appear if the Apptics feedback SDK is integrated into the app. This action will direct the user to the Apptics feedback activity. Ensure that you set the Apptics theme; otherwise, app will crash.

If the user chooses 'later' option in the pop-up, the next prompt will be deferred by 10 days ( default). Use the below method to customize the number of days to defer the prompt.

    AppticsInAppRating.instance.daysBeforeShowingPopupAgain = // days as int;

If the user chooses 'Later' option for three consecutive times, the popup will not be shown again until the criteria for that app version is reconfigured in the Apptics web console. Use the below method to customize the max number of prompts.

    AppticsInAppRating.instance.maxTimesToShowPopup = //number as int

Build your own UI

   import 'package:apptics_flutter/rateus/apptics_in_app_rating.dart'';
   
   await AppticsInAppRating.instance.getCriteriaId();

• The method above returns the criteriaId, which you can use to construct your UI. If the criteriaId is available, you can display your UI. This method operates asynchronously.

• You will have to call the sendStats method to send the stats to the server.

The value of an action param can be RATE_IN_STORE_CLICKED, SEND_FEEDBACK_CLICKED, or LATER_CLICKED enum depending upon whether the button clicked is to:

• Rate the app
• Go to the feedback screen
• Dismiss the dialog

   import 'package:apptics_flutter/rateus/apptics_in_app_rating.dart'';
   
       AppticsInAppRating.instance.sentStats(criteriaId: criteriaId, popupAction: PopupAction.LATER_CLICKED); 
       

Store in-app review API

   import 'package:apptics_flutter/rateus/apptics_in_app_rating.dart'';
   
    AppticsInAppRating.instance.setShowStoreAlertOnFulFillingCriteria(true);

If you use checkForRatingPop method. Enabling this will automatically present Google Play's in-app review system once the configured criterion is fulfilled.

Google Play review API doesn't have a callback to know whether the review UI is presented or not.

The Review API quotas are not well defined in the documentation. So, once the configured criterion is fulfilled and the Review API is invoked we will automatically defer the next review API call with respect to the value set in daysBeforeShowingPopupAgain.

Remote Configuration

Check our user guides to configure Remote config params and conditions.

Use the below snippet to fetch value for a param.

import 'package:apptics_flutter/remoteconfig/apptics_remote_config.dart';

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});
  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {

  getRemoteConfigData(BuildContext context) async {
    // Use the below method to fetch value for a param.
    String? stringValue = await AppticsRemoteConfig.instance.getStringValue('color'); // params need to config in web console.
    if (stringValue != null) {
      print("stringValue $stringValue");
      showDialog(
        context: context,
        builder: (context) {
          return AlertDialog(
            title: Text(stringValue),
            alignment: Alignment.center,
          );
        },
      );
    } else {
      print("No data available");
    }
  }

  @override
  Widget build(BuildContext context) {
    getRemoteConfigData(context);
    // return your widget;
  }
}

getStringValue accept three params. Future<String?> getStringValue(String key, { bool coldFetch = false, bool fallbackWithOfflineValue = false,})

• key [String] - the name of the param configured in web console.
• 'coldFetch' [bool] getStringValue has a cache mechanism, which prevents frequent network calls. If coldFetch is enabled, getStringValue fetches from Network ignoring the cache mechanism. However, we allow only 3 calls to network per minute, if this threshold breaks the method will return null or fallback to offline value.
• 'fallbackWithOfflineValue' [Boolean] - If enabled, getStringValue will return previously fetched value incase of Network failures.

Set custom condition criteria

Use the below method to set custom condition criteria for the device.

AppticsRemoteConfig.instance.setCustomConditionValue("ConditionKey", "Criteria")

In-App Update

Show Popup:

• To check and show new version alert pop-up, call checkAndUpdateAlert method.

import 'package:apptics_flutter/appupdate/apptics_in_app_update.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  

  @override
  Widget build(BuildContext context) {
    // Call the method checkAndUpdateAlert to check for updates and to show the update popup.
    AppticsInAppUpdates.instance.checkAndUpdateAlert(context);
    
    // return your widget;
  }
}

• This method should be invoked after setting the theme and creating the navigator in a Flutter application.
• The in-app update functionality in Flutter does not currently provide support for Material3.

Build your own flow

• The method below returns a Map<String, dynamic?>, allowing you to obtain data for your pop-up UI.
• With the data obtained from this method, you have the flexibility to design and implement your own custom pop-up UI to display the in-app update information.

      AppticsInAppUpdates.instance.getInAppUpdateData(context)

• Returns null, in case of no update availability.
• You can determine the response type base on the value of the category string, where 1 represents Normal update data and 2 represents Non-Supported OS popup data.
• After obtaining the map, you can extract the key-value pairs listed below, which can be used to create your custom UI. The action methods available are onClickUpdate, onClickReminder, onClickIgnore, onClickNonSupportAlert, and onSendImpressionStatus.
• Below are the keys you can use to construct your custom UI.

 For Custom Alerts data (Normal update):
 'updateid': The ID corresponding to a specific update configuration.
 'currentversion': The version of the app installed on the device.
 'featureTitle': The title or heading for the version alert.
 'features': Update features or what's new.
 'remindMeLaterText': Localized text for the "Remind Me Later" action.
 'updateNowText': Localized text for the "Update" action.
 'neverAgainText': Localized text for the "Ignore" action.
 
 The 'option' key determines the type of UI selected for this update in the web console:
 option (1): Flexible update flow.
 option (2): Immediate update flow.
 option (3): Force update flow.
 Read More https://www.zoho.com/apptics/resources/user-guide/in-app-updates.html
 
 'reminderDays': The number of days before showing the popup again if the user chooses "Remind Me Later." These days can be configured from the web console.

 'forceInDays': A custom store URL to redirect when the user taps "Update/Download." This can also be configured from the web console.

 'alertType': The type of the alert - Android in-app updates / ZAnalytics:
 
 0: Apptics Native UI alert
 1: Apptics Custom UI alert
 2: Android in-app updates
 
 'customStoreUrl': You can redirect this URL to another store.

 For the Non-Supported OS popup data:

 'title': The title of the popup.
 'description': The description of the popup.
 'continueBtTxt': Button text for the popup.
 'alertType' in the Non-Supported OS popup determines the action:
  0: Do Nothing
  1: Install Later
  2: Freeze
 'updateid': The ID corresponding to a specific update configuration.

Apptics Crash Tracking

Fatal Crash

• To enable automatic crash tracking, use the following method.

import 'package:apptics_flutter/crash_tracker/apptics_crash_tracker.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  
  @override
  Widget build(BuildContext context) {
    // Call the method autoCrashTracker to enable crash autoTracking.
    AppticsCrashTracker.instance.autoCrashTracker();
    
    // return your widget;
  }
}

Get last crash info

• You can always get the previous crash information as stringified JSONObject.

import 'package:apptics_flutter/crash_tracker/apptics_crash_tracker.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    // You can reliably obtain the previous crash information as a string.
    String? lastCrash = AppticsCrashTracker.instance.getLastCrashInfo();

    // return your widget;
  }
}

• Sample JSON structure:

{
  "issuename": "divide by zero",
  "message": "java.lang.ArithmeticException: divide by zero\n\tat com.zoho.apptics.MainActivity.onCreate$lambda$2(MainActivity.kt:42)",
  "networkstatus": 0,
  "serviceprovider": "T-Mobile",
  "orientation": 0,
  "batterystatus": 100,
  "edge": "Unknown",
  "ram": "2.9 GB",
  "rom": "5.8 GB",
  "sessionstarttime": 1711445408267,
  "customproperties": {},
  "screenname": "com.zoho.apptics.MainActivity",
  "happenedat": 1711445420908,
  "happenedcount": 1,
  "listofhappenedtime": 1711445420908,
  "errortype": "native"
}

Showing consent pop-up to send previous session crash info

• Presenting a consent pop-up to send crash information from previous sessions.

import 'package:apptics_flutter/crash_tracker/apptics_crash_tracker.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    // Displaying a consent pop-up to allow the sending of crash information from previous sessions.
    AppticsCrashTracker.instance.showLastSessionCrashedPopup();

    // return your widget;
  }
}

Non-Fatal Crash

Handle Exception

• You can use the following method to record non-fatal exceptions.

import 'package:apptics_flutter/crash_tracker/apptics_crash_tracker.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    
     try {
      int k = (1 / 0) as int;
    }catch(e,s){
      // Use the below method to record non-fatal.
      AppticsCrashTracker.instance.sendNonFatalException(e, s);
    }

    // return your widget;
  }
}

Set Custom Property

• Add custom properties for both fatal and non-fatal events using the method below.

import 'package:apptics_flutter/crash_tracker/apptics_crash_tracker.dart';

 class MyApp extends StatelessWidget {
  const MyApp({super.key});
  
  setCustomProperties() async {
    Map<String, dynamic> _portaInfoMap = {
      "name": "ABCD",
      "domains": ["Data Science", "Mobile", "Web"],
    };

    // Implement the following method to set a Custom Property. You can pass the parameter [map].
    await AppticsCrashTracker.instance.setCrashCustomProperty(_portaInfoMap);
  }
   
  @override
  Widget build(BuildContext context) {
    setCustomProperties();
    // return your widget;
  }
}