Since: API level 22
public class

NetworkAnalytics

extends Object
java.lang.Object
   ↳ com.samsung.android.knox.net.nap.NetworkAnalytics

Class Overview

This class provides APIs for registration of configuration profiles for the process of collecting network activity meta-data on the device. Knox provides MDM authorized network monitor applications (NPA Clients) to obtain meta-data about networking related activity by applications on the device. This meta-data, which is collected by the framework for every flow that is created on the device for sending and receiving application data over network interfaces, contains data points such as source and destination IP of the flow, the domain associated with the destination IP, time of creation and termination of the flow, number of bytes of data transfered through the flow, name of the process that created the flow, identifier of the application package of the process that created the flow etc.

The network analytics platform accepts configuration information from the MDM agent in the form of a JSON string called profiles. For each profile, the MDM agent provides details about the NPA client it is authorizing to collect data. The framework performs a signature level check of the NPA client when the NPA client requests initiation of the meta-data collection. The NPA client controls the start and stop of the meta-data collection process.
Each profile will also contains an integer value provided as flags. The flags will inform the platform, the meta-data fields that need to be provided to NPA client. The integer values of the flags and the corresponding json key for the value are standardized in NetworkAnalyticsConstants.DataPoints class.

MDM Agents can follow the details provided in the link on how to do the integeration; NetworkAnalytics

NPA Client Agents can follow the details provided in the link on how to the integeration; NetworkAnalytics

The Class Contains API's applicable for both the MDM and the NPA Agents; Please refer to the usage tag to find out the scope and refer to the integeration guide for more details

Since
API level 22
KNOX 2.8

Summary

Public Methods
static NetworkAnalytics getInstance(Context cxt)
API to get the instance of Network Analytics Class;
String getNPAVersion()
API to get the current version of the network analytics framework.
List<String> getNetworkMonitorProfiles()
API to get all registered network monitor profiles.
List<Profile> getProfiles()
API to get all registered profiles by the MDM agents;
int isProfileActivated(String profileName)
API to check if a profile that has been registered by the MDM has been activated.
int registerNetworkMonitorProfile(String jsonProfile)
API to register a network monitor profile with the network analytics platform.
int start(String profileName)
API to start collecting NPA data-points;
int start(String profileName, Bundle data)
API to start collecting NPA data-points at different flow intervals.
int stop(String profileName)
API to stop collecting NPA data-points;
int unregisterNetworkMonitorProfile(String profileName)
API to unregister a previously registered profile.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public static NetworkAnalytics getInstance (Context cxt)

Since: API level 22

API to get the instance of Network Analytics Class;

Returns
  • The API returns the instance of NetworkAnalytics Class; Null is returned if an error is encountered.
