To use the API calls of Aternity Android Mobile SDK in your Android app, you must first initialize the SDK. You can activate it either when the app launches or any other time using the init method in the Aternity Android SDK. This article focuses on the init method in particular. To view the broader picture of integrating the Aternity Android SDK into your app, which includes initialization, see Integrate and Initialize the Aternity Android SDK into your App.

For example, you can activate the Mobile SDK at launch or later on, after the UI of your app has loaded, so you can configure its settings dynamically and start the data reporting to Aternity without delaying the UI.

The Aternity class provides the getInstance method which returns a singleton object. You should call the class's methods using the singleton object, to avoid manually creating and maintaining the Aternity object.

For example:

Aternity.getInstance().init(this, R.raw.aternity);

where this refers to the standard Android app's context object, and R.raw.aternity is ID of aternity.conf configuration file in the res\raw folder.

For backward compatibility only, the API also maintains an initialization with several prescribed arguments. For more information on these legacy methods, see the API documentation from previous versions.

Before You Begin

Before you begin, ensure you have already done the following:

• To run a monitored app, the device must have the following operating systems:

  Attribute	Requirement
  Android operating system of monitored device	Android 4.4 and up to Android 9

• Integrate and initialize the Aternity Android SDK into your app development environment. For details, see Integrate and Initialize the Aternity Android SDK into your App

• Your development project must reference the aternity_sdk.jar file as a library.

• Whenever a class uses the Aternity Android SDK API methods, you must add the statement:

  import com.aternity.sdk.Aternity;

• Add the following recommended permissions to the AndroidManifest.xml file in your project to benefit from the full range of Aternity features:

  • INTERNET enables the app to access the Aternity Aggregation Server (mandatory).

  • GET_ACCOUNTS enables the app to report the device name.

  • ACCESS_COARSE_LOCATION enables the app to report the device's location coordinates. This requires UseLocation in the conf file to be set to true.

  • ACCESS_WIFI_STATE enables the app to report its IP address to determine if the device is on site or off site.

  • ACCESS_NETWORK_STATE enables the app to report if the device is connected via WiFi or cellular network connection, and to report the mobile signal strength.

  Add the permissions before the <application> tag, using the following syntax:

  <uses-permission android:name="android.permission.INTERNET"/>
  <uses-permission android:name="android.permission.GET_ACCOUNTS"/>
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

  

Declaration

There are several versions of the init method in the Aternity Android SDK.

To call init with reference to a configuration file, either pass the ID of the aternity.conf file in your project, when you know all the settings at build time, or pass a pathname to the configuration file to dynamically define the settings at run time.

InitResult init(Context context, int configResourceId);

InitResult init(Context context, String configPath);

Parameters

The init method takes two parameters: context and either configPath or configResourceId.

Configure the monitoring settings in the aternity.conf file, written in plain text JSON format. For example:

For on-premise deployments:

{
    "Server": "https://myserver.com",
    "UseLocation": "true"
}

http[s]://AggSrv_IP_or_Name[:Agg_port],[user]:[password]@ProxySrv_IP_or_Name:Proxy_port

• AggSrv_IP_or_Name is the address of the Aggregation Server, after going via the proxy server.

• Agg_port is the (optional) port number for accessing the Aggregation Server.

• user and password represent the (optional) sign in required to gain access to your proxy server.

• ProxySrv_IP_or_Name is the address of your proxy server.

• Proxy_port is the (mandatory) port to access the proxy server. Use 80 for unsecured http, or 443 for a secured https access to the proxy server.

Return Value

InitResult is type enum, and can have one of the following values:

• OK if it succeeded to load and parse the configuration file.

• CONFIGURATION_LOADED_WITH_WARNINGS if it succeeded to load the configuration file, but found some invalid values (and uses the default values instead).

• CANNOT_LOAD_CONFIGURATION, if the configuration file does not exist or is not readable.

• INVALID_CONFIGURATION_CONTENT if the configuration file does not contain a proper JSON format.

Example

For example, to initialize the Aternity Android SDK when the app launches, you can override the onCreate method from the app's Application class to add the init at the end of the method.

import com.aternity.sdk.Aternity;

public class MyApplication extends Application {
@Override
public void onCreate() {
   super.onCreate();
   Aternity.getInstance().init(this, R.raw.aternity);
   }

The following example illustrates how to verify the successful initialization of the Aternity Android SDK:

//Verify successful Aternity initialization
switch(Aternity.getInstance().init(getContext(), R.raw.aternity))) {
       case OK:
    //succeeded
      break;

  case CONFIGURATION_LOADED_WITH_WARNINGS:
    //handle warning
       break;

  //SDK failed to initialize
  case CANNOT_LOAD_CONFIGURATION:
  case INVALID_CONFIGURATION_CONTENT:
    //handle error
       break;
}