setting up android apps

HP AppPulse Mobile

Adding HP AppPulse Mobile to Your Android App

Document Release Date: May 2015

How to Add HP AppPulse Mobile to Your AndroidAppFor a quick overview showing this process, watch this video.

Before you BeginWithin AppPulseMobile, add an application.

Adding HP AppPulseMobile to Your Android AppHow to Add HP AppPulseMobile to Your Android App

HP AppPulseMobile (1.9) of 18

http://go.saas.hp.com/app-pulse-video2

Step 1: Download the SDKFrom the window that appears, download and extract the AppPulseMobile SDK.

Step 2: Add AppPulse Mobile to Your AppYou need to have Java Runtime Environment (JRE) 1.7 or higher installed. To verify what version youhave, run java -version in aWindows command line. To install JRE, click here.

1. Copy the application key generated in the previous step.

If you already closed the window, you can access the application's settings within AppPulseMobile and copy the application key from there.



http://java.com/en/download/

2. Open aWindows 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 pwl3i8kjke C:\MyAPK\myapp.apk

You now have a new APK in the same location as the original APK file, with the suffixsigned.debug.apk. The new APK is signed with a debug key, which is the standard for testing anddeveloping Android mobile apps.

l The above steps aremandatory. For other options, including parameters you can use to signthe APK with your private key, see " AdvancedOptions" on the next page.

l If you run into any problems, see "Basic Setup: Troubleshooting" on page 9.

Step 3: Run Your App

1. Install the new APK on an Android device or emulator, and use your app.

2. Now open AppPulseMobile, 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 GooglePlay store. To sign using AppPulseMobile, see "Signing-Related Parameters" on page 6.

As soon as users interact with your app, AppPulseMobile shows your users' experience in detail.



Advanced OptionsWhen you add HP AppPulseMobile to your app, you can define one or more advanced options asdescribed 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 directoryas the original APK. Use this parameter to specify a different outputfile.

-optIn By default, user data is automatically reported to AppPulseMobile.If you use this parameter, data will not be reported unless usersactivate data reporting (opt-in), as defined in your app. For details,see "Enabling Users to Opt-In/Opt-Out of Data Reporting" onpage 8.

-overrideacra AppPulseMobile uses a version of the ACRA library to collect dataon crashes. If your app already uses ACRA, by default AppPulseMobile will not show crash data for the app. You can use this flag toadd the AppPulseMobile ACRA library version and override yourcurrent ACRA library.

Note that this will disable your existing ACRA-based reportingmechanism, and you will see crash data in AppPulseMobile.

-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. Usethis parameter to modify this limit (possible range: 0-10). Setting ahigher limit will impact network load accordingly.

-tempdir <Temp directory> HP AppPulseMobile uses your temp directory to run theinstrumentation. Use this parameter to specify a different temporarydirectory.

Adding HP AppPulseMobile to Your Android AppAdvancedOptions


Signing-Related ParametersBy default, the instrumented APK is signed with a debug key, which is standard for testing anddeveloping Android mobile apps. However, youmust sign the APK with your private key before you canupload it to the Google Play store. If you want, you can use AppPulseMobile to sign the instrumentedAPK, using the following optional parameters:

Parameter Description

-keystore <Keystore file>] The path and name of the keystore file to be used for signing.

-storepass <Keystorepassword>

A password for the keystore, if configured.

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

Protecting Sensitive DataTo prevent reporting sensitive data such as a button or URL showing an account number, HP AppPulseMobile 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, HPAppPulseMobile shows Paid by account ***.

Before adding HP AppPulseMobile to your app, you can customize the default datamasking asfollows:

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 AppPulseMobile to Your Android App"on page 2.

l Change data masking rules. To define specific rules relevant for your particular app, open theSDK and locate the file <Unzipped SDK directory>\ApkInfuser\HPFilter.xml. This file contains thedefault 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 asneeded; 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 toAdd HP AppPulseMobile 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.



Protecting Sensitive URL ParametersBy default, AppPulseMobile alsomasks sensitive URL parameters. For example,http://www.example.com/customers/orders?username=dave&os=android is reported ashttp://www.example.com/customers/orders?username=*&os=*.

If you need custommasking (for example if a REST URLs contain usernames such ashttp://www.example.com/customers/546789876/orders/), you can configure amask in the followingfile: <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) arethe parts that will bemasked. In the example above, the URLhttp://www.example.com/customers/546789876/orders will bemasked tohttp://www.example.com/customers/*/orders.



Enabling Users to Opt-In/Opt-Out of Data ReportingSome apps give each user the ability to avoid sending data from their device, for example using aSettings menu item (opt-out). Other apps ask users to actively approve data collection, for examplewhen the app is first launched (opt-in).

By default, data is automatically sent frommobile apps to AppPulseMobile. You can use the -optInparameter 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 AppPulseMobile, change the Boolean value “enabled” inthe SharedPreferences “HPUserMonitoring”. The change will take effect the next time the user opensthe 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();

}



