Professional Documents
Culture Documents
Adding HP Apppulse Mobile To Your Android App
Adding HP Apppulse Mobile To Your Android App
AppPulse Mobile
If you already closed the window, you can access the application's settings within AppPulse
Mobile and copy the application key from there.
2. Open a Windows command line (Start > Run > cmd), and enter the following:
For example:
You now have a new APK in the same location as the original APK file, 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.
l The above steps are mandatory. For other options, including parameters you can use to sign
the APK with your private key, see " Advanced Options" on the next page.
2. Now open AppPulse Mobile, and explore your app's user experience!
What's Next?
When you are ready to upload it, sign the new APK with your private key and upload it to the Google
Play store. To sign using AppPulse Mobile, see "Signing-Related Parameters" on page 6.
As soon as users interact with your app, AppPulse Mobile shows your users' experience in detail.
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.
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.
-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.
Signing-Related Parameters
By default, the instrumented APK is signed with a debug key, which is standard for testing and
developing Android mobile apps. However, you must sign the APK with your private key before you can
upload it to the Google Play store. If you want, you can use AppPulse Mobile to sign the instrumented
APK, using the following optional parameters:
Parameter Description
-keystore <Keystore file>] The path and name of the keystore file to be used for signing.
-alias <Key alias> The alias to the private key entry in the keystore.
-keypass <Key password> A password for the private key entry in the keystore, if configured.
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 Android 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 Android 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.
If you need custom masking (for example if a REST URLs contain usernames such as
http://www.example.com/customers/546789876/orders/), you can configure a mask in the following
file: <Unzipped SDK directory>\ApkInfuser\HPFilter.xml.
Example:
…
</Items>>
<MaskUrls>
<MaskUrl>http://www.example.com/customers/(.*?)/orders/(.*?)
/there</MaskUrl>
<MaskUrl>http://www.example.com/customers/(.*?)/orders</MaskUrl>
<MaskUrl>http://www.example.com/customers/(.*?)/orders/.*</MaskUrl>
</MaskUrls>
The URLs are configured as regular expressions, where the capture groups (parenthesized parts) are
the parts that will be masked. In the example above, the URL
http://www.example.com/customers/546789876/orders will be masked to
http://www.example.com/customers/*/orders.
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:
Basic Setup: Troubleshooting
Supported versions
HP AppPulse Mobile supports apps with Android 2.3 (API 9) and higher.
Signing issues
By default, the instrumented APK is signed with a debug key, which is standard for testing and
developing Android mobile apps. However, you must sign the APK with your private key before you can
upload it to the Google Play store.
l If you try to upload your instrumented app without signing, you will receive a message: Upload
failed. You uploaded an APK that was signed in debug mode. You can use AppPulse
Mobile to sign the instrumented APK, as described in "Signing-Related Parameters" on page 6.
l 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.** { *; }).
Error messages
The following section lists messages that may appear when adding HP AppPulse Mobile to your app,
with their explanation.
l If you have JRE 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.
Explanation: l If you are running JRE 32-bit, install 64-bit if supported by your OS.
l 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.
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.
Explanation: The current version of HP AppPulse Mobile does not yet support monitoring of
hybrid components. This capability is coming soon!
Explanation: Your app includes bytecode obfuscation techniques that employ "junk byte
injection." Contact HP Support for help with instrumenting your app.
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 (“ ^ < > %).
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.
The following APIs provide you with the ability to report these kind of exceptions with a severity level
that will cause them to be displayed in AppPulse Mobile as either crashes or errors, helping you
improve application quality and stability. You can use the following APIs to report the exception or
crash you would like to monitor.
Handled Exceptions
A non-fatal exception will be displayed as an event in the Stability > Errors area. AppPulse Mobile will
display the exception type, the developer-added description, and a link to show the full stack trace.
exception is an object containing all the relevant information of the problem (stack trace, user
message).
description is an optional field in case you want some text displayed in the errors page. If no
description is used, the text will be taken from the exception message.
Handled Crashes
Use this API when you catch a crash or exception that leads to exit the application. A fatal exception
will be displayed as a crash in the Stability > Errors area, and will have the same data as a crash.
HpAppPulse.reportCrash(Exception exception)
exception is an object containing all the relevant information of the problem (stack trace, user
message).
Breadcrumbs API
This API gives you the ability to add custom breadcrumbs in critical places in your application,
containing information on the application's inner state. AppPulse Mobile displays these custom
breadcrumbs in reports on crashes, making it easier for you to investigate the source of the problem.
HPAppPulse.addBreadcrumb(String name)
name is a short logical name which describes the breadcrumb context. This will be displayed in the
AppPulse Mobile UI.
Control Name
Sets the name and type for a given control.
A control is a View (android.app.view) on which a listener was set. For example, in order to click a
button, an onClickListener is set on this button. For this button, you set the name or type of the control
using the following API.
If you would like to consider a few separate controls as an identical control (for example two separate
lists that really do the same thing), you can group them together by setting the same name and type.
For example, suppose you have a list containing three items: Flights to x, Flights to y, and Flights to z,
and AppPulse Mobile identifies this as a menu with three distinct actions. You can set each of the
options with the same name/ID, grouped under the category “Flights to a location.”
Example:
HpAppPulse.setActionName(myView,”myName”);
Control Type
Sets the type for a given control. (For a definition of HPControlType enum; see "Enumeration of
Control Types" on page 17.)
For example, you can use this if you want a list to be considered a menu, so AppPulse Mobile will show
a separate action for each item and not one action of list. Another example would be if you think the
type of control is not what it appears to be, such as a control that looks like a button but has a checkbox
and a textView in it, and you would like to see it as a button.
Example:
HpAppPulse.setControlType(myView, HpAppPulse.HPControlType.Button);
Screen Name
You can set the name for a specific screen by calling the following API on an existing activity. This
should be added in the onStart or onResume method of the activity. You can also set the screen name
for a specific control.
You can use this to group several screen together by setting the same name.
This API needs to be called during the activity onStart or onResume lifecycle methods.
Example:
HpAppPulse.setScreenName(myActivity,”myScreenName”);
For example, if a list item is clicked and you want the screen name to be based on the list container, the
user will call this method on the list rather than on the list item.
Example:
HpAppPulse.setScreenName(myView,”myScreenName”);
This block contains a template for creating masking 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 SDKItem node.
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.
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.