Crittercism

Import com.crittercism.app package to use this class.

Initialization

initialize (context, appID)
Initialize Crittercism. After calling this method crashes and network insight information will be automatically reported to the Crittercism servers. In addition, all other Crittercism methods will be enabled for use.
public static synchronized void initialize (Context context, String appID)
context An Android Context
appID Your Android appID
initialize (context, appID, config)
Initialize Crittercism. After calling this method crashes and network insight information will be automatically reported to the Crittercism servers. In addition, all other Crittercism methods will be enabled for use.
public static synchronized void initialize (Context context, String appID, CrittercismConfig config)
context An Android Context
appID Your Android appID
config Your unique Apteligent app ID which can be found on the Crittercism web portal

Logging Breadcrumbs

A breadcrumb is a developer-defined text string (up to 140 characters) that allows developers to capture app run-time information. Example breadcrumbs may include variable values, progress through the code, user actions, or low memory warnings. For an introduction, see Breadcrumbs.
leaveBreadcrumb (breadcrumb)

Breadcrumbs provide the ability to track activity within your app. A breadcrumb is a free form string you supply, which will be timestamped, and stored in case a crash occurs. Crash reports will contain the breadcrumb trail from the run of your app that crashed, as well as that of the prior run.

Breadcrumbs are limited to 140 characters, and only the most recent 100 are kept. Apteligent will automatically insert a breadcrumb marked session_start on each initial launch, or foreground of your app.

public static void leaveBreadcrumb (String breadcrumb)
breadcrumb The custom string to leave a breadcrumb, maximum of 140 characters

Logging Handled Exceptions

logHandledException (exception)

Handled exceptions may be used for tracking exceptions caught in a try/catch statement, 3rd party library exceptions, and monitoring areas in the code that may currently be using assertions. Handled exceptions can also be used to track error events such as low memory warnings. For an introduction, see Handled Exceptions.

Handled exceptions are grouped by stacktrace, much like crash reports. Handled exceptions may be viewed in the “Handled Exceptions” area of the Apteligent portal.

We limit logging handled exceptions to once per minute. If you’ve logged an exception within the last minute, we buffer the last five exceptions and send those after a minute has passed.

public static void logHandledException (Throwable t)
exception Exception to log

Logging Network Request

Apteligent Performance Monitoring automatically monitors HTTP traffic generated by either java.net.HttpURLConnection or org.apache.http.impl.client.DefaultHttpClient. You can manually capture traffic generated by other networking libraries that Apteligent does not currently instrument.
logNetworkRequest(method, url, latency, bytesRead, bytesSent, responseCode, error)

This method allows developers to log service endpoints manually. This is useful for monitoring networking libraries that Crittercism does not itself instrument.

A network request will NOT be logged in the following cases:

  • A null string is provided for the method parameter.
  • A null URL is provided for the URL parameter.
  • A negative value is provided for the response time parameter.
  • An excessively large value is provided for the response time parameter (i.e., System.currentTimeMillis() - responseTimeMillis < 0).
  • A negative value is provided for the bytes read parameter.
  • A negative value is provided for the bytes sent parameter.
public static void logNetworkRequest(String method,
                                     URL url,
                                     long latency,
                                     long bytesRead,
                                     long bytesSent,
                                     int responseCode,
                                     Exception error)
method The connection method, such as GET, POST, HEAD, PUT, DELETE, TRACE, OPTIONS, CONNECT, PATCH
url The endpoint URL
latency The time between start of request and receipt of response, in milliseconds
bytesRead The number of bytes included in response body
bytesSent The number of bytes included in request body
responseCode HTTP status code, generally 100-599, e.g. 200 == OK, 400 == Bad Request, can be 0 if there is an error
error Exception instance for a failed request. Null if no error.
Introduced in Android SDK 5.1.0
logNetworkRequest(method, urlString, latency, bytesRead, bytesSent, responseCode, error)

This method allows developers to log service endpoints manually. This is useful for monitoring networking libraries that Crittercism does not itself instrument.

A network request will NOT be logged in the following cases:

  • A null string is provided for the method parameter.
  • A null URL is provided for the URL parameter.
  • A negative value is provided for the response time parameter.
  • An excessively large value is provided for the response time parameter (i.e., System.currentTimeMillis() - responseTimeMillis < 0).
  • A negative value is provided for the bytes read parameter.
  • A negative value is provided for the bytes sent parameter.
