HTML5 SDK

This topic describes how to use Apteligent with HTML5. Apteligent provides the HTML5 library using a content delivery network (CDN) for simplicity so that you can get crash reporting up and running within your application as quickly as possible.

Initializing the HTML5 SDK

Obtain your app ID from Workspace ONE Intelligence platform.

To set up basic integration:

  1. Include the following Apteligent Javascript library from our CDN in your HTML using a <script> tag:

<script type="text/javascript" src="https://d1a62freaxhn7x.cloudfront.net/v2/24/crittercismClientLibraryMin.js"></script>

  1. Call Crittercism.init with your Apteligent App ID, when the document is ready (the document.ready event).

The following example HTML document shows adding Apteligent to an application that uses jQuery.

<!DOCTYPE html>
<html>
  <head>
    <title>Example Document with Apteligent</title>
    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
    <script type="text/javascript" src="https://d1a62freaxhn7x.cloudfront.net/v2/24/crittercismClientLibraryMin.js"></script>
    <script type="text/javascript">
      $(document).ready(function() {
        Crittercism.init({
          appId: 'appId', // Example: 47cc67093475061e3d95369d
          appVersion: '1.0' // Developer-provided application version
        });
      });
    </script>
  </head>
</html>

Crittercism.init(options) takes a single argument, options. The options is a JSON dictionary containing key value pairs.

Keys

Name

Description

appId

AppId string obtained from Apteligent for a registered HTML5 app

appVersion

Developer-provided application version (optional)

debug

true, causes HTML5 SDK to print messages to console.log (optional)

View the raw CrittercismIntegrationWithJQuery.html hosted on GitHub.

Now you have the basic crash reporting available from Apteligent. The rest of this topic describes optional features that you can add to your HTML code.

Note

Hybrid Apps don’t and shouldn’t call Crittercism.init(). Hybrid Apps should include Apteligent Javascript library using a <script> tag.

Logging Breadcrumbs

Use the leaveBreadcrumb API to write to a chronological log that is reported with crashes, handled exceptions, and userflows.

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.

Here’s an example of how to leave a breadcrumb:

Crittercism.leaveBreadcrumb("User tapped a button");

Logging Handled Exceptions

Use the logHandledException API to track error conditions that do not necessarily cause a crash.

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 Workspace ONE Intelligence portal.

Here’s an example of how to log a handled exception:

try {
  JSON.parse('this isnt valid json');
} catch(e) {
  Crittercism.logHandledException(e);
}

Logging User Metadata

Developers can set user metadata to tracking information about individual users. For an introduction, see User Name.

Adding a Username

Setting a username will allow the ability to monitor app performance for each user. We recommend setting a username to a value that can be tied back to your customer support system.

Here’s an example of how to set a user name:

Crittercism.setUsername("TomCritter");

Logging Userflows

Note

The Logging Userflows API is currently only supported for Hybrid Apps . The Logging Userflows API methods currently act as NOP’s in pure HTML5 web apps.

Use the beginTransaction, endTransaction, and failTransaction methods to log userflows.

User flows allow developers to track key interactions or user flows in their app such as login, account registration, and in app purchase. The Workspace ONE Intelligence 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 Workspace ONE Intelligence portal except for cancelled user flows.

User flows with the same name are aggregated together in the portal by Workspace ONE Intelligence. 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.

Here’s an example of how to log a single userflow:

Crittercism.beginTransaction("login");
var didLogin = runMyLoginCode();
if didLogin {
    Crittercism.endTransaction("login");
} else {
    Crittercism.failTransaction("login");
};

Beginning a Userflow

Beginning a user flow tells Workspace ONE Intelligence SDK that the user flow has started. Workspace ONE Intelligence SDK starts timing the duration of the user flow and waits for the user flow to succeed, fail, or be cancelled in code.

Here’s an example of how to begin a userflow:

Crittercism.beginTransaction("my_transaction");

Ending a Userflow

Ending a user flow tells Workspace ONE Intelligence SDK that the given user flow has successfully completed. At this point, the user flow time is recorded, and the user flow will be reported to Workspace ONE Intelligence.

Here’s an example of how to end a userflow, which is the same as marking it as succeeded:

Crittercism.endTransaction("my_transaction");

Failing a Userflow

Failing a user flow tells Workspace ONE Intelligence SDK that the given user flow has failed. At this point, the user flow time is recorded, and the user flow will be reported to Workspace ONE Intelligence.

Here’s how to mark a userflow as failed:

Crittercism.failTransaction("my_transaction");

Modifying the Value of a Userflow

