Introduction
The embedded agent is a bridge between your application and the App47 service. It provides an easy-to-use API for recording session times and durations, log messages, and performance events. Once you've added your Android app to the App47 Dashboard, be sure to record the App ID as it will be used to configure the agent after installation.
Android Agent Version 2
Note: If you are using a version prior to 2.0, please consult the Android Agent 1.X for additional information. In addition, please upgrade at your earliest convenience to the latest Android agent.
Required steps:
Each of the steps below are further explained in the corresponding sections below.
- Download the embedded agent
- Add build dependency on EmbeddedAgent.jar
- Add embedded agent services to AndroidManifest.xml
- Set your app up to capture events
- Configure embedded agent
Optional steps:
-
Update Other Agent Configuration Settings on Server
- Add logging statements to your app
- Add timed events to your app
- Add generic events to your app
- Use Configuration groups in your app
- Automatically require app upgrades
The Required Steps -- Explained
1. Download the Embedded Agent
- Download the embedded agent zip file from the Resource Center.
- Once you have downloaded the file, open the zip file and you should see the following files:
File | Description | Required? |
---|---|---|
EmbeddedAgent.jar | jar file that contains the EmbeddedAgent | Yes |
EmbeddedAgentConfig.xml | Additional settings for configuring the embedded agent. | No |
ManifestExample.xml | Shows you how to configure your AndroidManifest.xml to use the Embedded Agent | No |
android-support-v4.jar | Used for LocalBroadcastManager events | Yes |
- Include the Embedded Agent library into your project
- Copy the EmbeddedAgent.jar file to the directory in your project that contains libraries. It is the {PROJECT}/libs in our example.
2. Add Build Dependency on EmbeddedAgent.jar
When using IntelliJ:
- Right click your app’s module, choose Open Module Settings.
- Go to the Dependencies tab, then click Add….
- Then choose Single-Entry Module Library.
- Choose the EmbeddedAgent.jar from the file tree that appears.
- Click on OK when finished.

When using Eclipse:
- Right click your app project’s folder, then choose Build Path-->Add External Archives.
- Choose the EmbeddedAgent.jar from the file tree that appears. Click Open once done.

