Android (with JDK) version

1. The Appreneur Android SDK runs on Android SDK Version 14(User Version 4.0 ICE_CREAM_SANDWICH) or later. Your app should be built on JDK Version 1.7 or later.

We support to install the SDK using Gradle or manually process. If you would like to integrate the Appreneur SDK into your app, you need to perform a few basic tasks to prepare your Android Studio project.

Installing with Gradle

1. Update your project’s top-level build.gradle script to include the Appreneur Maven repository.

   repositories {
     jcenter()
     maven { url 'https://appreneur.nestpia.com/maven' }
   }

2. In your project's app-level build.gradle, add dependencies for the Appreneur SDK

   dependencies {
     compile 'com.nxstinc:appreneur:1.1.+'
   }

Manual Installation

1. Download the Appreneur Android SDK HERE.
2. Copy com.nxstinc.appreneur-<version>.jar into your Android project’s libs directory

   Copy Path : <project home>/libs/. <Project home> is the folder created by Project Name.

1. If you want to just obfuscate your codes, you should exclude the Appreneur SDK from your obfuscation. Because, All variables of the SDK is accessing by reflection then it will not be worked well by obfuscation.

   To exclude the SDK from obfuscation use the following configuration.

   You must add two lines in proguard-rules.pro file.

   -keep interface com.nxstinc.** { *; }
   -keep class com.nxstinc.** { *; }

How does it configure?

Please make sure you understand the exact feature of each API before disabling it as this may have a drastic effect on the Appreneur analytic services. The API group of the Appreneur SDK for collecting user data is listed below.

appreneur.config

Default setting of Appreneur config file

{
    "clientKey" : "1516696551599133398",
    "autoTrackForm" : true,   // Set Auto tracking
    "useUncaughtException" : true,   // Set the Crash errors tracking
    "useTrackActivity" : true,   // Set the Form tracking
    "useTrackFragment" : true,   // Set the Fragment form tracking
    "useTrackDialog" : true,   // Set the Dialog form tracking
    "useTrackEvent" : true,   // Set the UI Events tracking
    "useTrackPurchase" : true,   // Set the In-App Purchase events tracking
    "useTrackPayment" : true,   // Set the Payment events tracking
    "useTrackAccount" : true,   // Set the user profile data tracking
    "useTrackError" : true,   // Set the Handled Exception Errors tracking
    "useTrackAdImpression" : true,   // Set the Ad impression events tracking
    "useTrackAdClick" : true,   // Set the Ad click events tracking
}

Plug in the Config file into your app project. Follow the process below.

1. Download the Appreneur config file HERE or directly from the Appreneur console. To download from the console, go to Setting\Applications and download from the Edit screen of your registered app.
2. Copy the appreneur.config file in the <project home>/src/assets directory. If there are no assets subdirectory under src, create an assets directory first and copy it.

   If this process is successful you can see the project file structure in the Android Studio, as shown below.

   

   Set project files on the Android Studio

In the mobile application environment, user behaviors can be tracked through Forms and Events. Android Apps have a least one activity and fragment for all device activities and most apps have several. The Appreneur SDK tracks Activity, Fragment, and Dialog form classes to get activity data from user devices.

Firstly, You should change the tracking property of form in the Appreneur configuration. Go to the appreneur.config file in your project and change the default value from “True” to “False” in the "autoTrackForm" : "true". True means that form data will be automatically collected by Appreneur. False means that the user will manually track this value through a separate independent API.

You should add the Appreneur package under any existing imports in related classes

Where / when MUST call this API in all Activity classes defined as “form” of your app. The form means display screens shown to users when navigating through the app. Make the following changes to Activity.onCreate method clauses. How to

1. Create the tracker instance in the Activity.onCreate method clauses.
2. To start the tracking process, MUST call the create() method and start() method simultaneously (such as in the case below tracker = NForm.create().start()).

tracker = NForm.create("Main", this, savedInstanceState).start();

Call APIs for starting tracking process

import com.nxstinc.appreneur.NForm;

public class MainActivity extends Activity {
    private NForm tracker;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        tracker = NForm.create("Main", this, savedInstanceState).start();

         //
        setContentView(R.layout.activity_main);
    } 

There are two ways to allocate the Activity Tracking objects. Choose one of the below and allocate an object. The return value is the tracker object.

1. Allocate an object by setting form names.

   Package	com.nxstinc.appreneur
   Class	NForm
   public static NForm create( @NonNull String name, @NonNull android.app.Activity activity, @Nullable android.os.Bundle savedInstanceState )

   You should call this method if your app code is encrypted with the [Code Obfuscation]

2. Allocate an object by using the class name of each Activity.

   Package	com.nxstinc.appreneur
   Class	NForm
   public static NForm create( @NonNull android.app.Activity activity, @Nullable android.os.Bundle savedInstanceState )

API structure to start tracking process

public NForm start()

Allocating an object has always been paired with start() method to track Activities.

Form tracking based on fragment

Some Android applications have one more fragment in the UI structure. In this case of the fragments, we have to track the fragment forms in a different way. In addition to tracking Activity forms, you should also integrate the Fragment API for tracking exact forms in your app.

Where / when MUST call this API in all Fragment classes defined as “form” of your app. The form means display screens shown to users when navigating through the app. Make the following changes to Fragment.onCreate method clauses. How to

1. Allocate the tracker instance in the Fragment.onCreate method clauses.
2. To start tracking process, MUST call the create() method and start() method simultaneously (such as in the case below tracker = NFragment.create().start()).

tracker = NFragment.create(this, savedInstanceState).start();

Call APIs for starting tracking

import com.nxstinc.appreneur.NFragment;

public class MyFragment extends Fragment {
   private NFragment tracker;

   @Override
   public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
      tracker = NFragment.create(this, savedInstanceState).start();

      // Inflate the layout for this fragment
      View view = inflater.inflate(R.layout.fragment_blank, container, false);
      return view;
   }

There are two ways to allocate Fragment Tracking objects. Choose one of the below and allocate an object. The return value is the tracker object.

1. Allocate an object by setting form names.

   Package	com.nxstinc.appreneur
   Class	NFragment
   public static NFragment create( @NonNull String name, @NonNull android.app.Fragment fragment, @Nullable android.os.Bundle savedInstanceState )

   You should call this method if your app code is encrypted with the [Code Obfuscation]

2. Allocate an object by using the class name of each Fragment.

   Package	com.nxstinc.appreneur
   Class	NFragment
   public static NFragment create( @NonNull android.app.Fragment fragment, @Nullable android.os.Bundle savedInstanceState )

   API structure to start tracking process

   Package	com.nxstinc.appreneur
   Class	NFragment
   public NFragment start()

   Allocating an object has always been paired with start() method to track Fragments.

Form Flow Tracking on the Activity Path

The UI structure of Android apps varies in composition. If your application has the Master/Detail composition structure or Activity/Fragment changes frequently, it might be able to cause errors in tracking connections from Activity(correctly "form") to Activity. To prevent this issue in advance, use this API.

If your Application has a single view composition structure and independent Activities(forms), you do not need to use this API.

Where / when Call this API whenever an event occurs in the startActivity method clause to open a new Actvity. How to Call the tracker.trackIntent() when the onClick() method is called to open a new form in your application. At the time of calling this API, you MUST set the Inent argument into this API.

Call APIs to open a new Activity

button_next.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View view) {
        Intent i = new Intent(MainActivity.this, Main2Activity.class);
        tracker.trackIntent(i);
        startActivity(i);
    }
});

Activity connection API structure

public void trackIntent(@NonNull android.content.Intent intent)

Where / when Call this API whenever the dialog forms are opened by the Event Listener in related Dialog classes. How to

1. Create NDialog dialogTracker = tracker.dialog() Dialog Form Instance into the Dialog class
2. Call dialogTracker.start() method to start the tracking
3. Whenever the dialog form closes, MUST call dialogTracker.destroy() method.

Call APIs for dialog form tracking

button_purchase.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View view) {
        final NDialog dialogTracker = tracker.dialog("PurchaseDialog");

        AlertDialog.Builder builder = new AlertDialog.Builder(Main2Activity.this);
        builder.setMessage("Purchase Dialog")
                .setPositiveButton("OK", new DialogInterface.OnClickListener() {
                    public void onClick(DialogInterface dialog, int id) {
                        dialogTracker.trackPurchase("item-1", 1, 0.99);
                        dialogTracker.trackEvent("OK");
                    }
                })
                .setNegativeButton("Cancel", new DialogInterface.OnClickListener() {
                    public void onClick(DialogInterface dialog, int id) {
                        dialogTracker.trackEvent("Cancel");
                    }
                });
        AlertDialog dialog = builder.create();
        dialog.setOnDismissListener(new DialogInterface.OnDismissListener() {
            @Override
            public void onDismiss(DialogInterface dialogInterface) {
                dialogTracker.destroy();
            }
        });

        dialogTracker.start();
        dialog.show();
    }
});

