# Crasheye Unity Plugin

# Integration

Crasheye Unity Plugin is an exception monitoring plugin exclusively for Unity game apps, which catches exceptions thrown by scripts (such as JavaScript and C#) and native code (such as Objective-C, Java) in Unity project, and offers instant and accurate error analyzing service.

# Create A New App and Get The AppKey

Once you register and log in Crasheye, you can create your own app. Every app will have a unique AppKey to initialize the SDK, and to identify your app as well.( Download Sample (opens new window) )

Create new app::

  1. Log in Crasheye to access admin panel.
  2. Click the profile picture at the upper right corner of the page, and select [my apps] in the popup menu to access the list of your apps.
  3. Click [new] in app list page.
  4. Input an app name and choose a platform type, and then click [yes]. A new app is created.

Keep your unique AppKey secured from misuse.

# Download SDK

On the SDK download page, click Download Crasheye Unity Plugin

# Import Crasheye Unity Plugin

After the download is completed, drag the Package directly into the project, and click Import

Note: If the Unity version used by the project is higher than the Unity2018.2 version, you can skip 2 or 3 steps.

Since Unity2018.2 version , Unity has been able to directly compile .cpp , .a, .java files as plug-ins in Unity programs, which can save the use of VS, AS, XCode plug-in development export debugging steps, very convenient.

If your project uses a Unity version higher than the Unity2018.2 version, you can create a new Java file directly in the project's Plugins/Androiddirectory, named MainA ctivity.java. The contents of the Java file will be belowstep2.3in thescheme onescheme twoin the Java code can be copied

.

# Android initialization

The initialization of Crasheye android must be done in the java layer,so the following steps can be performed

# 1、Export Android projects in Unity

Check Export Project in the Android build options, and click Export to export the Android project

Note: If the selected build platform is not Android platform, first click Switch platform to switch to Android platform

# 2、New Empty Activities

Open the Android project, and (Unity 2019 version needs to be under the unity library) create a new Empty Activity, the location and name are optional

This place is called MainActivity and the location is com.crasheye.client.api.unity 3d

TheIDEused in the screenshot isAndroid Studio

Note: The new activity does not require interface files, language selection Java

# 3、Crasheye initialization configuration

Change the inherited class to UnityPlayerActivity and configure Crasheye initialization, as shown in the following code

If the main Activity in your project inherits from the UnityPlayerActivity, be sure to place the Crasheye initialization code after super.on Create ().

Because new UnityPlayer () is called in super.on Create (), and because the new version of Unity handles crash signals, Unity must be initialized first, then Crasheye must be initialized, so that Crasheye can capture the crash signal first.

Scenario 1: Configure parameters in the jar package

This method has a disadvantage, want to use different appkey, you need to regenerate the jar package

package com.crasheye.client.api.unity3d;

import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import com.unity3d.player.UnityPlayerActivity;
import com.xsj.crasheye.Crasheye;

public class MainActivity extends UnityPlayerActivity {
    @Override
    private String appkey = "project AppKey" //project's appkey
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        Crasheye.initWithMonoNativeHandle(this, appkey);
    }
}

Here appkey fill in the appkey of your own project, the appkey can be applied in Permission Platform (opens new window).

Solution 2: Configure parameters in the manifest (recommended)

It is recommended to modify it to the form of the following sample code. Easy to call different parameters, no need to regenerate the jar package

package com.crasheye.client.api.unity3d;

import android.content.pm.ApplicationInfo;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.util.Log;

import com.unity3d.player.UnityPlayerActivity;
import com.xsj.crasheye.Crasheye;

public class MainActivity extends UnityPlayerActivity {
    public static String TAG = "MonoCrasheye";
    
    String Crasheye_appkey = null;

    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        
        try {
            ApplicationInfo info = getPackageManager().getApplicationInfo(getPackageName(), PackageManager.GET_META_DATA);
            Crasheye_appkey = info.metaData.getString("Crasheye_appkey");
        } catch (PackageManager.NameNotFoundException e) {
            e.printStackTrace();
        }
        
        if (Crasheye_appkey == null) {
            Log.e(TAG,"appkey is Empty");
        } else {
            Crasheye.initWithMonoNativeHandle(this, Crasheye_appkey);
        }
    }
}

In this way, the server domain name Crasheye upload data are placed in the AndroidManifest.xml file to complete.After modifying the configuration, you can directly modify it in the AndroidM anifest.xml without re-exporting the project to hit the jar package .

Add two meta-data tags to the application tag in the AndroidM anifest.xml file. Used to specify Crasheye upload the appkey of the project.

<application>
    <meta-data
        android:name="Crasheye_appkey"
        android:value="project is appkey" />
</application>

# 4、 Package Activities into jars

  • Eclipse packaged into jars

Export src project as jar package

When exporting, remove all files and only select src for export. For example, the exported file is MonoC rasheye.jar

  • - Android Studio packaged into jar packages

    Android Studio

In thebuild.gradlefile, add aJar Task.Used to make the typed Jar package remove theBuildConfigfile

task makeJar(type: Jar, dependsOn: ['build']) {
    destinationDir = file('build/outputs/jar/')
    baseName = "MonoCrasheye"
    //from('build/intermediates/classes/debug')
    from('build/intermediates/javac/debug/compileDebugJavaWithJavac/classes')
    include('com/crasheye/**/*.class')
}

Afterbuild.gradleadd configuration,be sure to click the Sync Now button

Click the Gradle button to bring up the Gradle menu. Open the path shown below

Find the Jar Taskyou just created, andright-click to executethe Task to complete the packaging

The packaged jar package is called MonoCrasheye.jar, under the Activity path of theLibrarywhere thebuild/outputs/jaris located。

# 5、Import Unity Project

Put the Jar package in the Plugins\ Android directory of the Unity project

Then modify theAndroidManifest.xmlile in the Unity project and set the entry to the activity just typed.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.unity3d.player">

    <uses-feature android:glEsVersion="0x00030000" />
    <uses-feature
        android:name="android.hardware.vulkan.version"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.touchscreen"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.touchscreen.multitouch"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.touchscreen.multitouch.distinct"
        android:required="false" />

    <application>
        <activity
            android:name="com.crasheye.client.api.unity3d.MainActivity"
            android:configChanges="mcc|mnc|locale|touchscreen|keyboard|keyboardHiddennavigation|orientation|
            screenLayout|uiMode|screenSize|smallestScreenSize|fontScale|layoutDirection|density"
            android:hardwareAccelerated="false"
            android:launchMode="singleTask"
            android:screenOrientation="fullSensor"
            android:theme="@style/UnityThemeSelector">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

            <meta-data
                android:name="unityplayer.UnityActivity"
                android:value="true" />
            <meta-data
                android:name="android.notch_support"
                android:value="true" />
        </activity>
        <meta-data
            android:name="unity.splash-mode"
            android:value="0" />
        <meta-data
            android:name="unity.splash-enable"
            android:value="True" />
        <meta-data
            android:name="notch.config"
            android:value="portrait|landscape" />
        <meta-data
            android:name="unity.build-id"
            android:value="38c4abce-dfeb-493b-9906-c63646cacb76" />
    </application>
</manifest>

# 6、Android access completed

Put the exported jar and AndroidM anifest.xml files under the Android of the Unity project.

After completing the above steps, android in Crasheye Unity Package is complete.

Possible problems

  1. 1. Gradle project sync failed.

If you encounter this situation, you need to check whether the local.properties file of the project uses the Android SDK path of the Unity engine.

If so, change the path of the SDK to the Android SDK path of Android Studio.

Normally C:\ Users\ {Your username}\ AppData\ Local\ Android\ Sdk

After modification, click the SDK Manager button to check whether the corresponding version of Android SDK in the build.gradle file has been downloaded.

When finished, click Try Again if Gradle project sync failed. Disappeared, indicating that the build was successful

  1. Type XXX is defined multiple times

Try Clean Project first, then repack

If you still report an error, check the jar package and code for files or similar names.

# iOS Initialization

Add Unity's initialization script to the program entry:(Use this access to remove the C rasheye.cs from the object.

void Start()
{
        #if UNITY_ANDROID
                // The program entry also needs to be initialized to capture script exceptions
                Crasheye.RegisterLogCallback();
        #endif

        #if UNITY_IPHONE
                /**
                * iOS initialization is done in Unity 
                */
                Crasheye.StartInitCrasheye("Please fill in iOS AppKey");
        #endif
}

# iOS App Configuration

Note: Skip this step if your app will not be published on iOS market.

Configure build settings in the iOS project exported from Unity. (Do not configure duplicate)

Open Xcode project settings, select [Build Phases] tab, and unfold [Link Binary with Libraries], and click [+] button:

Add [libz.dylib] and [libc++.dylib] file:

Your iOS app is now configured with Unity project. Please test on a real device. If successful, data will be showed in admin panel in real time.

In iOS SDK 2.5.0 or later, it uploads files through HTTPS protocol instead, so it's not necessary to add NSExceptionDomains or NSAllowsArbitraryLoadsz fields. But in the versions older than 2.5.0, you have to add the two fields by yourself.

# Test

Please test on a real device. If successful, data will be shown in admin panel in real time.

Run your project. If Crasheye outputs logs demonstrated below, the initialization is completed.

# iOS SDK Integration in MONO Mode

Default mode for iOS SDK is IL2CPP. If MONO mode is required, you can follow the instructions below: (Skip this step if you are using IL2CPP))

  1. Comment out the following code in public static void Init(string appKeyForIOS, string channIdForIOS) of CrasheyeForIOS.cs file.
crasheyeInitWithChannel(appKeyForIOS, channIdForIOS);
  1. Add function declaration in main.mm of the exported Xcode project:
