PhoneGap Integration Guide

This topic describes how integrate Apteligent into a PhoneGap application. The Apteligent plugin is available for Apple and Android.

Note

If this is your first time using Apteligent, go to the Apteligent Quickstart to get up and running quickly. You must first sign up for your free Apteligent account and register your app for its intended platform(s).

Installing the Apteligent PhoneGap Plugin

You will need Cordova-4.0.0 or higher and jQuery included in your <script>. An example app is available on github.

  1. Assuming you release your PhoneGap app on both Android and iOS, register two new apps on the Apteligent portal. The app platform types should be Android and iOS.
  2. Obtain your Apple and/or Android Apteligent app IDs from the app settings page on the Apteligent portal
  3. To integrate the Apteligent plugin, run the following command:
cordova plugin add cordova-plugin-apteligent
  1. Enable Apteligent. Call Crittercism.init() after the plugins are ready
document.addEventListener('deviceready', onDeviceReady, false);
function onDeviceReady() {
   Crittercism.init({ 'iosAppID' : 'YOUR_IOS_APP_ID',
                  'androidAppID' : 'YOUR_ANDROID_APP_ID'});
}

That’s it! You’re now ready to build and run your app.

Service Monitoring

Whenever an app makes a network call, Apteligent monitors and captures certain information. For the PhoneGap plugin, Apteligent monitors network requests for both native iOS/Android as well as for JavaScript. For an introduction to service monitoring, see Service Monitoring.

For JavaScript, Apteligent currently monitors XMLHttpRequests and jQuery Ajax calls and logs the following details for each request:

  • HTTP method
  • URL
  • Bytes in
  • Bytes out
  • Latency
  • Response code
  • Time stamp

Current Limitations

  • jQuery $.getScript requests and requests with datatype ‘jsonp’ are not monitored
  • Synchronous XMLHttpRequests and jQuery ajax calls are missing latency information
  • Information on payload size is not currently collected when sending and receiving FormData and Document data types

Logging Network Requests

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.

Logging Userflows

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:

Crittercism.beginTransaction("login");
// Run the code you want to monitor
var didLogin = runMyLoginCode();
if (didLogin) {
    Crittercism.endTransaction("login");
} else {
    Crittercism.failTransaction("login");
}

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:

Crittercism.beginTransaction("my_transaction");

When beginning a userflow, you can also assign the userflow a value:

var valueInCents = 100;
Crittercism.beginTransaction("my_transaction", valueInCents);

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:

Crittercism.endTransaction("my_transaction");

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:

Crittercism.failTransaction("my_transaction");

Modifying the Value of a Userflow

Use the setTransactionValue and getTransactionValue methods to modify the value of a userflow. The value of a userflow should be specified in cents. getTransactionValue is run asynchronously so you will need to pass in a callback function.

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 itemValueInCents = 100, totalValueInCents;
Crittercism.getTransactionValue("shopping_cart", function(transactionValue) {
    totalValueInCents = transactionValue + itemValueInCents;
    Crittercism.setTransactionValue("shopping_cart", totalValueInCents);
});

Logging Breadcrumbs

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

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 Crashes

Unhandled JavaScript exceptions are normally reported to the Handled Exceptions area of the Apteligent server because the app itself doesn’t crash. Use the setLogUnhandledExceptionAsCrash API to request Apteligent to report unhandled JavaScript exceptions to the Crash Reports area of the Apteligent server instead.

Crittercism.setLogUnhandledExceptionAsCrash(value);
Crittercism.getLogUnhandledExceptionAsCrash();

The value should be a boolean, true or false. Here’s an example of how to use setLogUnhandledExceptionAsCrash:

function callCriticalBusinessFunction() {
    try {
        setLogUnhandledExceptionAsCrash(true);
        criticalBusinessFunction();
    } finally {
        setLogUnhandledExceptionAsCrash(false);
    }
}

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) {
  Crittercism.logHandledException(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:

Crittercism.setUsername("MommaCritter");

Adding Arbitrary User Metadata

For each user you can set arbitrary key/value pairs. 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 a specific key/value pair
var gameLoadTime = getGameLoadTime();
Crittercism.setValueForKey('gameLoadTime', gameLoadTime);