The structure of objects and APIs for dialog form tracking is as follows.

1. Allocate an object by setting the dialog screen names.

   Package	com.nxstinc.appreneur
   Class	NForm
   public NDialog dialog( @NonNull String name // Dialog name )

2. Start tracking API structure

   Package	com.nxstinc.appreneur
   Class	NDialog
   public NDialog start()

3. Close tracking API structure

   Package	com.nxstinc.appreneur
   Class	NDialog
   public void destroy()

Every time the dialog forms are closed in your application, you MUST call this destroy() method to prevent memory crashes.

Where / when Whenever an event occurs in all forms, this API should be called into the event handling method clause of all UI classes. And then, the event tracking process starts immediately on the form. How to Call tracker.trackEvent() method into the event handling method clause(such as in the case below onClick(View view))

Call API for event tracking

button_event.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View view) {
        tracker.trackEvent("button_event click");
    }
});

Event API structure

public void trackEvent(
@NonNull String eventId //event separator 
)

This API is only used for In-App Purchase transactions made with Google Pay and Apple Pay.

Do not use this API for In-App Purchases paid with debit/credit cards, or Paypal, etc.

Where / whenCall this API into the event handler method clause at the time of transaction completion. How to

1. Call tracker.trackPurchase(name, count, amount) method in the transaction event method clause at the time of In-App Purchase transaction completion.
2. Set the argument value with the transaction counts and amounts into this API.

Call API for In-App Purchase Revenue Tracking

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_CODE) {
        int responseCode = data.getIntExtra("RESPONSE_CODE", 0);
        String purchaseData = data.getStringExtra("INAPP_PURCHASE_DATA");
        String dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE");

        if (resultCode == RESULT_OK) {         
            tracker.trackPurchase("item-1", 1, 0.99);
            ...
        }
   }
}

In-App Purchase API Structure

public void trackPurchase(
@NonNull String name, 
int count, 
double usd
)

This API is only used for all Payment transactions made with including subscription payments, trading events, and payments with credit/debit/Paypal, etc.

Do not use this API for Payment paid with Google Pay and the Apple Pay.

Where and when Call this API into the event handler method clause at the time of the transaction completion How to

1. Call tracker.trackPayment(name, count, amount) method in the transaction event method clause at the time of Payment transaction completion.
2. Set the argument value with the transaction counts and amounts into this API.

Call API for Payment Revenue Tracking

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == PAYPAL_REQUEST_CODE) {
            //If the result is OK
            if (resultCode == Activity.RESULT_OK) {
                tracker.trackPayment("item-1", 1, 0.99);
            }
        }
    }

Payment API structure

public void trackPayment(
@NonNull String name, 
int count, 
double usd
)

These APIs are used for collecting impression data and click data from advertisements served in your app.

If your app does not have 3rd party advertising SDK or has In-house Ads, you do not need to integrate this API. This API is only for Ad Revenue tracking purpose.

Where / whenCall the Appreneur Ad Impression/Click APIs in the method clause whenever the Impression/Click event handler method of 3rd party Ad SDK API is called. How to

1. Call tracker.trackAdImpression() method into impression event handler method clauses of 3rd party Ad SDK.
2. Call tracker.trackAdClick() method into click event handler method clauses of 3rd party Ad SDK.

Call API for Ad Revenue Tracking

 mAdView.setAdListener(new AdListener() {
    @Override
    public void onAdLoaded() {
        tracker.trackAdImpression();
    }
    @Override
    public void onAdFailedToLoad(int errorCode) {
    }
    @Override
    public void onAdOpened() {
        tracker.trackAdClick();
    }
    @Override
    public void onAdLeftApplication() {
    }
    @Override
    public void onAdClosed() {
    }
});

Ad Revenue APIs structure

1. Ad Impression count API

   Package	com.nxstinc.appreneur
   Class	NForm
   public void trackAdImpression()

2. Ad Click count API

   Package	com.nxstinc.appreneur
   Class	NForm
   public void trackAdClick()