Throws
SecurityException If caller does not have required permissions
Usage
This API is applicable only for NPA client app

 try {
     NetworkAnalytics na = NetworkAnalytics.getInstance(this);
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Since
API level 22
KNOX 2.8
Multiuser Environment
User Scope

public String getNPAVersion ()

Since: API level 22

API to get the current version of the network analytics framework.

Returns
  • String value of the version of the framework.
Throws
SecurityException If caller does not have required permissions
Usage
The version will let the caller know about the version of network analytics framework and data points supported by the framework.
This API is applicable for both NPA Client app and MDM agent app
 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(getApplicationContext());
 try {
     NetworkAnalytics na = ekm.getNetworkAnalytics();
     String version = na.getNPAVersion();
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Since
API level 22
KNOX 2.8
Multiuser Environment
User Scope

public List<String> getNetworkMonitorProfiles ()

Since: API level 22

API to get all registered network monitor profiles.

Returns
  • The API returns a list of JSON profile strings that are registered. Null is returned if an error is encountered.
Throws
SecurityException If caller does not have required permissions
Usage
All the profiles that are registered by the MDM client will be returned in the same JSON format as provided to the framework during registration.
This API is applicable only for MDM agent app

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(getApplicationContext());
 try {
     NetworkAnalytics na = ekm.getNetworkAnalytics();
     List<String> returnValue = na.getNetworkMonitorProfiles();
 } catch (SecurityException e) {
    Log.e(TAG, "SecurityException: " + e);
 }

 
For Container:

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(getApplicationContext());
 KnoxContainerManager kmcm = ekm.getKnoxContainerManager(containerID);
 try {
     NetworkAnalytics na = kmcm.getNetworkAnalytics();
     List<String> returnValue = na.getNetworkMonitorProfiles();
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_NPA" permission with a protection level of signature.
Since
API level 22
KNOX 2.8
Multiuser Environment
User Scope

public List<Profile> getProfiles ()

Since: API level 22

API to get all registered profiles by the MDM agents;

Returns
  • The API returns a list of Profile object that are registered. Null is returned if an error is encountered.
Throws
SecurityException If caller does not have required permissions
Usage
This API is applicable only for NPA client app

 try {
     List<Profile> returnValue = na.getProfiles();
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Since
API level 22
KNOX 2.8
Multiuser Environment
User Scope

public int isProfileActivated (String profileName)

Since: API level 22

API to check if a profile that has been registered by the MDM has been activated.

Parameters
profileName The name of the profile as provided in the JSON profile string during registration.
Returns
Throws
SecurityException If caller does not have required permissions
Usage
Activation means that the registered NPA client has called the start API for the profile and is actively recording meta-data for the profile. Activation state is persisted through device reboot.
This API is applicable only for MDM agent app

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(getApplicationContext());
 try {
     NetworkAnalytics na = ekm.getNetworkAnalytics();
     int returnValue = na.isProfileActivated("SAMPLE_PROFILE_NAME");
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
For Container:

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(getApplicationContext());
 KnoxContainerManager kmcm = ekm.getKnoxContainerManager(containerID);
 try {
     NetworkAnalytics na = kmcm.getNetworkAnalytics();
     int returnValue = na.isProfileActivated("SAMPLE_PROFILE_NAME");
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_NPA" permission with a protection level of signature.
Since
API level 22
KNOX 2.8
Multiuser Environment
User Scope

public int registerNetworkMonitorProfile (String jsonProfile)

Since: API level 22

API to register a network monitor profile with the network analytics platform.

Parameters
jsonProfile The profile in the JSON format. An example is shown above.
Returns
Throws
SecurityException If caller does not have required permissions
Usage
This API is called by the MDM agent. Each profile will contain the following information, all of which (except client specific information which is optional) MUST be provided in the JSON file.
This API is applicable only for MDM agent app

1) Profile Name: A unique string to recognize this profile.

2) Package name: The package name of the network monitor application that will perform the network monitoring operation on the device.

3) Package signature: The signature of the network monitor application that will perform the network monitoring operation on the device. This will ensure signature level protection for the process.

4) Flags: An integer value that is created based on the expected values from the Network Analytics platform. A set of supported values can be requested using the logical OR of constants provided in the NetworkAnalyticsConstants class.

5) Client specific information: This information is meant for the network monitoring application and will be passed on to it during the activation stage.

The profile JSON also contains a vendor section which the MDM agent can use to pass NPA client specific configuration information to the framework and the NPA client.

Sample Json File:
 {
  "NETWORK_ANALYTICS_PARAMETERS":{
          "profile_attribute":{
                  "profile_name":"SAMPLE_PROFILE_NAME",
                  "package_name":"com.example.network.monitor",
                  "package_signature":"3aouiydsoa324askdfja7wiejtr10984ajnoqwh........audhf",
                  "flags":65535
           },
          "vendor":{
           }
    }
  }
 

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(getApplicationContext());
 try {
     JSONObject obj = new JSONObject();
     obj.put(NetworkAnalyticsConstants.JSONConstants.PROFILE_NAME,
          "SAMPLE_PROFILE_NAME");
     obj.put(NetworkAnalyticsConstants.JSONConstants.PACKAGE_NAME,
          "com.example.network.monitor");
     obj.put(NetworkAnalyticsConstants.JSONConstants.PACKAGE_SIGNATURE,
          "3aouiydsoa324askdfja7wiejtr10984ajnoqwh........audhf");
     obj.put(NetworkAnalyticsConstants.JSONConstants.FLAGS, 65535);

     JSONObject profileAttribute = new JSONObject();
     profileAttribute.put(
          NetworkAnalyticsConstants.JSONConstants.PROFILE_ATTRIBUTES, obj);

     JSONObject parent = new JSONObject();
     parent.put(NetworkAnalyticsConstants.JSONConstants.PARENT, profileAttribute);

     NetworkAnalytics na = ekm.getNetworkAnalytics();
     int returnValue = na.registerNetworkMonitorProfile(parent.toString());
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
For Container:

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(getApplicationContext());
 KnoxContainerManager kmcm = ekm.getKnoxContainerManager(containerID);
 try {
     JSONObject obj = new JSONObject();
     obj.put(NetworkAnalyticsConstants.JSONConstants.PROFILE_NAME,
          "SAMPLE_PROFILE_NAME");
     obj.put(NetworkAnalyticsConstants.JSONConstants.PACKAGE_NAME,
          "com.example.network.monitor");
     obj.put(NetworkAnalyticsConstants.JSONConstants.PACKAGE_SIGNATURE,
          "3aouiydsoa324askdfja7wiejtr10984ajnoqwh........audhf");
     obj.put(NetworkAnalyticsConstants.JSONConstants.FLAGS, 65535);

     JSONObject profileAttribute = new JSONObject();
     profileAttribute.put(
          NetworkAnalyticsConstants.JSONConstants.PROFILE_ATTRIBUTES, obj);

     JSONObject parent = new JSONObject();
     parent.put(NetworkAnalyticsConstants.JSONConstants.PARENT, profileAttribute);

     NetworkAnalytics na = kmcm.getNetworkAnalytics();
     int returnValue = na.registerNetworkMonitorProfile(parent.toString());
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_NPA" permission with a protection level of signature.
Since
API level 22
KNOX 2.8
Multiuser Environment
User Scope

public int start (String profileName)

Since: API level 22

API to start collecting NPA data-points;

Parameters
profileName The name of the profile as provided in the JSON profile string which is retrieved through @see #getProfiles()
Throws
SecurityException If caller does not have required permissions
Usage
This API is applicable only for NPA client app

 try {
     int returnValue = na.start("SAMPLE_PROFILE_NAME");
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Since
API level 22
KNOX 2.8
Multiuser Environment
User Scope

public int start (String profileName, Bundle data)

Since: API level 26

API to start collecting NPA data-points at different flow intervals.

Parameters
profileName The name of the profile as provided in the JSON profile string which is retrieved through @see #getProfiles()
data Bundle for passing extra information like when the data-points needs to be captured; It will return an error code of ERROR_INVALID_PARAMETERS if null is passed for Bundle type;
Throws
SecurityException If caller does not have required permissions
Usage
This API is applicable only for NPA client app

 try {
     Bundle data = new Bundle();
     data.putString(NetworkAnalyticsConstants.ActivationState.PROFILE_RECORD_TYPE,NetworkAnalyticsConstants.ActivationState.RECORD_TYPE_STOP);    
     int returnValue = na.start("SAMPLE_PROFILE_NAME",data);
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Since
API level 26
KNOX 3.2
Multiuser Environment
User Scope

public int stop (String profileName)

Since: API level 22

API to stop collecting NPA data-points;

Parameters
profileName The name of the profile as provided in the JSON profile string which is retrieved through @see #getProfiles()
Throws
SecurityException If caller does not have required permissions
Usage
This API is applicable only for NPA client app

 try {
     int returnValue = na.stop("SAMPLE_PROFILE_NAME");
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Since
API level 22
KNOX 2.8
Multiuser Environment
User Scope

public int unregisterNetworkMonitorProfile (String profileName)

Since: API level 22

API to unregister a previously registered profile.

Parameters
profileName The name of the profile as provided in the JSON profile string during registration.
Returns
Throws
SecurityException If caller does not have required permissions
Usage
Unregistration of profiles causes the termination of meta-data recording for the profile if it is activated.
This API is applicable only for MDM agent app

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(getApplicationContext());
 try {
     NetworkAnalytics na = ekm.getNetworkAnalytics();
     int returnValue = na.unregisterNetworkMonitorProfile("SAMPLE_PROFILE_NAME");
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
For Container:

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(getApplicationContext());
 KnoxContainerManager kmcm = ekm.getKnoxContainerManager(containerID);
 try {
     NetworkAnalytics na = kmcm.getNetworkAnalytics();
     int returnValue = na.unregisterNetworkMonitorProfile("SAMPLE_PROFILE_NAME");
 } catch (SecurityException e) {
     Log.e(TAG, "SecurityException: " + e);
 }

 
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_NPA" permission with a protection level of signature.
Since
API level 22
KNOX 2.8
Multiuser Environment
User Scope