public static void logNetworkRequest(String method,
                                     String urlString,
                                     long latency,
                                     long bytesRead,
                                     long bytesSent,
                                     int responseCode,
                                     Exception error)
method The connection method, such as GET, POST, HEAD, PUT, DELETE, TRACE, OPTIONS, CONNECT, PATCH
urlString The endpoint URL in String
latency The time between start of request and receipt of response, in milliseconds
bytesRead The number of bytes included in response body
bytesSent The number of bytes included in request body
responseCode HTTP status code, generally 100-599, e.g. 200 == OK, 400 == Bad Request, can be 0 if there is an error
error Exception instance for a failed request. Null if no error.
Introduced in Android SDK 5.1.0
updateLocation (curLocation)

Inform Crittercism of the device’s most recent location for use with performance monitoring.

Apteligent Performance Monitoring ties location information to network data. By default, location information is obtained through a reverse IP lookup.

You have the option of updating location information with data given by android.location.LocationManager.NETWORK_PROVIDER or android.location.LocationManager.GPS_PROVIDER. This allows more accurate data to be sent to the server.

As explained in the Android Developer Guide, in order to receive location updates from the network or GPS provider, your AndroidManifest.xml` file must include either the ``ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION permission.

public static void updateLocation (Location curLocation)
location Location of the user / device
Introduced in Android SDK 4.2.0

Logging User Metadata

Developers can set user metadata to tracking information about individual users. For an introduction, see User Metadata.
setUsername (username)

Setting a username will allow the ability to monitor app performance for each user. Once a username is set, the Apteligent portal’s “Userviews” feature may be used to lookup a list of crashes and errors a specific user has experienced. We recommend setting a username to a value that can be tied back to your customer support system.

Valid inputs are strings with a length of 1 to 32 characters

public static void setUsername (String username)
username The new username
setMetadata (metadata)

Associate user data in the provided JSONObject with the device’s Crittercism UUID. This will send the association to Crittercism’s back end.

Up to ten key/value pairs of arbitrary metadata may be set for each user. The data will be displayed on the developer portal when viewing a user profile.

public static void setMetadata (JSONObject metadata)
metadata A JSONObject that contains user metadata

Logging User Flows

User flows allow developers to track key interactions or user flows in their app such as login, account registration, and in app purchase.

For an introduction, see User Flows Monitoring.

beginUserflow (name)

Init and begin a user flow with a default value.

User flows allow developers to track key interactions or user flows in their app such as login, account registration, and in app purchase. The SDK will automatically track application load time as a user flow. You can specify additional user flows by adding code to your application.

Beginning a user flow starts a user flow. Ending, failing, or cancelling a user flow stops a user flow. Otherwise, the user flow will be marked as crashed or timed out. If a crash occurs, all in progress user flows are marked crashed and will be reported with the crash.

All user flows will appear on Apteligent portal except for cancelled user flows.

User flows with the same name are aggregated together in the portal by Apteligent. Only one user flow for a given name can be in progress at a given time. If you begin a second user flow with the same name while another is in progress, the first user flow will be cancelled and the new one will take its place.

public static void beginUserflow (String name)
name The name of the user flow
cancelUserflow (name)
Cancel a user flow as if it never existed. The userflow will not be reported.
public static void cancelUserflow (String name)
name The name of the user flow
endUserflow (name)
End an already begun user flow successfully.
public static void endUserflow (String name)
name The name of the user flow
failUserflow (name)
End an already begun user flow as a failure.
public static void failUserflow (String name)
name The name of the user flow
setUserflowValue (name, value)
Set the currency cents value of a user flow.
public static void setUserflowValue (String name, int value)
value The value of the user flow
name The name of the user flow
getUserflowValue (name)
Get the currency cents value of a user flow.
public static int getUserflowValue (String name)
name The name of the user flow

Detecting a Crash Occurred

getPreviousSessionCrashData (crashListener)
Submit a callback to this method to get crash data from the previous session. The callback will receive crash information, see CrashData for details.
public static void getPreviousSessionCrashData (CrittercismCallback<CrashData> crashListener)
didCrashOnLastLoad ()
public static boolean didCrashOnLastLoad ()
Returns True if the app crashed on the last load, returns False otherwise.

Delay Sending App Load Data

sendAppLoadData ()
Tell Crittercism to send app load event. By default, Crittercism will send app load event automatically when your app is started. However, if you set ..:ref:delaySendingAppLoad <ios_delay_sending_app_load> flag to True on config, you can call this method to manually send app load event.
public static void sendAppLoadData ()

Instrumenting OkHttpClient

Apteligent Android SDK offers users the ability to instrument OkHttpClients to collect network insights.
instrumentOkHttpClient (okHttpClient)

Enables OkHttpClient instrumentation to collect network insights. It must be called on the main UI thread after the OkHttpClient is set. Once the method is invoked, Apteligent will automatically log network calls made with the returned instrumented client to the Network Insights page of the Web Portal.

Here’s an example of how to instrument a client:

OkHttpClient uninstrumentedClient = new OkHttpClient();
OkHttpClient instrumentedClient = Crittercism.instrumentOkHttpClient(uninstrumentedClient);
// now you can use the instrumented client for network calls (on a different thread)
instrumentedClient.newCall(...).execute();
public static OkHttpClient instrumentOkHttpClient(OkHttpClient client)
Introduced in Android SDK 5.8.11-rc2. Requires OkHttp 3.3.0 and above.

Instrumenting WebView

Apteligent Android SDK offers users the ability to instrument WebViews. This method only works for WebViews where JavaScript has already been enabled.
instrumentWebView (webView)

Enables WebViews instrumentation. This method only works if JavaScript has already been enabled. It must be called on the UI thread after the WebViewClient is set and before the webpage is loaded. Once the method is invoked, Apteligent will automatically log any uncaught JavaScript exceptions to the Handled Exceptions page of the Web Portal.

Here’s an example of how to configure and instrument a WebView:

// 1) Optionally set your own WebViewClient.
myWebView.setWebViewClient(myWebViewClient);

// 2) Enable JavaScript.
myWebView.getSettings().setJavaScriptEnabled(true);

// 3) Instrument WebView.
Crittercism.instrumentWebView(myWebView);

Note

Instrumenting WebView must be enabled in Hybrid Apps in order for Apteligent API calls in the JavaScript code layer to communicate with the native code layer.

public static void instrumentWebView(WebView webView)
Introduced in Android SDK 5.3.0

Opt Out Status

Apteligent provides an opt-out setting that disables all reporting to Apteligent. This allows developers to implement code that asks end users whether they want to opt out of Apteligent. For an introduction, see Opt Out of Apteligent.
getOptOutStatus ()
Retrieve current opt out status.
public static boolean getOptOutStatus()
Return True if the user has opted out of reporting Crittercism data.
setOptOutStatus (isOptedOut)

If you wish to offer your users the ability to opt out of Crittercism crash reporting, you can set the OptOutStatus to True. there will be no information/requests sent from that user’s app. If you do so, any pending crash reports will be purged.

Typically, a developer would connect this API call to a checkbox in a settings menu.

public static void setOptOutStatus(final boolean isOptedOut)
status set to True to disable Crittercism

Setting Apteligent’s Log Verbosity

By default, Apteligent prints a few messages to the device logcat that may be useful to verify that Apteligent is initialized and properly working. If you don’t want to see Apteligent log messages, you can tune the amount of logging that is displayed.
getLoggingLevel ()
public static LoggingLevel getLoggingLevel ()
The current logging level of the verbosity of Apteligent log messages.
setLoggingLevel (loggingLevel)

Set the logging level to tune the verbosity of Apteligent log messages. The default value is Crittercism.LoggingLevel.Warning.

See CrittercismLoggingLevel to see various logging levels.

public static void setLoggingLevel (LoggingLevel loggingLevel)
loggingLevel The verbosity of Crittercism logging
Crittercism.LoggingLevel
Enum used to describe Apteligent logging level.
public enum LoggingLevel {
    Silent,
    Error,
    Warning,
    Info }
Crittercism.LoggingLevel.Silent Turns off all Apteligent log messages
Crittercism.LoggingLevel.Error Only print errors. An error is an unexpected event that will result not capturing important data
Crittercism.LoggingLevel.Warning Only print warnings. Currently warning messages are printed when calling Apteligent methods before initializing Apteligent.
Crittercism.LoggingLevel.Info (Default) The most verbose level of logging