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.
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"/>
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 on-premise deployments:
{
"Server": "https://myserver.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;
}