Unity Integration

Apteligent helps developers track and manage performance of mobile applications on several platforms. For more information, see Overview and the Solution Overview.

Requirements

  • Unity version 5.
  • iOS 6.0 and later
  • Android 2.3 and later

Installing the Unity SDK

1. Obtaining the Unity SDK

Download our latest Unity Plugin. The download contains the following items:

Item Contains
Plugins/iOS The iOS plugin binary
Plugins/Android The Android plugin binary
Plugins/Crittercism/Crittercism_IOS_Scripts Init Script and the C# bindings that call into the Apteligent iOS SDK
Plugins/Crittercism/Crittercism_Android_Scripts Init Script and the C# bindings that call into the Apteligent Android SDK
DemoApp An example app

2. Adding the SDK to your Project

Drag and drop the Plugins directory into your project’s Assets folder:

../_images/unity_drag_plugins.png

Modifying Your Android Manifest

A custom AndroidManifiest.xml file must be added to the {Unity Project}/Plugins/Android folder. Inside the file, verify you have the INTERNET and ACCESS_NETWORK_STATE permission in between the <manifest> ... </manifest> tags so Apteligent can send data to our servers:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

For more granular data (optional), add the following permissions:

<uses-permission android:name="android.permission.GET_TASKS"/>

3. Adding the Apteligent Component

  • In the Unity Editor, create a new GameObject. Rename the Game Object to “Crittercism Initializer”.
  • Select the game object in the Hierarchy pane and attach the Apteligent script as a component.
../_images/unity_embed_script.png

4. Initializing Apteligent

Fill in your iOS app ID and Android app ID

../_images/unity_fill_app_id.png

5. Configure Unity Build and Player Settings

The Unity IDE has several settings which impact the type of data the Apteligent SDK can report. This section will outline the effects of these settings and give recommended values for best support.

Android Optional Configuration

The Android Unity SDK provides additional configuration options to enable logcat collection, and customize version names. In order to perform these configurations, open CrittercismAndroid.cs script under Plugins/Crittercism/Crittercism_Android_Scripts directory.

Inside Init (string appID) method, instantiate a CrittercismConfig object and invoke the SetLogcatReportingEnabled (bool) and SetCustomVersionName (string) methods. Then pass the configuration object to the initialization call.

Here’s an example:

public static void Init (string appID)
{
   CrittercismConfig config = new CrittercismConfig ();

   // enable logcat collection
   config.SetLogcatReportingEnabled (true);

   // set version name to myCustomVersion
   config.SetCustomVersionName ("myCustomVersion");

   Init (appID, config);
}

Logging Crashes

DidCrashOnLastLoad API

Use the DidCrashOnLastLoad API to test if the previous session of your app crashed.

bool didCrash = Crittercism.DidCrashOnLastLoad();

SetLogUnhandledExceptionAsCrash API

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 bool, true or false. Here’s an example of how to use SetLogUnhandledExceptionAsCrash:

void 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 {
    throw new TestException();
} catch (System.Exception error) {
    Crittercism.LogHandledException(error);
}

Note

We limit to sending five exceptions per minute.

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 started level 5");

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

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:

Crittercism.SetValue("5", "GameLevel");

It is also possible to associate several keys and values in one go:

using System.Collections;
using System.Collections.Generic;

// Maintain List's, then convert them to Array's to pass to SetMetadata.
List<string> listOfKeys = new List<string>();
List<string> listOfValues = new List<string>();
listOfKeys.Add("Locale");
listOfKeys.Add("playerID");
listOfKeys.Add("playerLVL");
listOfValues.Add("en");
listOfValues.Add("23958");
listOfValues.Add("34");
Crittercism.SetMetadata(listOfKeys.ToArray(), listOfValues.ToArray());

// Alternatively, just use Array's.
Crittercism.SetMetadata(
    new string[] {"Age", "Email", "Extra"},
    new string[] {"26", "email@test.com", "Data"} );

Logging Userflows

Use the BeginUserflow, EndUserflow, FailUserflow, and CancelUserflow 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.BeginUserflow("login");
// Run the code you want to monitor
bool didLogin = RunMyLoginCode();
if (didLogin) {
    Crittercism.EndUserflow("login");
} else {
    Crittercism.FailUserflow("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.BeginUserflow("my userflow");

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

var valueInCents = 100;
Crittercism.BeginUserflow("my userflow", 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.EndUserflow("my userflow");

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.FailUserflow("my userflow");

Cancelling a Userflow

Cancelling a user flow tells Apteligent that the given user flow has been cancelled. The user flow is not recorded and will not be reported to Apteligent.

If a developer does not specify success, failure, or cancelled in code, then the only possible remaining final states a user flow can reach are crashed and timed out. See User Flows Final States for more information.

Here’s how to cancel a userflow:

Crittercism.CancelUserflow("my userflow");

Modifying the Value of a Userflow

Use the SetUserflowValue and GetUserflowValue methods 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.

int itemValueInCents = 100;
int totalValueInCents
    = Crittercism.GetUserflowValue("shopping cart") + itemValueInCents;
Crittercism.SetUserflowValue("shopping cart", totalValueInCents);

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

Crittercism.SetOptOut (true);

bool isOptedOut = Crittercism.GetOptOut ();