‹ Apteligent Doc Home

Apteligent 集成指南

For the C++ version of cocos2d-x v3.x - (all other versions)

集成

注册一个 Apteligent 帐号并且创建一个 app 。

在您确保正确安装了 SDKBOX installer 的情况下，运行下面的命令来集成 SDKBOX Apteligent 插件。

$ sdkbox import apteligent

重点注意事项

如果您升级到了 Xcode7, 则需要以下额外步骤来确保插件工作正常:

禁用应用程序安全传输策略

添加以下项到 plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

添加后的文件内容看起来就像这样：

禁止 Bitcode 支持

您必须禁止 Bitcode 的支持，否则将会编译失败。

游戏全屏配置

如果您的游戏不同时支持横竖屏，则必须在 Xcode 中选中 Requires full screen，否则将不会通过 Apple 的审核。

canOpenURL 白名单

取决于您使用哪些插件。需要在 info.plist 的 LSApplicationQueriesSchemes 下添加名单。

关于 Creator 工程

Creator 导出工程会修改工程的配置, 这可能会影响 SDKBox 对工程的配置修改. 所以可以有以下做法(任选其一):

1. 保存导出工程中的修改, 对于 SDKBox 来说可能有这些文件(mk, gradle, gradle.properties, AppDelegate.cpp, ...), 导出后再恢复对应该文件
2. 在每一次 Creator 导出工程后, 重新 import 插件.

推荐第一种, 但是第一种的麻烦点在于, 对于第一次(或很久没接触的人)可能会有露掉某个文件 第二种, 很方便, 它的麻烦点在于, 如果你对工程有自己的修改, SDKBox 的重新 import 不能帮你恢复.

JSON 配置

SDKBOX Installer 将会自动在您的 sdkbox_config.json 中插入一份配置样例。请修改这份配置样例，使其能用于您自己的 app 。

• id: Apteligent App ID

可选项

---

• monitor_connection [bool]: (iOS only)

  • true [default]
  • false

Determines whether Service Monitoring should capture network performance information for network calls made through NSURLConnection.

• monitor_session [bool]: (iOS only)

  • true [default]
  • false

Determines whether Service Monitoring should capture network performance information for network calls made through NSURLSession.

• enable_service_monitoring [bool]:

  • true [default]
  • false

This flag determines wither Apteligent service monitoring is enabled at all.

• delay_sending_appload [bool]:

  • true
  • false [default]

Delay to reports an app load event.

• url_filters [array]:

  • ["http://www.gmail.com", "www.other.com"]

These filters are used to make it so certain network performance information is not reported to Apteligent.

• logcat_reporting_enabled: (Android only) Include Logcat

  • true
  • false [default]

Including system log data (Logcat) can be helpful for debugging crashes and handled exceptions, but it comes at the cost of slightly increasing disk and network usage, which is why this feature must be manually enabled. Apteligent collects the last 100 lines of logcat data.

more information:

• https://docs.crittercism.com/ios/ios.html
• https://docs.crittercism.com/android/android.html

Example:

{
    "ios": {
        "Apteligent":{
            "debug":true,
            "id":"956194d922984692a3184816ec3a510300555300",
            "monitor_connection":true,
            "monitor_session":true,
            "enable_service_monitoring":true,
            "delay_sending_appload":false,
            "url_filters":[
                "https://metrics.sdkbox.com",
                "http://www.gmail.com"
            ]
        }
    },
    "android": {
        "Apteligent":{
            "debug":true,
            "id":"3f66168979494ce38374b4d32d637dcc00555300",
            "enable_service_monitoring":true,
            "delay_sending_appload":false,
            "url_filters":[
                "https://metrics.sdkbox.com",
                "http://www.gmail.com"
            ],
            "version":"version:2.0.4 build:4981 codeName:Cactus",
            "version_string_include_version_code":true,
            "logcat_reporting_enabled":true
        }
    }
}

使用

初始化 Apteligent

在您的代码的合适的位置初始化这个插件，我们建议您在 AppDelegate:applicationDidFinishLaunching() 或者 AppController:didFinishLaunchingWithOptions() 中进行初始化。并确保您的代码中包含了正确的头文件。举例如下：

#include "PluginApteligent/PluginApteligent.h"
AppDelegate::applicationDidFinishLaunching()
{
     sdkbox::PluginApteligent::init();
}

注册追踪器 Breadcrumbs

// leave a breadcrumb
sdkbox::PluginApteligent::leaveBreadcrumb("User tapped start button");

// perform all breadcrumb writes on a background thread
sdkbox::PluginApteligent::setAsyncBreadcrumbMode(true);

注册用户元数据

// Adding a Username
sdkbox::PluginApteligent::setUsername("MrsCritter");

// Adding Arbitrary User Metadata
sdkbox::PluginApteligent::setValueforKey("5", "Game Level");

注册用户流

// Beginning a Userflow
sdkbox::PluginApteligent::beginUserflow("login");

// Ending a Userflow
sdkbox::PluginApteligent::endUserflow("login");

// Failing a Userflow
sdkbox::PluginApteligent::failUserflow("login");

// Cancelling a Userflow
sdkbox::PluginApteligent::cancelUserflow("login");

修改用户流的值

int valueInCents = sdkbox::PluginApteligent::valueForUserflow("my_userflow");
valueInCents += 5;
sdkbox::PluginApteligent::setValueforUserflow(valueInCents, "my_userflow");

注册网络请求

sdkbox::PluginApteligent::logNetworkRequest("GET", "http://www.abc123def456.com", 2.0, 1000, 100, 200);

过滤截获数据

sdkbox::PluginApteligent::addFilter("www.gmail.com");

配置位置坐标

// Beijing, China
sdkbox::PluginApteligent::updateLocation(39.9042, 116.4074);

其他任务

// Allowing Users to Opt Out of Apteligent
sdkbox::PluginApteligent::setOptOutStatus(true);

// Changing the verbosity of Apteligent’s Logs
// sdkbox::CRLoggingLevelSilent  : Turns off all Apteligent log messages
// sdkbox::CRLoggingLevelError   : Only print errors. An error is an unexpected event that will result not capturing important data
// sdkbox::CRLoggingLevelWarning : (Default) Only print warnings. Currently warning messages are printed when calling Apteligent methods before initializing Apteligent.
// sdkbox::CRLoggingLevelInfo    : The most verbose level of logging
sdkbox::PluginApteligent::setLoggingLevel(sdkbox::CRLoggingLevelInfo);

// Send App Load Data
// You must set `"delay_sending_appload":true` in `sdkbox_config.json` first
sdkbox::PluginApteligent::sendAppLoadData();

实现 ApteligentListener

• 您可以实现 ApteligentListener 用来设置回调，比如当一个视频播放完成的时候。

#include "PluginApteligent/PluginApteligent.h"
class MyClass : public sdkbox::ApteligentListener
{
private:
    void onCrashOnLastLoad() {} // not support on android
}

API Reference

Methods

static bool init ( ) ;

initialize the plugin instance.

static void setListener ( ApteligentListener * listener ) ;

Set listener to listen for apteligent events

static ApteligentListener * getListener ( ) ;

Get the listener

static void removeListener ( ) ;

Remove the listener, and can't listen to events anymore

static void addFilter ( const std::string & filter ) ;

Adds an additional filter for network instrumentation.

static void leaveBreadcrumb ( const std::string & breadcrumb ) ;

Breadcrumbs provide the ability to track activity within your app.

static void setAsyncBreadcrumbMode ( bool writeAsync ) ;

By default, breadcrumbs are flushed to disk immediately when written. This is by design - in order to provide an accurate record of everything that happened up until the point your app crashed.

static void updateLocation ( double latitude , double longitude ) ;

Inform Apteligent of the device's most recent location for use with performance monitoring.

static bool logNetworkRequest ( const std::string & method ,
                                const std::string & urlString ,
                                long latency ,
                                long bytesRead ,
                                long bytesSent ,
                                long responseCode ) ;

Logging endpoints is a way of manually logging custom network library network access to URL's which fall outside Apteligent's monitoring of NSURLConnection and ASIHTTPRequest method calls.

static void setOptOutStatus ( bool status ) ;

If you wish to offer your users the ability to opt out of Apteligent crash reporting, you can set the OptOutStatus to YES. If you do so, any pending crash reports will be purged.

static bool getOptOutStatus ( ) ;

Retrieve current opt out status.

static void setMaxOfflineCrashReports ( int max ) ;

Set the maximum number of crash reports that will be stored on the local device if the device does not have internet connectivity. If more than |maxOfflineCrashReports| crashes occur, the oldest crash will be overwritten. Decreasing the value of this setting will not delete any offline crash reports. Unsent crash reports will be kept until they are successfully transmitted to Apteligent, hence there may be more than |maxOfflineCrashReports| stored on the device for a short period of time.

static int maxOfflineCrashReports ( ) ;

Get the maximum number of Apteligent crash reports that will be stored on the local device if the device does not have internet connectivity.

static std::string getUserUUID ( ) ;

Get the Apteligent generated unique identifier for this device.

static void setUsername ( const std::string & username ) ;

Associate a username string with the device's Apteligent UUID. This will send the association to Apteligent's back end.

static void setValueforKey ( const std::string & value ,
                             const std::string & key ) ;

Associate an arbitrary key/value pair with the device's Apteligent UUID.

static bool didCrashOnLastLoad ( ) ;

Did the application crash on the previous load?

static void beginUserflow ( const std::string & name ) ;

Init and begin a userflow with a default value.

static void beginUserflow ( const std::string & name , int value ) ;

Init and begin a userflow with an input value.

static void cancelUserflow ( const std::string & name ) ;

Cancel a userflow as if it never existed.

static void endUserflow ( const std::string & name ) ;

End an already begun userflow successfully.

static void failUserflow ( const std::string & name ) ;

End an already begun userflow as a failure.

static int valueForUserflow ( const std::string & name ) ;

Get the currency cents value of a userflow.

static void setValueforUserflow ( int value , const std::string & name ) ;

Set the currency cents value of a userflow.

static void sendAppLoadData ( ) ;

Tell Apteligent to send app load event. By default, Apteligent will send app load event automatically when your app is started However, if you set delaySendingAppLoad flag to YES on config, you can call this method to manually send app load event.

static void setLoggingLevel ( int loggingLevel ) ;

Set the logging level to tune the verbosity of Apteligent log messages.

Listeners

void onCrashOnLastLoad ( ) {

Notifies the delegate that the app has crash last time.

手动集成

如果 SDKBOX 安装器 安装插件失败了，那么需要手动集成插件.如果安装器安装插件成功了,那么不需要，也没必要,按文档再手动集成一次.

下面列出的的步骤一般很少用到.如果你按下面的步骤完成了集成，请在完成集成后，再按步骤检查一次.

iOS 平台手动集成

拖拽下列 framework 从 Apteligent 插件包的 plugins/ios 目录到您的 Xcode 工程中，在添加 frameworks 的时候，请勾选 Copy items if needed 。

sdkbox.framework

PluginApteligent.framework

Crittercism.framework

如果您没有添加下面这些系统库，您有需要添加它们：

SystemConfiguration.framework

CoreLocation.framework

Android 手动集成

SDKBox 支持三种 Android 工程, command-line, eclipse 和 Android Studio.

• command-line 和 eclipse 类型的项目, <project_root> 指代 proj.android .
• Android Studio 类型的项目, <project_root> 指代 proj.android-studio .

拷贝文件

从插件安装包中的 plugin/android/libs 目录拷贝所有文件到您的工程的 proj.android/libs 目录。

• 如果你使用 cocos2d-x 源码，拷贝 jar 文件到：

  Android command-line: cocos2d/cocos/platform/android/java/libs

  Android Studio: cocos2d/cocos/platform/android/libcocos2dx/libs

• 如果你使用 cocos2d-js 或者 lua ，拷贝 jar 文件到:

  Android command-line: frameworks/cocos2d-x/cocos/platform/android/java/libs

  Android Studio: frameworks/cocos2d-x/cocos/platform/android/libcocos2dx/libs

• 如果你使用 cocos2d-x 预编译包，拷贝 jar 文件到：

  Android command-line: proj.android/libs

拷贝 jni 库

从 plugin/android/jni/ 拷贝并覆盖 <your_project_root>/jni/ 目录.

编辑 AndroidManifest.xml

在标签 application tag 上添加下列权限：

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

编辑 Android.mk

编辑 proj.android/jni/Android.mk：

为 LOCAL_WHOLE_STATIC_LIBRARIES 添加额外的库：

LOCAL_WHOLE_STATIC_LIBRARIES += PluginApteligent
LOCAL_WHOLE_STATIC_LIBRARIES += sdkbox

在所有 import-module 语句之前添加一条 call 语句：

$(call import-add-path,$(LOCAL_PATH))

在最后添加额外的 import-module 语句：

$(call import-module, ./sdkbox)
$(call import-module, ./pluginapteligent)

这意味着您的语句顺序看起来像是这样：

$(call import-add-path,$(LOCAL_PATH))
$(call import-module, ./sdkbox)
$(call import-module, ./pluginapteligent)

Note: 如果您使用的是 cocos2d-x 预编译库，那么保证这些语句在已有的 $(call import-module,./prebuilt-mk) 语句之上非常重要。

编辑 Application.mk （只限 Cocos2d-x v3.0 到 v3.2 版本）

编辑 proj.android/jni/Application.mk 保证 APP_STL 的定义正确。如果 Application.mk 包含了 APP_STL := c++_static 语句，那么这条语句应该被改为：

APP_STL := gnustl_static

修改 AppActivity.java

插件版本 >= 2.4.0.3

1. 找到 AppActivity.java 文件

find . -name "AppActivity.java"

1. 把 extends Cocos2dxActivity 替换为 extends com.sdkbox.plugin.SDKBoxActivity

以下是 AppActivity.java 不同版本的引擎所在的目录：

cpp
  - proj.android/src/org/cocos2dx/cpp/AppActivity.java
  - proj.android-studio/app/src/org/cocos2dx/cpp/AppActivity.java
  - proj.android/app/src/org/cocos2dx/cpp/AppActivity.java ( from cocos2d-x 3.17)

lua
  - frameworks/runtime-src/proj.android/src/org/cocos2dx/lua/AppActivity.java
  - frameworks/runtime-src/proj.android-studio/app/src/org/cocos2dx/lua/AppActivity.java
  - frameworks/runtime-src/proj.android/app/src/org/cocos2dx/lua/AppActivity.java (from cocos2d-x 3.17)

js
  - frameworks/runtime-src/proj.android/src/org/cocos2dx/javascript/AppActivity.java
  - frameworks/runtime-src/proj.android/app/src/org/cocos2dx/javascript/AppActivity.java ( from cocos2d-x 3.17)

插件版本 < 2.4.0.3

• 如果您使用 cocos2d-x 源代码，假设您在 proj.android 目录下，那么您可以在如下位置找到 Cocos2dxActivity.java 文件：

  ../../cocos2d-x/cocos/platform/android/java/src/org/cocos2dx/ lib/Cocos2dxActivity.java

• 如果您使用 cocos2dx-x 预编译库， 假设您在 proj.android 目录下，那么您可以在如下位置找到 Cocos2dxActivity.java 文件：

  ./src/org/cocos2dx/lib/Cocos2dxActivity.java

Note: 当你使用 cocos2d-x 源代码时，不同的版本中 Cocos2dxActivity.java 文件的位置也不同。一个确定该文件位置的方法是查看 proj.android/project.properties 。比如：

android.library.reference.1=../../cocos2d-x/cocos/platform/android/java

在这个例子中， Cocos2dxActivity.java 文件应该在如下位置：

../../cocos2d-x/cocos/platform/android/java/src/org/cocos2dx/lib/Cocos2dxActivity.java

• 修改 Cocos2dxActivity.java 文件，导入如下包：

import android.content.Intent;
import com.sdkbox.plugin.SDKBox;

• 然后，修改 Cocos2dxActivity 类的 onCreate(final Bundle savedInstanceState) 函数，添加一个调用语句 SDKBox.init(this); 。添加的位置非常重要，必须在调用 onLoadNativeLibraries(); 之后。如下：

onLoadNativeLibraries();
SDKBox.init(this);

• 最后, 我需要提供合适的 overrides 方法的代码。这里有一些约定如下。

  • 如果这个被列出的方法没有在 SDKBox 中定义，那么__定义它__。

  • 如果这个被列出的方法已经被定义在 SDKBox 中，那么请调用这个在 SDKBox 中的__同名方法__。

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
          if(!SDKBox.onActivityResult(requestCode, resultCode, data)) {
            super.onActivityResult(requestCode, resultCode, data);
          }
    }
    @Override
    protected void onStart() {
          super.onStart();
          SDKBox.onStart();
    }
    @Override
    protected void onStop() {
          super.onStop();
          SDKBox.onStop();
    }
    @Override
    protected void onResume() {
          super.onResume();
          SDKBox.onResume();
    }
    @Override
    protected void onPause() {
          super.onPause();
          SDKBox.onPause();
    }
    @Override
    public void onBackPressed() {
          if(!SDKBox.onBackPressed()) {
            super.onBackPressed();
          }
    }

使用 Proguard （release模式下可选）

• 编辑 project.properties 文件， 指定一个 Proguard 配置文件。比如：

proguard.config=proguard.cfg

• 编辑这个配置文件，加入如下内容：

# If your project uses WebView with JS, uncomment the following
# and specify the fully qualified class name to the JavaScript interface
# class:
#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
#   public *;
#}

# cocos2d-x
-keep public class org.cocos2dx.** { *; }
-dontwarn org.cocos2dx.**
-keep public class com.chukong.** { *; }
-dontwarn com.chukong.**

# google play service
-keep public class com.google.android.gms.** { public *; }
-dontwarn com.google.android.gms.**

-keep class * extends java.util.ListResourceBundle {
    protected Object[][] getContents();
}

-keep public class com.google.android.gms.common.internal.safeparcel.SafeParcelable {
    public static final *** NULL;
}

-keepnames @com.google.android.gms.common.annotation.KeepName class *
-keepclassmembernames class * {
    @com.google.android.gms.common.annotation.KeepName *;
}

-keepnames class * implements android.os.Parcelable {
    public static final ** CREATOR;
}

#sdkbox
-keep public class com.sdkbox.** { *; }
-dontwarn com.sdkbox.**

# apteligent
-keep public class android.webkit.** { *; }
-dontwarn android.webkit.**
-keep public class com.crittercism.**
-keepclassmembers public class com.crittercism.*
{
    *;
}

Note: Proguard 只能工作在 Release 模式下 （比如： cocos run -m release） debug 模式下不会触发 Proguard 。