This API is used to analyze arguments of the exception handling errors defined by app developers. The supported argument type is String or Throwable/Exception. This API categorizes errors and argument type by UI and Non-UI sections. In Java, the Throwable class is the superclass of all errors and exceptions. With proper handling of throwable class, you can pinpoint why certain errors occur. That’s why Appreneur provides you with another error tracking API method for throwable/exception. The supported argument type for this API is Throwable/Exception.

Handled UI Exception Errors

Where / when Call this API in handled exception clause whenever exception errors occur in Activity / Fragment classes How to

1. Call tracker.trackError("ERROR MESSAGE") method in handled exception clause at the time of errors occur.
2. Set the argument value in this method. The error message argument type is string only.

Argument Type of Handled UI Exception Error API

if (error != 0) {
    tracker.trackError("error != 0");
}

Handled UI Exception Error API structure

public void trackError(
@NonNull String error
)

Handled UI Throwable/Exception Errors

This API tracks and analyzes Throwable/Exception errors caused by java.lang.Throwable / java.lang.Exception during application has been running. The supported argument type for this API is Throwable/Exception.

Where / when Call this API in Catch clause for Throwable/Exception Handling whenever errors occur in Activity / Fragment classes. How to

1. Call tracker.trackError(Argument) method in Catch clause at the time of errors occur.
2. Set the argument value in this method. The error message argument type is Throwable/Exception only.

Argument Type of Handled UI Exception Error API

try {
	throw new RuntimeException("MyException");
} catch (Exception ex) {
	tracker.trackError(ex);
	ex.printStackTrace();
}

Argument Type of Handled UI Throwable Error API

try {
	throw new RuntimeException("MyException");
} catch (Throwable th) {
	tracker.trackError(th);
	th.printStackTrace();
}

Throwable/Exception Error API structure

public void trackError(
@NonNull Throwable throwable
)

Handled Non-UI Exception Errors

This API is for Non-UI relevant error tracking like network errors which may happen on asynchronous tasks. The supported argument type is the string only.

Where / When Call this API in handled exception clause whenever exception errors occur in non-UI section How to

1. Call NErrorTracker.trackError("ERROR ID", "ERROR MESSAGE") in handled exception clause at the time exception errors occur.
2. Set argument value in this method. The error message argument type is string only.

You should add the Appreneur package under any existing imports in related classes

Argument Type of Handled Non-UI Exception Error API

if (200 == httpConnection.getResponseCode()) {
    instream = httpConnection.getInputStream();
    // ...
} else {
    NErrorTracker.trackError("http", String.format(“status : %d”, httpConnection.getResponseCode()));
}

Call API to handle Non-UI Exception errors

AsyncTask task = new AsyncTask() {
    @Override
    protected Object doInBackground(Object... a) {
        // ...
        try {
            httpConnection = (HttpURLConnection)url.openConnection();
            if (200 == httpConnection.getResponseCode()) {
                // ...
            } else {
                NErrorTracker.trackError("http", String.format("status : %d", httpConnection.getResponseCode()));
            }
        } catch(Throwable throwable) {
            throwable.printStackTrace();
        } finally {
            // ...
        }
        return null;
    }
};

Handled Non-UI Exception Error API structure

public static void trackError(
@NonNull String eventId, // event separator
@NonNull String error
)

Handled Throwable/Exception Errors in the Non-UI Sections

This API is for Non-UI relevant error tracking, specifically for throwable/exception errors like network errors which may happen in the asynchronous task. These are typical errors of Android apps, occurring in java.lang.Throwable and java.lang.Exception. The supported argument type is Throwable/Exception.

Where / when Call this API in the Catch clause whenever Throwable/Exception errors occur. How to

1. Call NErrorTracker.trackError(Argument) method in the Catch clause at the time Throwable/Exception errors occur.
2. Set the argument value in this method. The error message argument type is Throwable/Exception only.

You should add the Appreneur package under any existing imports in related classes

Call API to handle Non-UI Throwable/Exception Errors

AsyncTask task = new AsyncTask() {
    @Override
    protected Object doInBackground(Object... a) {
        // ...
        try {
            httpConnection = (HttpURLConnection)url.openConnection();
            if (200 == httpConnection.getResponseCode()) {
                // ...
            }
        } catch(Exception ex) {
            NErrorTracker.trackError("network", ex);
        } catch(Throwable throwable) {
            NErrorTracker.trackError("network", throwable);
        } finally {
            // ...
        }
        return null;
    }
};

Handled Non-UI Throwable/Exception Error API structure

public void trackError(
@NonNull String eventId,
@NonNull Throwable throwable
)

