@zoho_apptics/apptics-react-native v0.7.0

Apptics React Native

React Native library for Apptics, wrapper around Apptics Native iOS and Android SDK. Supports tracking in-app events, screens, session, crash tracking, in-app version alerts and Remote configs.

Prerequisites

• Requires React Native v0.6+
• Setup development environment for React Native

Install Apptics

Navigate to your app's root directory in terminal to install apptics-react-native package.

npm install @zoho_apptics/apptics-react-native

Initialize Apptics

Apptics requires you to perform platform specific initialization steps.

intialization 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 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


  post_install do |installer|
        puts system("sh ./Pods/Apptics-SDK/native/scripts/postinstaller --prefix=\"[PREFIX STRING]\" --target-name=\"[MAIN TRGET NAME STRING\" --config-file-path=\"apptics-config-debug.plist\"")
  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' 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

Postinstaller script usage:

postinstaller --prefix=\"PREFIX STRING\" --target-name=\"[MAIN TRGET NAME STRING\" --config-file-path=\"apptics-config-debug.plist\""

• --prefix="PREFIX STRING"
• --target-name="MAIN TARGET NAME Optional"
• --target-group="TARGET GROUP NAME Optional"
• --project-name="PROJECT NAME Optional"
• --project-file-path="PROJECT FILE PATH Optional"
• --config-file-path="CONFIG FILE PATH Optional"
• --use-swift Optional

4. Import Apptics in your AppDelegate file

#import <Apptics/Apptics.h>

• Check the configurations and make the necessary changes, if needed. In your Appdelegate class make sure you call this method Apptics.initializewithVerbose: or Apptics.initializewithVerbose: config:` in your app launch.

Note: For Mac applications, make sure you call Apptics.initializewithVerbose: in applicationWillFinishLaunching:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey,id> *)launchOptions

  [Apptics initializeWithVerbose:<#(BOOL)#>];

  return true;
}

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

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

   apply plugin: "com.android.application"
   apply plugin: "apptics-plugin"

5. Rebuild the Android project. (Build -> Rebuild in Android Studio)

6. Initialize Apptics in JS.

   import { Apptics } from '@zoho_apptics/apptics-react-native';
   
   Apptics.init();

Crash Tracking.

Initialize react native crash handler.

import { Apptics } from '@zoho_apptics/apptics-react-native';

React.useEffect(() => {
    Apptics.initCrashTracker()
  }, []);

Event Tracking

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

import { Apptics } from '@zoho_apptics/apptics-react-native';

Apptics.addEvent("eventName", "eventGroupName", {'propKey': 'propValue'})

Screen Tracking

Use the methods provided to track screen navigation.

import { Apptics } from '@zoho_apptics/apptics-react-native';

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

// call when screen disappears
Apptics.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.

import { Apptics } from '@zoho_apptics/apptics-react-native';

Apptics.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 undhandled exceptions.

PII

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

You can use setTrackingState method to change the tracking state.

import { Apptics, TrackingState } from '@zoho_apptics/apptics-react-native';

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

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

In-app version alerts

Version alerts can be configured from Apptics webconsole. Please refer user guide. Use the below snippet to check and show version alert pop-up

import { Apptics, AppticsAppUpdate } from '@zoho_apptics/apptics-react-native';

AppticsAppUpdate.showVersionAlertPopup()

Make sure to call Apptics.init before calling showVersionAlertPopup.

Add the below colors to your App theme in main/res/values/styles.xml

<item name="appticsTextColor">#000000</item>
<item name="appticsSecondaryTextColor">#000000</item>
<item name="appticsUpdateActionButtonColor">#FF00FF</item>
<item name="appticsUpdateActionButtonTextColor">#000000</item>
<item name="appticsRemindAndIgnoreActionButtonColor">#FF00FF</item>

Check our native SDK theme guide to know more about these color tokens.

Build your own flow You can use checkForUpdate method to obtain a map of data as configured in the webconsole, which can be used to build your own UI and flow for in-app version alerts.

import { Apptics, AppticsAppUpdate } from '@zoho_apptics/apptics-react-native';

AppticsAppUpdate.checkForUpdate()

• Method returns null, if there is no update configured for this version.

Below are the keys available in map obtained from checkForUpdate method.

 '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.

• Send action from your custom built pop-up for Apptics to build stats.

import { Apptics, AppticsAppUpdate } from '@zoho_apptics/apptics-react-native';

// update id, fetched from map returned by checkForUpdate
// actions are defined in UpdateStats Enum
AppticsAppUpdate.sendUpdateStat(update_id, UpdateStats.Impression)

Remote Config

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

Use the below snippet to fetch value for a param.

import { Apptics, AppticsRemoteConfig} from '@zoho_apptics/apptics-react-native';

AppticsRemoteConfig.getStringValue("param_name", false, true).then(function(success: string) {
      console.log(success);
    })

getStringValue accepts three params. key - the name of the param configured in web console.

coldFetch - 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 - If enabled, getStringValue will return previously fetched value incase of Network failures.

Custom condition You can pass the value for custom conditions using the below snippet.

import { Apptics, AppticsRemoteConfig} from '@zoho_apptics/apptics-react-native';

AppticsRemoteConfig.setCustomCondition("condtionKey", "conditionValue")

Remote Logger

Remote Logger helps you to receive real time application logs from your app and debug issues remotely. Only send logs to Apptics servers from release builds, logs in debug builds will only be printed on the console.

Remote Logger is disabled by default, use the below snippets to enable/disable or get the current status.

import {Apptics, APLogger, APLogLevel} from '@zoho_apptics/apptics-react-native';

// to enable logger
APLogger.enable();

// to disable logger
APLogger.disable();

// to get the current status
APLogger.isEnabled();

You can use the below methods to send logs to Apptics

import {Apptics, APLogger, APLogLevel} from '@zoho_apptics/apptics-react-native';

let prop = {'Plan': 'Premium'};

APLogger.log("log from verbose testing", ["mango", "apple"], prop);
APLogger.debug("log from debug");
APLogger.info("log from info");
APLogger.warn("log from warn");
APLogger.error("log from error");

Filename and method name captured will be obfuscated.