Cocos Plugin Integration

1 Overview

CrashSight Cocos Plugin is a native CrashSight (iOS/Android) SDK interface for encapsulating apps (iOS/Android), based on Cocos engine. It facilitates the calling of CrashSight’s native SDK. It can be used in SDK initialization, setting custom user info, errors, etc., and auto detection and reporting app script (Lua) errors and info of crashes caused by native code (Object-C, Java, C/C++, etc.). It provides real-time, multi-dimensional exception analysis. Preparations: If you haven’t registered your app, please contact CrashSight website administrator to register a new app and obtain a CrashSight AppID. Note: the exported Android project and iOS project need two AppIDs.

2 Integration Steps

2.1 Download CrashSIght Cocos Plugin

Download CrashSight Cocos Plugin (Download is unavailable due to an ongoing internal review. To download it, please contact WeTest@wetest.net) Install plugins according to the programming language of your Cocos project (c++, lua). Plugin bundle structure:

• CocosPlugin
• CrashSight: Supports C++ interface encapsulation
• CrashSight/Lua: Support Lua interface encapsulation
• agent: Interface encapsulation of native SDK (iOS/Android)
• CrashSightSDK: Native SDK (iOS/Android)

2.2 Integrate CrashSight Cocos Plugin

iOS Project Configurations

Open the Xcode project under the proj.ios_mac directory. Add the header file and source file in the CrashSigh directory into the project, and add the source file into the Compile Sources of the specified Target, as shown in the image

Add the CrashSight.framework under the CrashSightCore.framework, CrashSightPlugin.framework, and CrashSightSDK/iOS directories of aget/iOS directory to the Xcode project, and add the -force_load mark to the other Linker Flags configuration item of Build Settings. Set a path for CrashSightPlugin.framework. As shown in the image

Check the Link Binary With Libraries configuration item of Build Phases of the Xcode project. Make sure the dynamic library dependency has been added. As shown in the image

Android Project Configurations

Copy files under the CocosPlugin/CrashSight directory to the Crashes/CrashSightCocosPlugin/Android directory, as shown in the image

Open the Android project of the proj.android (or proj.android_studio) directory. Add the .jar under the agent/Android and CrashSightSDK/Android directories to the project’s libs directory. Add the libCrashSight.so under the CrashSightSDK/Android directory and the libCrashSightCore.so under the agent/Android/libs directory to the project’s jni/prebuilt directory, as shown in the image

Edit the proj.android/jni/Android.mk file and add the following configuration:

# Integrate libCrashSight.so and libCrashSightCore.so. Add them after the "LOCAL_PATH := $(call my-dir)" line:
include $(CLEAR_VARS)
LOCAL_MODULE := CrashSightCore
LOCAL_SRC_FILES := prebuilt/$(TARGET_ARCH_ABI)/libCrashSightCore.so
include $(PREBUILT_SHARED_LIBRARY)
include $(CLEAR_VARS)
LOCAL_MODULE := CrashSight
LOCAL_SRC_FILES := prebuilt/$(TARGET_ARCH_ABI)/libCrashSight.so
include $(PREBUILT_SHARED_LIBRARY)
include $(CLEAR_VARS)
#======

# After the "LOCAL_SRC_FILES :=" line:
LOCAL_SRC_FILES += ../../../Classes/CrashSightCocosPlugin/Android/UQMCrashBridge.cpp

# After the "LOCAL_C_INCLUDES :=" line
LOCAL_C_INCLUDES += $(LOCAL_PATH)/../../../Classes/CrashSightCocosPlugin/Android

# Include the dynamic library before the "include $(BUILD_SHARED_LIBRARY)" line
LOCAL_SHARED_LIBRARIES := CrashSight CrashSightCore

Edit the AndroidManifest.xml file and add the following permission declaration

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

Initialization

Call interface static void Init(const char *appId, bool unexpectedTerminatingDetectionEnable, bool debugMode, const char *serverUrl)in the AppDelegate::applicationDidFinishLaunching() method of the Classes/AppDelegate.cpp