Basic Setup: Troubleshooting

Supported versionsHP AppPulseMobile supports apps with Android 2.3 (API 9) and higher.

Signing issuesBy default, the instrumented APK is signed with a debug key, which is standard for testing anddeveloping Android mobile apps. However, youmust sign the APK with your private key before you canupload it to the Google Play store.

l If you try to upload your instrumented app without signing, you will receive amessage: Uploadfailed. You uploaded an APK that was signed in debug mode. You can use AppPulseMobile 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 iton a device. For example, if you useGoogleWallet or GoogleMaps, your app requires the originalcertificate. This is also true if your application uses custom permissions that are signatureprotected, or if your application explicitly validates signatures.

If you are unable to properly run your app after adding AppPulseMobile, sign the new APK with youroriginal certificate.

Obfuscation issuesIf your app uses obfuscation, AppPulseMobile cannot be added to the app if you include theAndroidSupport Library in the obfuscation process. Make sure it is excluded from obfuscation (for example,for ProGuard use -keep class android.support.** { *; }).

Adding HP AppPulseMobile to Your Android AppBasic Setup: Troubleshooting


Error messagesThe following section lists messages that may appear when adding HP AppPulseMobile to your app,with their explanation.

Message: Instrumentation process was unable to run - Java RuntimeEnvironment was not found.

Explanation: l If you do not have JRE installed, install it from http://java.com/en/download/.

l If you have JRE installed but instrumentation still fails, access your systemvariables, and open the PATH variable for editing. Verify that the Java Homeis properly defined in the PATH variable; for example: C:\ProgramFiles\Java\jre7\bin.

After you edit the variable, close the existing command line and open a newone to continue instrumentation.

Message: Could not reserve enough space for object heap.

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 thisprocess. If you needmore, access the HP AppPulseMobile SDK and openthe ApkInfuser.bat file for editing. Locate the string -Xmx2048m and increasethis value as needed, depending on your available system resources.

Message: Warning: You already have the ACRA library in your applicationfor monitoring crashes. You can use the -overrideacra flag toreplace your existing ACRA library. In this case, you'll get ourdetailed crash reports solution instead.

Explanation: AppPulseMobile uses the ACRA library to collect data on crashes. Since yourapp is already using ACRA, by default AppPulseMobile will not collect crashdata for the app.

You can use the -overrideacra flag to add the AppPulseMobile ACRA libraryversion 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.



http://java.com/en/download/

Explanation: You used the -overrideacra flag to override your current ACRA library, but yourACRA library is obfuscated (class names are changed). Since you havecustomized your ACRA wewill not override it, and AppPulseMobile will notshow your crash data.

Message: Note: You are using the Override ACRA flag to enable AppPulseMobile crash reports.

Explanation: You used the -overrideacra flag to add the AppPulseMobile ACRA library versionand override your current ACRA library. This disables your existing ACRA-basedreportingmechanism, and you will see crash data in AppPulseMobile.

Message: Note: Your application contains some html or javascriptcomponents, which are not yet supported.

Explanation: The current version of HP AppPulseMobile does not yet support monitoring ofhybrid components. This capability is coming soon!

Message: There was a problem in decoding dex file. This application isobfuscated to avoid post-build instrumentation.

Explanation: Your app includes bytecode obfuscation techniques that employ "junk byteinjection." 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 AppPulseMobile to your appmust contain theSDK batch location, the application key, and the apk location. Check if yourcommand is missing one of these, or if any parameter in the command containsillegal characters (“ ̂ < > %).

Message: Failed to open dex file

Explanation: The classes.dex file is missing from your original apk, and AppPulseMobilecannot be added unless this file exists. Use a zip viewer (like 7-zip) to see if theclasses.dex file exists in your original apk. If it does exist, try to extract this fileonly from the original apk. Youmay see that your anti-virus software deletes itimmediately. In this case, disable the anti-virus before adding AppPulseMobileto your app, then re-enable your anti-virus software.



AppPulse Mobile SDKIn order to add the AppPulseMobile SDK and use its APIs, add the location of the jar to the classpath inyour project dependencies. The jar is located in the following location: <unzipped sdkdirectory>\sdk\HPAppPulseMobile.jar. After you rebuild your project you can use the following APIs:

l "Handled Exceptions and Crashes API" below

l "Breadcrumbs API" on the next page

l "User Action Customization APIs" on page 14

Handled Exceptions and Crashes APIAppPulseMobile automatically identifies and reports crashes. However, there are certain situationwhere exceptions occur and are caught by the application code, meaning they do not lead to a crash.

The following APIs provide you with the ability to report these kind of exceptions with a severity levelthat will cause them to be displayed in AppPulseMobile as either crashes or errors, helping youimprove application quality and stability. You can use the following APIs to report the exception orcrash you would like tomonitor.

Handled ExceptionsA non-fatal exception will be displayed as an event in the Stability > Errors area. AppPulseMobile willdisplay the exception type, the developer-added description, and a link to show the full stack trace.

HpAppPulse.reportException (Exception exception, String description)

HpAppPulse.reportException (Exception exception)

exception is an object containing all the relevant information of the problem (stack trace, usermessage).

description is an optional field in case you want some text displayed in the errors page. If nodescription is used, the text will be taken from the exceptionmessage.

Here's an example in the code:

Adding HP AppPulseMobile to Your Android AppAppPulseMobile SDK


Handled CrashesUse this API when you catch a crash or exception that leads to exit the application. A fatal exceptionwill 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, usermessage).


Breadcrumbs APIThis API gives you the ability to add custom breadcrumbs in critical places in your application,containing information on the application's inner state. AppPulseMobile 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 namewhich describes the breadcrumb context. This will be displayed in theAppPulseMobile UI.

The following are examples in the code:

User Action Customization APIsHP AppPulseMobile automatically assigns names to your application's screens and user actions(UI controls) based on a number of methods. If you want to customize these screen and control namesas they appear in AppPulseMobile, you can use the following APIs to define naming and grouping asrelevant to your needs.

This includes the following:

l "Control Name" on the next page

l "Control Type" on the next page

l "Screen Name" on page 16

l "Screen Name by Activity " on page 16

l "Screen Name by Control Container " on page 16

l "Enumeration of Control Types" on page 17



Control NameSets 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 abutton, an onClickListener is set on this button. For this button, you set the name or type of the controlusing the following API.

If you would like to consider a few separate controls as an identical control (for example two separatelists 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 AppPulseMobile identifies this as amenu with three distinct actions. You can set each of theoptions with the same name/ID, grouped under the category “Flights to a location.”

void setActionName(View view, String actionName);

Example:

HpAppPulse.setActionName(myView,”myName”);

Control TypeSets the type for a given control. (For a definition of HPControlType enum; see "Enumeration ofControl Types" on page 17.)

For example, you can use this if you want a list to be considered amenu, so AppPulseMobile will showa separate action for each item and not one action of list. Another example would be if you think thetype of control is not what it appears to be, such as a control that looks like a button but has a checkboxand a textView in it, and you would like to see it as a button.

void setControlType(View view, HPControlType controlType);

Example:

HpAppPulse.setControlType(myView, HpAppPulse.HPControlType.Button);




Screen NameYou can set the name for a specific screen by calling the following API on an existing activity. Thisshould be added in the onStart or onResumemethod of the activity. You can also set the screen namefor a specific control.

You can use this to group several screen together by setting the same name.

Screen Name by ActivitySets the screen name based on the activity.

This API needs to be called during the activity onStart or onResume lifecycle methods.

void setScreenName(Activity activity, String screenName);

Example:

HpAppPulse.setScreenName(myActivity,”myScreenName”);


Screen Name by Control ContainerSets the screen name based on a given control container.

For example, if a list item is clicked and you want the screen name to be based on the list container, theuser will call this method on the list rather than on the list item.

void setScreenName(View view, String screenName);

Example:

HpAppPulse.setScreenName(myView,”myScreenName”);




Enumeration of Control Typespublic enum HPControlType {

Button,RadioButton,Tab,Menu,List,DropDown,CheckBox

}

Protecting Sensitive Data Collected by the SDKIn some cases, youmay not want to show specific information collected via the AppPulseMobileAPIs, such as a screen name that includes a sensitive parameter. Tomask such data, open the SDKand locate the file <Unzipped SDK directory>\ApkInfuser\HPFilter.xml. Uncomment and edit the<SDK> block as needed.

This block contains a template for creatingmasking 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

WarrantyThe only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should beconstrued 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 LegendConfidential 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 NoticesApple is a trademark of Apple Computer, Inc., registered in the U.S. and other countries.

Google and Android are registered trademarks of Google Inc.



setting up android apps

Documents