extern "C" void mono_set_signal_chaining(int chain_signals);
extern "C" void crasheyeInitWithChannel(const char * appkey, const char * channel);
  1. Add the following code between NSAutoreleasePool* pool = [NSAutoreleasePool new]; UnityInitTrampoline(); in the main function of main.mm of the exported Xcode project.
mono_set_signal_chaining(1);
//The values of parameter "appkey" and parameter "channel" should be the real AppKey ID and Channel ID.
crasheyeInitWithChannel("appkey","channel");

# Test

Please test on a real device. If successful, data will be showed in admin panel in real time.

# Android Configuration for Regular Integration

Note: Skip this step if you have configured Android MONO stack backtrace.

# Mount and Initialize Scripts

Select the first scene or main sceneto load in your Unity project, and choose an existing object or create a new object. Then, you need to drag [Crasheye.cs] script to the new game object to mount on it. (Sample download (opens new window))

# Configure AppKey

Set the Crasheye initialization in Inspector and replace the value of parameters such as Your AppKey For Android,Your AppKey For iOS,Your Channel Id For Android,Your Channel Id For iOSwith the corresponding AppKey and Channel ID. AppKey is mandatory. Channel ID can be optional.

Open [Build Setting] panel. Select an Android platform, and click on [Player Settings...]. Then, you can switch to [Setting for Android] tab to unfold [Other Settings], and select [Require] in [Internet Access].

Finally, please make sure that Android permission permission has been included in [AndroidManifest.xml] of the exported Android
project. Note: Do not configure duplicate.
Note: Do not configure duplicate.

Your Android app is now configured with Unity project.Please test on a real device. If successful, real time data will be monitored and shown on the Crasheye admin panel.

# Common APIs

# Report Script Exception

This API is for the convenience of developers. The caught exceptions of stack trace, such as lua and js script exceptionexceptions of stack trace, will be reported to server.

/**
* Script exception reporting interface
* @param e : exception information
*/
Crasheye.sendScriptException(Exception e);

# Set whether to report report files only under wifi

In order to save the cellular data usage for the users, Crasheye offers an API to report stack trace of crashes only when the device is on wifi networks.

/**
* Whether the file is uploaded via WIFI only or not
* @param enabled true: Report via WIFI only
*/
Crasheye.setFlushOnlyOverWiFi(bool enabled);

# Set App version number

By default, Crasheye will read version information from configuration file. Of course you can also set app version by calling API .

Crasheye.SetAppVersion(string youAppVersion);

# Set user ID

You can assign User Identification to each reported issue to help filter and locate issues. Developer can use this method to filter crash issues reported by his own device.

/**
* Set user identifier
* @param userIdentifier : user identifier
*/
Crasheye.SetUserIdentifier("UserIdentifiter");

# Set channel number

You can call an API to set Channel ID:

/**
* Set channel ID
* @param ChannelID Set channel ID
*/
Crasheye.SetChannelID("xxx");

# Add custom data

In case that you want to capture more data than the default setup does, you can call this API to add developer-defined text string to collect more needed information:

/**
* Add User-defined keyword
* @param key : user-defined identifier
* @param value : user-defined information
*/
Crasheye.AddExtraData(string key, string value);

# Add breadcrumbs (dotting info)

By leaving breadcrumbs (navigation information), you can capture the time and sequence of crashes and handled exceptions to keep track of if your app is working as intended. Call the following API where you want to monitor(The Android interface supports the collection of up to 16 lines of the latest breadcrumbs):

Crasheye.leaveBreadcrumb(string breadcrumb);

# Set to collect log logs

This API collects logs (LogCat) in runtime. When exception occurs, the collected logs will be saved and reported to server. (Maximum 1000 lines of the latest logs)

The interface is for Android system only, and is not working in iOS system.

/**
* Access application log (filtration parameters: keyword and line count)
* @param lines  : lines of codes collected (1000 lines in maximum)
* @param filter : Keyword(require = false), for example, using Crasheye as keyword is equivalent to entering "logcat -d Crasheye" in Logcat filter
*/
Crasheye.SetLogging(lines, filter);
or
Crasheye.SetLogging(lines);

# Set the registered log callback function

Application.RegisterLogCallback is the function that calls back register log. This interface is initialized only once in Crasheye, so you can set the function you need using this interface if necessary.

/**
* configure the function that calls back register log
* @param RegisterLog     the function that needs to be called back
*/
Crasheye.SetRegisterLogFunction(RegisterLog); 
//eq: 
void Start()
{
    Crasheye.SetRegisterLogFunction(Test1);
}

[AOT.MonoPInvokeCallback(typeof(Crasheye.RegisterLog))]
public void RegisterLogFunction(string logString, string stackTrace, LogType type)
{
    //do something
}

# Set up a beta version

/**
* Set whether the version is the beta
* @param isBeta : true is beta version(true or false)
*/
Crasheye.SetIsBetaVersion(isBeta)
Last Updated: 6/28/2022, 3:28:16 PM