Initialize Code Example：

Note: For Android, libCrashSightCore.so must be loaded before initialization. Code example:

2.3 Supports Lua Script Error Detection, for Cocos Lua Projects Only

iOS Project Configurations

Open the Xcode project under the proj.ios_mac directory. Add the header file and source file in the CrashSight/lua directory into the project, and add the source file into the Compile Sources of the Target, as shown in the image

Android Project Configurations

Copy files under the CocosPlugin/CrashSight/lua directory to the Crashes/CrashSightCocosPlugin/Android directory, as shown in the image

Edit the proj.android/jni/Android.mk file and add the following configuration:

# After the "LOCAL_SRC_FILES :=" line
LOCAL_SRC_FILES += ../../../Classes/CrashSightCocosPlugin/Android/lua/lua_CrashSight_auto.cpp
# After the "LOCAL_C_INCLUDES :=" line
LOCAL_C_INCLUDES += $(LOCAL_PATH)/../../../Classes/CrashSightCocosPlugin/Android/lua

Example:

LOCAL_PATH := $(call my-dir)

# Integrate libCrashSigh.so and libCrashSightCore.so. Add them after the "LOCAL_PATH := $(call my-dir)" line
include $(CLEAR_VARS)
LOCAL_MODULE := CrashSightCore
LOCAL_SRC_FILES := prebuilt/$(TARGET_ARCH_ABI)/libCrashSightCore.so
include $(PREBUILT_SHARED_LIBRARY)

include $(CLEAR_VARS)
LOCAL_MODULE := CrashSight
LOCAL_SRC_FILES := prebuilt/$(TARGET_ARCH_ABI)/libCrashSight.so
include $(PREBUILT_SHARED_LIBRARY)
include $(CLEAR_VARS)
# ======

LOCAL_MODULE := cocos2dlua_shared

LOCAL_MODULE_FILENAME := libcocos2dlua

LOCAL_SRC_FILES := \
../../../Classes/AppDelegate.cpp \
hellolua/main.cpp
LOCAL_SRC_FILES += ../../../Classes/CrashSightCocosPlugin/Android/UQMCrashBridge.cpp
LOCAL_SRC_FILES += ../../../Classes/CrashSightCocosPlugin/Android/lua/lua_CrashSight_auto.cpp

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../../Classes
LOCAL_C_INCLUDES += $(LOCAL_PATH)/../../../Classes/CrashSightCocosPlugin/Android
LOCAL_C_INCLUDES += $(LOCAL_PATH)/../../../Classes/CrashSightCocosPlugin/Android/lua

# _COCOS_HEADER_ANDROID_BEGIN
# _COCOS_HEADER_ANDROID_END

LOCAL_STATIC_LIBRARIES := cclua_static

# _COCOS_LIB_ANDROID_BEGIN
# _COCOS_LIB_ANDROID_END

LOCAL_SHARED_LIBRARIES := CrashSight CrashSightCore
include $(BUILD_SHARED_LIBRARY)

$(call import-module, cocos/scripting/lua-bindings/proj.android)

# _COCOS_LIB_IMPORT_ANDROID_BEGIN
# _COCOS_LIB_IMPORT_ANDROID_END

Register the Listening Callback Function of Lua Script Error

Call interface int register_all_CrashSight(lua_State* tolua_S) in the AppDelegate::applicationDidFinishLaunching() method of the Classes/AppDelegate.cpp file and initialize

Code example:

Call the interface of Lua script error report in the _G_TRACKBACK callback function of Lua script

UQMCrashBridge:ReportException(int type, const char *exceptionName, const char *exceptionMsg, const char *exceptionStack)
__G__TRACKBACK__ = function(msg)
-- record the message
local message = msg;
-- auto genretated
local msg = debug.traceback(msg, 3)
print(msg)
-- report lua exception
UQMCrashBridge:ReportException(6, "luaErrorType", tostring(message), debug.traceback())
return msg
end