HP AppPulse Mobile
Setting up Android Apps
Document Release Date: February 2015
Setting up Android Apps
Before you Begin
Before you Begin
l
l
You should have already added an application in HP AppPulse Mobile and downloaded the HP
AppPulse Mobile SDK. For details, see the Getting Started pdf.
You need to have Java Runtime Environment (JRE) 1.7 or higher installed. If you need to install it,
click here.
How to Add HP AppPulse Mobile to Your App
For a quick overview showing this process, watch this video.
1. Within HP AppPulse Mobile, access the application's settings and copy the application key.
2. Open a Windows command line (Start > Run > cmd) and enter the following:
<Unzipped SDK directory>\AppPulse_mobile.bat -appkey <application key>
<path and name of your APK>
For example:
C:\MySDKFiles\AppPulse_mobile.bat -appkey 1knfsdol2d C:\MyAPK\myapp.apk
This command adds HP AppPulse Mobile and your application key to your app. For details about
other options, see " Advanced Options" on the next page.
By default, the new APK is created in the same directory as the original APK, with the suffix
signed.debug.apk. The new APK is signed with a debug key which is the standard for testing and
developing Android mobile apps.
3. Install the new APK on a device or emulator. Run your app, and in a few minutes you'll see data in
HP AppPulse Mobile.
4. When you are ready to upload it, sign the new APK with your private key and upload it to the
Google Play store.
As soon as users interact with your app, HP AppPulse Mobile shows your users' experience in
detail.
HP AppPulse Mobile (1.8)
Page 2 of 9
Setting up Android Apps
Advanced Options
Advanced Options
When you add HP AppPulse Mobile to your app, you can define one or more advanced options as
described in the following section.
To use advanced options, enter the following in the command line:
<Unzipped SDK directory>\AppPulse_mobile.bat -appkey <application key>
<optional parameters> <path and name of your APK>
You can enter the following optional parameters:
Parameter
Description
-o <File path>
By default, the instrumented APK is created in the same directory
as the original APK. Use this parameter to specify a different output
file.
-optIn
By default, user data is automatically reported to AppPulse Mobile.
If you use this parameter, data will not be reported unless users
activate data reporting (opt-in), as defined in your app. For details,
see "Enabling Users to Opt-In/Opt-Out of Data Reporting" on
page 5.
-overrideacra
AppPulse Mobile uses a version of the ACRA library to collect data
on crashes. If your app already uses ACRA, by default AppPulse
Mobile will not show crash data for the app. You can use this flag to
add the AppPulse Mobile ACRA library version and override your
current ACRA library.
Note that this will disable your existing ACRA-based reporting
mechanism, and you will see crash data in AppPulse Mobile.
-sdfile <File path>
Use this parameter to block sensitive data; for details see
"Protecting Sensitive Data" on the next page.
-stacktracesizelimit <n>
By default, crash reports' stacktrace have a size limit of 2 KB. Use
this parameter to modify this limit (possible range: 0-10). Setting a
higher limit will impact network load accordingly.
-tempdir <Temp directory>
HP AppPulse Mobile uses your temp directory to run the
instrumentation. Use this parameter to specify a different temporary
directory.
HP AppPulse Mobile (1.8)
Page 3 of 9
Setting up Android Apps
Advanced Options
Protecting Sensitive Data
To prevent reporting sensitive data such as a button or URL showing an account number, HP AppPulse
Mobile automatically shows *** instead of any sequence of 4 or more of the following elements: 0-9 , .
- (digit, comma, period, hyphen). For example, if your app reports Paid by account 413-57, HP
AppPulse Mobile shows Paid by account ***.
Before adding HP AppPulse Mobile to your app, you can customize the default data masking as
follows:
l
No data masking. If you do not want these strings replaced, open the SDK and delete the file
<Unzipped SDK directory>\ApkInfuser\HPFilter.xml.
Run the default command line described in "How to Add HP AppPulse Mobile to Your App" on
page 2.
l
Change data masking rules. To define specific rules relevant for your particular app, open the
SDK and locate the file <Unzipped SDK directory>\ApkInfuser\HPFilter.xml. This file contains the
default rule, and a template for creating additional rules. Each rule has two parts: <detection string>
<replacement string>. The detection uses regular expressions. You can add as many rules as
needed; each rule is a separate Item node.
Add or edit rules as needed, save the file, and run the default command line described in "How to
Add HP AppPulse Mobile to Your App" on page 2.
l
Use a different xml file. You can create a different XML file using the guidelines described above.
When you run the command line, specify the location of your file with the -sdfile <File path>
parameter.
Note: By default, AppPulse Mobile also masks sensitive URL parameters. For example,
http://www.example.com/customers/orders?username=dave&os=android is reported as
http://www.example.com/customers/orders?username=*&os=*.
HP AppPulse Mobile (1.8)
Page 4 of 9
Setting up Android Apps
Advanced Options
Enabling Users to Opt-In/Opt-Out of Data Reporting
Some apps give each user the ability to avoid sending data from their device, for example using a
Settings menu item (opt-out). Other apps ask users to actively approve data collection, for example
when the app is first launched (opt-in).
By default, data is automatically sent from mobile apps to AppPulse Mobile. You can use the -optIn
parameter to disable default data reporting; in this case data is only collected from users who opt in.
Note that the relevant user interface and interaction within the app are up to the application developer.
To enable or disable reporting from your app to AppPulse Mobile, change the Boolean value “enabled” in
the SharedPreferences “HPUserMonitoring”. The change will take effect the next time the user opens
the app.
For example:
private static final String HP_RUM_API_PREFERENCES_NAME =
"HPUserMonitoring";
private static final String HP_RUM_API_PREFERENCES_ENABLED = "enabled";
public void disableReporting(View view) {
SharedPreferences.Editor spe = getSharedPreferences(HP_RUM_API_
PREFERENCES_NAME, Context.MODE_MULTI_PROCESS).edit();
spe.putBoolean(HP_RUM_API_PREFERENCES_ENABLED, false).commit();
}
public void enableReporting(View view) {
SharedPreferences.Editor spe = getSharedPreferences(HP_RUM_API_
PREFERENCES_NAME, Context.MODE_MULTI_PROCESS).edit();
spe.putBoolean(HP_RUM_API_PREFERENCES_ENABLED, true).commit();
}
HP AppPulse Mobile (1.8)
Page 5 of 9
Setting up Android Apps
Troubleshooting
Troubleshooting
Supported versions
HP AppPulse Mobile supports apps with Android 2.3 (API 9) and higher.
Signing issues
By default, when you add HP AppPulse Mobile to your app the APK is signed in debug mode, which is
the standard for testing and developing Android mobile apps. (This enables you to test the app on a
device but not to upload it to the Google Play store.)
However, some applications require that you sign the app with the original certificate in order to properly
run it on a device. For example, if you use Google Wallet or Google Maps, your app requires the original
certificate. This is also true if your application uses custom permissions that are signature protected, or
if your application explicitly validates signatures.
If you are unable to properly run your app after adding AppPulse Mobile, sign the new APK with your
original certificate.
Obfuscation issues
If your app uses obfuscation, AppPulse Mobile cannot be added to the app if you include the Android
Support Library in the obfuscation process. Make sure it is excluded from obfuscation (for example, for
ProGuard use -keep class android.support.** { *; }).
HP AppPulse Mobile (1.8)
Page 6 of 9
Setting up Android Apps
Troubleshooting
Error messages
The following section lists messages that may appear when adding HP AppPulse Mobile to your app,
with their explanation.
Message:
Explanation:
Instrumentation process was unable to run - Java Runtime
Environment was not found.
l
l
If you do not have JRE 1.7 installed, install it from
http://www.oracle.com/technetwork/java/javase/downloads/jre7-downloads1880261.html.
If you have JRE 1.7 installed but instrumentation still fails, access your
system variables, and open the PATH variable for editing. Verify that the
Java Home is properly defined in the PATH variable; for
example: C:\Program Files\Java\jre7\bin.
After you edit the variable, close the existing command line and open a new
one to continue instrumentation.
Message:
Explanation:
Could not reserve enough space for object heap.
l
l
If you are running JRE 32-bit, install 64-bit if supported by your OS.
If you are running JRE 64-bit, the batch file assigns 2048KB of RAM for this
process. If you need more, access the HP AppPulse Mobile SDK and open
the ApkInfuser.bat file for editing. Locate the string -Xmx2048m and increase
this value as needed, depending on your available system resources.
Message:
Warning: You already have the ACRA library in your application
for monitoring crashes. You can use the -overrideacra flag to
replace your existing ACRA library. In this case, you'll get our
detailed crash reports solution instead.
Explanation:
AppPulse Mobile uses the ACRA library to collect data on crashes. Since your
app is already using ACRA, by default AppPulse Mobile will not collect crash
data for the app.
You can use the -overrideacra flag to add the AppPulse Mobile ACRA library
version and override your current ACRA library.
Message: Warning: Unable to override ACRA because your ACRA is obfuscated.
Crashes will therefore not be reported via our solution.
HP AppPulse Mobile (1.8)
Page 7 of 9
Setting up Android Apps
Troubleshooting
Explanation:
You used the -overrideacra flag to override your current ACRA library, but your
ACRA library is obfuscated (class names are changed). Since you have
customized your ACRA we will not override it, and AppPulse Mobile will not
show your crash data.
Message: Note: You are using the Override ACRA flag to enable AppPulse
Mobile crash reports.
Explanation:
You used the -overrideacra flag to add the AppPulse Mobile ACRA library version
and override your current ACRA library. This disables your existing ACRA-based
reporting mechanism, and you will see crash data in AppPulse Mobile.
Message:
Note: Your application contains some html or javascript
components, which are not yet supported.
Explanation:
The current version of HP AppPulse Mobile does not yet support monitoring of
hybrid components. This capability is coming soon!
Message:
There was a problem in decoding dex file. This application is
obfuscated to avoid post-build instrumentation.
Explanation:
Your app includes bytecode obfuscation techniques that employ "junk byte
injection." Contact HP Support for help with instrumenting your app.
Message:
SEVERE: Incorrect number of arguments, or illegal character used.
SEVERE: The following path was not found: <path>
Explanation:
The command to add HP AppPulse Mobile to your app must contain the
SDK batch location, the application key, and the apk location. Check if your
command is missing one of these, or if any parameter in the command contains
illegal characters (“ ^ < > %).
Message:
Failed to open dex file
Explanation:
The classes.dex file is missing from your original apk, and AppPulse Mobile
cannot be added unless this file exists. Use a zip viewer (like 7-zip) to see if the
classes.dex file exists in your original apk. If it does exist, try to extract this file
only from the original apk. You may see that your anti-virus software deletes it
immediately. In this case, disable the anti-virus before adding AppPulse Mobile
to your app, then re-enable your anti-virus software.
HP AppPulse Mobile (1.8)
Page 8 of 9
Setting up Android Apps
Legal Notices
Warranty
The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be
construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
The information contained herein is subject to change without notice.
Restricted Rights Legend
Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software,
Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.
Copyright Notice
© Copyright 2014-2015 Hewlett-Packard Development Company, L.P.
Trademark Notices
Apple is a trademark of Apple Computer, Inc., registered in the U.S. and other countries.
Google and Android are registered trademarks of Google Inc.
HP AppPulse Mobile (1.8)
Page 9 of 9