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'
        }
    }
    
  4. Apply apptics-plugin and enable event tracking in app level gradle (app/build.gradle)

    apply plugin: "com.android.application"
    apply plugin: "apptics-plugin"
    
    apptics {
        supportEventAsStrings = ["default":true]
    }
    
  5. Rebuild the Android project. (Build -> Rebuild in Android Studio)

  6. 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, move the file into the Xcode project root folder, and add the config file to the main target.
  3. Add pre-build scripts to your 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

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' is below the 'Compile Sources' and '[cp-user] 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

4. Build the Xcode project and check for any issues.

Create AppticsFlutter instance

import 'package:apptics_flutter/apptics_flutter.dart';

final _appticsFlutterPlugin = AppticsFlutter();

Event Tracking

  1. Configure custom events in Apptics webconsole.
  2. Track the configured event with properties using addEvent method.
_appticsFlutterPlugin.addEvent("eventName", "eventGroupName", {'propKey': 'propValue'})

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'';
   AppticsInAppRating.instance.checkForRatingPop(context);
  • 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';


  String? stringValue = await AppticsRemoteConfig.instance.getStringValue('paramName');
  if (stringValue != null) {
  // code 
  }

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

Create AppticsFlutter instance

   import 'package:apptics_flutter/apptics_flutter.dart';
   
   final _appticsFlutterPlugin = AppticsFlutter();

Show Popup:

  • To check and show new version alert pop-up, call checkAndUpdateAlert method.
      _appticsFlutterPlugin.checkAndUpdateAlert(context)
  • 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.
      _appticsFlutterPlugin.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: ZAnalytics custom UI alert
 1: ZAnalytics native 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.