3. Add Embedded Agent Services to AndroidManifest.xml
The embedded agent library requires services that run in the background to process network calls and file caching. In order for a service to be called in an Android Application, it must be declared in the project’s AndroidManifest.xml, within the file’s application tag.
The required Service Declarations are:
<service android:enabled="true" android:name="com.app47.embeddedagent.AgentConfigService"/> <service android:enabled="true" android:name="com.app47.embeddedagent.AgentSessionService”/> <service android:enabled="true" android:name="com.app47.embeddedagent.AgentEventService"/>
The agent also requires two permissions to be declared in your manifest: INTERNET and ACCESS_FINE_LOCATION.
-
INTERNET is required, as the agent can’t make any server calls without it.
-
ACCESS_FINE_LOCATION is only required if you wish to include location information to your agent data.
<uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
The AndroidManifest.xml used by MyApp:
<?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example" android:versionCode="1" android:versionName="1.0"> <uses-sdk android:minSdkVersion="8" /> <application android:icon="@drawable/icon" android:label="@string/app_name"> <activity android:name=".MyActivity" android:label="@string/app_name"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> <service android:enabled="true" android:name="com.app47.embeddedagent.AgentConfigService"/> <service android:enabled="true" android:name="com.app47.embeddedagent.AgentSessionService"/> <service android:enabled="true" android:name="com.app47.embeddedagent.AgentEventService"/> </application> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> </manifest>
4. Set your App Up to Capture Events
In order to function, the embedded agent has to know when particular events are triggered in your Activity’s lifecycle.
There are two ways to configure this:
-
Extend EmbeddedAgentActivity
-
Use EmbeddedAgent.onResume() and EmbeddedAgent.onPause()
Extending Embedded Agent Activity
When you create an Activity of your own, it extends the Activity class. The easiest way to set up the embedded agent required events is to extend EmbeddedAgentActivity class from your Activity classes, instead of the SDK-based Activity class.
For example, this class:
public class MyActivity extends Activity{ //fields... public void onCreate(Bundle savedInstanceState){ super.onCreate(savedInstanceState); //do setup.... } //more implementation.... }
will become:
import com.app47.embeddedagent.EmbeddedAgentActivity; public class MyActivity extends EmbeddedAgentActivity{ //fields... public void onCreate(Bundle savedInstanceState){ super.onCreate(savedInstanceState); //do setup.... } //more implementation.... }
Using EmbeddedAgent.onResume() and EmbeddedAgent.onPause()
If you use a specialized Activity type, such as ListActivity, PreferencesActivity, or even your own custom Activity, you can still set up your Activity using the onResume and onPause functions provided by EmbeddedAgent.
In your Activity’s protected void onResume method, add the line "EmbeddedAgent.onResume(getApplicationContext());" directly after the call to super.onResume.
In your Activity’s protected void onPause method, add the line "EmbeddedAgent.onPause(getApplicationContext());" directly after the call to super.onPause. This will set up your activity to use the Agent correctly.
For example, this class:
public class MyActivity extends ListActivity{ //fields... protected void onResume(){ super.onResume(); //Setup your app for Resume } protected void onPause(){ super.onPause(); //Setup your app for Pause } //more implementation.... }
will become:
import com.app47.embeddedagent.EmbeddedAgent; public class MyActivity extends ListActivity{ protected void onResume(){ super.onResume(); EmbeddedAgent.onResume(getApplicationContext()); //Setup your app for Resume } protected void onPause(){ super.onPause(); EmbeddedAgent.onPause(getApplicationContext()); //Setup your app for Pause } //more implementation... }
5. Configure Embedded Agent
The simplest way to configure the agent is to include the com.app47.embeddedagent package and use the configureAgentWithAppID method using the App ID obtained from the App47 Web application.
Note: This method will assume intelligent default configuration values for various aspects of the agent framework. Regardless, if you use the method configureAgentWithAppID, this will record session start, duration, location and capture relevant device and app information.
import com.app47.embeddedagent.*; public class MyActivity extends EmbeddedAgentActivity{ //fields... public void onCreate(Bundle savedInstanceState){ super.onCreate(savedInstanceState); EmbeddedAgent.configureAgentWithAppID (getApplicationContext(),“4d556ab4530a69fb4b000002”); //do setup.... } //more implementation.... }
The Agent can load the application ID from an XML value in one of your Resource files included in your project. You can either include the provided EmbeddedAgentConfig.xml file in your res/values/ directory, or add string elements listed below to any existing XML value file:
Name | Description | Default | Required? | Valid Values |
---|---|---|---|---|
EmbeddedAgent_applicationID | The App ID provided in your dashboard. | None | Yes | Valid App ID from your account |
Regardless, if you use the method configureAgentWithAppID, this will record session start, duration, location and capture relevant device and app information.
import com.app47.embeddedagent.*; public class MyActivity extends EmbeddedAgentActivity{ //fields... public void onCreate(Bundle savedInstanceState){ super.onCreate(savedInstanceState); EmbeddedAgent.configureAgent(getApplicationContext()); //do setup.... } //more implementation.... }
The Optional Steps -- Explained
Update Other Agent Configuration Settings on Server
The other settings for the Agent are configured on the server from the App/Edit settings in the Agent tab. This allows for dynamic configuration of the Agent instead of settings being put in the resources or part of the configuration API call in code. Changes to settings will be acquired by the app the next time a configuration update is done, if you always want the app to have the latest settings set Agent Check in frequency to Every time.
Add Logging Statements to your App
Additional level logging can be added to your app to capture debug, info, warn, error, and crash log information. Log information is recorded locally and then uploaded to the service the next time the application resumes the active state or is started.
Examples of logging statements:
import com.app47.embeddedagent.*; public class MyActivity extends EmbeddedAgentActivity{ //fields... public void onCreate(Bundle savedInstanceState){ super.onCreate(savedInstanceState); EmbeddedAgent.configureAgent(getApplicationContext()); //Info level log statement EmbeddedAgentLogger.i(“Agent told to configure”); //do setup.... //Debug level log statement EmbeddedAgentLogger.d(“Finished creating activity”); } public void doSomeThing(String param, String anotherParam) { //can overload methods with tags for additional search criteria in //the web app EmbeddedAgentLogger.i(“doing something”, “doing”, param,anotherParam); try{ openFileInput(param); }catch(IOException e){ //can pass a Throwable to add to log EmbeddedAgentLogger.e(“doSomeThing no file found”,e); } }
The Logger methods follow the Android Log class:
-
d - Debug
-
i - Info
-
w - Warn
-
e - Error
-
wtf - What a Terrible Failure (Crash)
Add Timed Events to your App
Timed events allow you to measure and record events in your application along with the duration of the event. Timed events are sent to the service immediately upon completion. If the agent is unable to send the event immediately, it is cached locally and then sent at the next App startup or activation. A simple example of using timed events in your application would look like the following code:
public void performMyTransaction() { String eventID = EmbeddedAgent.startTimedEvent(“Transaction"); // Perform some business logic to complete the transaction // … // EmbeddedAgent.endTimedEvent(eventID); }
Add Generic Events to your App
Generic events are like timed events, but with no duration. Generic events are sent to the service immediately upon request. If the agent is unable to send the event immediately, it is cached locally and then sent at the next App startup or activation.
A simple example of using generic events in your application would look like the following code:
public void performMyTransaction() { EmbeddedAgent.sendGenericEvent(“Transaction"); // Perform some business logic to complete the transaction // … // }
Use Configuration Groups in your App
Configuration groups allow you to set a collection of key value pairs through the main web interface that are then downloaded by the agent at initial startup, and then subsequently at a frequency set by the “EmbeddedAgent_configurationUpdateFrequency” parameter in the EmbeddedAgentConfig.xml file. Configuration items must be requested by a group name and key name. A default value may be given to be used in the event that the configuration group does not contain an item with the requested key name. If a default value is not given, and the key does not exist in the group, the value null is returned. Configuration groups can be assigned to agents based on App version, OS version and platform.
A simple example of using configuration groups in your application would look like the following code:
public void myMethod() { String prodURL = EmbeddedAgent. configurationStringForKey(“server_url", “prod_urls”, “http://default.url”); // Do something with the prodURL value // … }
Automatically Require App Upgrades
You can force users of an App that contains the App47 Agent to upgrade to a minimum App version.
In order to enforce this feature on Apps, you must got to the security screen from within the App47 dashboard. You will see a screen that looks like this:
From here, you can select a particular platform and environment to enforce – for example, you can select Android Test instances be on version 1.5. Additionally, you can set a custom message that a user will see upon an App upgrade notice.
Android Agent requirements
In order for the App upgrade process to work smoothly, you must do a few things. Namely, you'll have to add one new permissions to your App's manifest file.
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
There is a dialog that pops up to inform the user of this feature; therefore, you'll need to add the following Activity to your App's manifest as well:
<activity android:label="@string/app_name" android:name="com.app47.sdk.util.UpgradeDialogActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar"/>
Test Environment settings
If you include an array of allowed UDIDs for a particular app in its manifest file, the App47 system will treat the app as a test version (i.e. this is a mirroring feature of standard iOS behavior w/r to ad hoc builds and provisioning certificates). For instance, if you include the following XML array of values in any values XML file in your app, the agent, at runtime, will determine this instance of the app to be a test version:
<string-array name="allowed_udids"> <item>some device UDID</item> <item>some other device UDID</item> </string-array>
Note, the attribute value of allowed_udids
is required.
Listening for Agent Configured Event
When the configuration for an Agent is updated, a new Intent is created dubbed “agent-config” – you can listen for it and act accordingly when you receive the event. For example, if you use configuration values, you can listen for this event and then grab values you may require. Note, this event becomes important in frameworks like PhoneGap and Appcelerator where Agent configuration can take a few moments.
You'll need to register a BroadcastReceiver. You can do this like so:
// handler for received Intents for the "agent-config" event private BroadcastReceiver mMessageReceiver = new BroadcastReceiver() { public void onReceive(Context context, Intent intent) { //things are broadcasted only on update so this code will execute then... } }; //somewhere else in your code: // Register mMessageReceiver to receive messages. LocalBroadcastManager.getInstance(this).registerReceiver(mMessageReceiver, new IntentFilter(EmbeddedAgent.AGENT_CONFIGURATION_COMPLETE_BROADCAST));
Note that you can statically import EmbeddedAgent.AGENT_CONFIGURATION_COMPLETE_BROADCAST like so:
import static com.app47.embeddedagent.EmbeddedAgent.AGENT_CONFIGURATION_COMPLETE_BROADCAST;
And then your code is less verbose:
LocalBroadcastManager.getInstance(this).registerReceiver(mMessageReceiver, new IntentFilter(AGENT_CONFIGURATION_COMPLETE_BROADCAST));
You can also listen for configuration group changes via CONFIG_GROUPS_COMPLETE_BROADCAST. This is the same as the code above, just a different broadcast name. This broadcast is sent when any configuration group changes.
Releases
-
Agent with dynamic configuration.
Comments
0 comments
Please sign in to leave a comment.