Crashes / Uncaught Exception Errors

In Android apps, the system error reporting method is the Thread.setDefaultUncaughtExceptionHandler() method. Uncaught exceptions are handled in instances where your app occurred unexpected errors at runtime and are often lethal, causing the app to crash as a result. Uncaught exceptions can be sent to Appreneur System automatically by setting the UncaughtExceptions property to True in the Appreneur.config file. All system exceptions sent using automatic exception measurement are reported as log data in the Appreneur console.

When using automatic reporting of the crash errors, keep the following in mind:

1. All crash exception errors sent using automatic error measurement are reported as log data in the Appreneur SDK.
2. In the Appreneur console, the description field of crash errors is automatically set using the stack trace logs.

Automatic Configuration

To send all uncaught exceptions in your app automatically to Appreneur Analytics, Keep this property value of the configuration file as it is:

"useUncaughtException" : true

After sending an exception using automatic exception measurement, the exception will be passed on to Thread's default exception handler.

This property value can only be set to true for a single SDK in your app. If specified for multiple SDKs, then the last one to be initialized will be used.

Where / when Call this API when it is available to get user profile data How to

1. Call trackAccount(userId, name, photoUrl, gender, yearOfBirth) method in available clause to get the data.
2. Set the Argument Value in this method. The argument type is Nullable, so fill the data fields only.

Argument Value of Custom User Profile API

tracker.trackAccount("userid-1", "Alice", "http://temuri/photo.png", NLog.GENDER_FEMALE, 1980);

Custom User Profile API structure

public void trackAccount(
@NonNull String userId, 
@Nullable String name, 
@Nullable String photoUrl, // http url
@Nullable String gender, //  M (male), F (female), O (other)
@Nullable Integer yearOfBirth // put the year 1980, 2000 
)

Argument details of Custom User Profile API

Where / when Call this API when user profile information is loaded after facebook login. The set argument value type is only object. How to After getting the Return Value the moment facebook user profiles are loaded,

1. Call tracker.trackAccountForFacebookJSONObject(object) method.
2. Set the Return Value as Appreneur API argument value and the set value type as object

Argument Value of Facebook User Profile API

 GraphRequest request = GraphRequest.newMeRequest(
        AccessToken.getCurrentAccessToken(),
        new GraphRequest.GraphJSONObjectCallback() {
            @Override
            public void onCompleted(JSONObject object, GraphResponse response) {
                tracker.trackAccountForFacebookJSONObject(object);
            }
        });
Bundle parameters = new Bundle();
parameters.putString("fields", "id,name,email,picture,gender,birthday");
request.setParameters(parameters);
request.executeAsync();

Facebook User Profile API structure

public void trackAccountForFacebookJSONObject(
@NonNull Object jsonObject
)

The Follow the process below.

1. Set the tracking property AutoTrackForm = True in the appreneur.config file.
2. Declare and call all of the id trackers as NForm tracker = NForm.find(MainActivity.this) in the Appreneur APIs handler method clause.
3. Add if (tracker != null) { tracker.Appreneur APIs call section} clause.

Conversion Form Tracking

button_event.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View view) {
        NForm tracker = NForm.find(MainActivity.this); 
        if (tracker != null)
            tracker.trackEvent("button_event"); 
    } 
});

In case of using the find method, you must check null.

Lookup Instance API structure

public static synchronized NForm find(
@NonNull Object origin // the current activity  or the instance of fragment object
)

Push Message Payload

{
  "data": {
    "tag": "https://appreneur.nestpia.com"
  },
  "notification": {},
  "to": ""
}

How to submit the push information to use push token in your app

import com.nxstinc.appreneur.NFirdbaseCloudMessageTracker;

public class MyFirebaseMessagingService extends FirebaseMessagingService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (NFirdbaseCloudMessageTracker.checkTrackerSelfPushMessage(remoteMessage))
            return;

        handleNow();
        if (remoteMessage.getNotification() != null) {
            Log.d(TAG, "Message Notification Body: " + remoteMessage.getNotification().getBody());
        }
    }

public static boolean checkTrackerSelfPushMessage(
@NonNull com.google.firebase.messaging.RemoteMessage remoteMessage
)

 public class GcmIntentService extends IntentService {
   @Override
   protected void onHandleIntent(Intent intent) {
      Bundle bundle = intent.getExtras();
      if (!NTracker.instance().checkPushMessage(bundle))
         return;
   }