Use the setTransactionValue method to modify the value of a userflow. The value of a userflow should be specified in cents.

A developer may optionally set the value of each user flow. This allows stakeholders to more accurately evaluate the business impact of failing user flows. Setting user flows values within the app is most useful when the value of a user flow can change based on user interactions. One example is in-app purchases of varying quantities.

In addition to being able to specify user flows values in the code, a default user flows value may be specified in the Workspace ONE Intelligence portal. This allows changing user flows values on the fly.

var valueInCents = 999;
Crittercism.setTransactionValue("my_transaction", valueInCents);

Logging Network Requests

Note

The Logging Network Requests API is currently only supported for Hybrid Apps . The Logging Network Requests API methods currently act as NOP’s in pure HTML5 web apps.

Use the logNetworkRequest method to manually log network library network access to URL’s.

Here’s an example of how to log a network request:

Crittercism.logNetworkRequest("GET",
                              "http://www.abc123def456.com",
                              2000,
                              10000,
                              100,
                              200,
                              0)

Arguments

Name

Description

method

String HTTP verb such as “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “TRACE”, “OPTIONS”, “CONNECT”, or “PATCH”.

url

String, representing the contacted endpoint.

latency

Number, representing the time between start of request and receipt of response, in milliseconds.

bytesRead

Number, the number of bytes included in response body.

bytesSent

Number, the number of bytes included in request body.

responseCode

Number, HTTP status code, generally 100-599, e.g. 200 == OK, 400 == Bad Request, can be 0 if there is an error.

errorCode

Number, a non-zero error code can be logged if network request failed to contact server, etc. Pass 0 if there was no error.

Hybrid Apps

The HTML5 SDK supports iOS and Android hybrid applications. A hybrid app is a mobile application built using both native code as well as javascript code which is run in a webview. Using the installation instructions below, you will be able to monitor the performance of both the native code as well as javascript code in the webview in a unified view.

To properly instrument a hybrid app, you’ll need to follow these steps:

  1. Install the Apteligent Native SDK

Download and install the native Apteligent SDKs.

  1. Initialize the Apteligent Native SDK

After the SDKs are installed, initialize the native Apteligent SDK in your app. To obtain an app_id, register an iOS or Android app and use the app_id for that app. Registering a separate HTML5 app is not necessary.

  1. Enable Webview Monitoring

To monitor the performance of webviews including javascript error monitoring, enable monitoring the webview in the native SDK.

Note

Hybrid apps automatically report uncaught JavaScript exceptions as handled exceptions to Apteligent. Hybrid apps also automatically log XMLHttpRequest network requests.

Customized Instrumentation for Hybrid Apps

In addition to automatically monitoring the performance of webviews, users can optionally add instrumentation to measure custom Userflows and custom logging in the HTML5 code to help debug errors:

  1. Integrate HTML5 SDK

In order to set up custom logging from the HTML5 SDK, include the Apteligent JavaScript library. This will allow your JavaScript code to call any of the other HTML5 SDK API methods. The JavaScript code layer of a hybrid app does not need to call Crittercism.init() since initialization is performed by the native code layer of the hybrid app. Once the JavaScript library is included, calls to any of the HTML5 SDK methods will call the native code layer.

<script type="text/javascript" src="https://d1a62freaxhn7x.cloudfront.net/v2/24/crittercismClientLibraryMin.js"></script>

  1. Custom Logging in Hybrid Apps

Add Breadcrumbs in both JavaScript and native code to help debug errors in crashes, handled exceptions, or userflows. All JavaScript exceptions are automatically sent as Handled Exceptions. Breadcrumbs can be logged in both the native SDK as well as the HTML5 SDK. Regardless of where breadcrumbs are logged, they will appear in all crashes, handled exceptions, and userflows.

  1. Custom Userflows in Hybrid Apps

A common performance problem in many hybrid apps is UI lag and errors when the app switches between the hybrid UI and the webview. Measure these transitions by adding Userflows. Since the Apteligent HTML5 SDK can communicate directly with the native SDK, you can begin and end Userflows between the two SDKs.

For example, you can begin a Userflow in your native iOS SDK:

Objective-C

[Crittercism beginUserflow:@"Load Checkout Page"];

Swift

Crittercism.beginUserflow("Load Checkout Page")

Then, you can end that same Userflow in your HTML5 SDK:

Crittercism.endTransaction("Load Checkout Page");

This will allow you to measure the UI lag for transitioning between the native layer and the webview as well as monitor any crashes or javascript errors during the transition. For more information on instrumenting Userflows, see the following: