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. For related information, see Apteligent Quickstart.


If this is your first time using Apteligent, go to Apteligent Quickstart to get up and running quickly. Before you can install the Apteligent SDK, you must first sign up for your free Apteligent account, register your app (if needed), and download the Apteligent SDK for your app platform. Apteligent determines which Data Location to send your data based upon the Apteligent application id.

Refer to the Release Notes for information about the version you downloaded.

Initializing the HTML5 SDK

Obtain your App ID from Apteligent’s “New App Registration” page (Apteligent Quickstart).

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=""></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>
    <title>Example Document with Apteligent</title>
    <script type="text/javascript" src=""></script>
    <script type="text/javascript" src=""></script>
    <script type="text/javascript">
      $(document).ready(function() {
          appId: 'appId', // Example: 47cc67093475061e3d95369d
          appVersion: '1.0' // Developer-provided application version

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


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.


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

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

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

Logging User Metadata

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

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

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


Adding Arbitrary User Metadata

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.

Here’s an example of how to associate metadata with the current user:

// Set metadata using a JSON object
  currency : "dollar",
  gameLevel : 5,
  virtualCurrencyBalance: 100

// Set a specific key/value pair
var gameLoadTime = getGameLoadTime();
Crittercism.setValue('gameLoadTime', gameLoadTime);

Logging Userflows


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

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

var didLogin = runMyLoginCode();
if didLogin {
} else {

Beginning a Userflow

Beginning a user flow tells Apteligent the user flow has started. Apteligent 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:


Ending a Userflow

Ending a user flow tells Apteligent 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 Apteligent.

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


Failing a Userflow

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

Here’s how to mark a userflow as failed:


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 Apteligent portal. This allows changing user flows values on the fly.

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

Logging Network Requests


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:



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.


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=""></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:

[Crittercism beginUserflow:@"Load Checkout Page"];
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: