Initialize the Aternity Android SDK Manually (init)

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.

Note

In this example, if you delay the initialization of the Mobile SDK, it would impact on the app's reported launch times.

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.

Tip

(Android only) To monitor the wait times and usage times to display the UXI, you must also wrap the app.

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 or later.

  • 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"/>
    Add required permissions to AndroidManifest.xml

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.

Parameter Type Description
context

Android app Context object

Specify the object performing this operation (usually the app's Application object or the app's Activity object).

configResourceId

integer

(Only if you add the configuration file to the development project.) Specify configResourceId as the ID of the aternity.conf file in the resource folder. For example, R.raw.aternity.

configPath

string

(Only if your configuration file is an external file, for example if you update its settings dynamically.) Specify configPath as a string of the pathname to the file. For example, "/sdcard/custom.json"

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

For Aternity SaaS deployments:

{
    "AccountKey": "ABCD1234567890",
    "Server": "https://aggregation.aternity.com",
    "UseLocation": "true"
}
Note

You can set most of the configuration settings centrally in Aternity, and update them without requiring you to distribute an updated version of the app. We therefore recommend to define the settings which define the app usage locally on the device side: username, device name, location site name. You also need to specify your company's account key (for Aternity SaaS deployments) or Aternity Aggregation Server address (for on-premise deployments) so you can access your data reported to Aternity.

Field Description
AccountKey (Aternity SaaS deployments only)

(Aternity SaaS only) This value is the account ID for your company, which you received from Customer Services.

Server (on-premise deployments only)

For Aternity on-premise, specify the full address of the Aternity Aggregation Server, including its protocol (mandatory) and port (optional). For example, "https://aggserver.company.com:443"

UseLocation

Set this value to true for apps which report their location.

(Aternity on-premise only) If the app connects to your Aggregation Server via a proxy server, enter the server name then the proxy server name in the following format:
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;
}