Flurry Analytics 集成指南

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

集成

用如下命令来集成 SDKBOX Flurry Analytics 插件,请确保您可以正常执行的 SDKBOX 安装器.

sdkbox import flurryanalytics

重点注意事项

如果您升级到了 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 对工程的配置修改. 所以可以有以下做法(任选其一):

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

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

JSON 配置

SDKBOX 安装器会自动在您的工程中添加一个样例配置文件 sdkbox_config.json.在您编译工程前,请用您自己的应用信息修改里面的参数值

下面给出一个 Flurry Analytics 的配置样例,您需要用在 Flurry Analytics ID注册的帐号信息,替换 <API KEY>.

下面给出一个 iOS 下的配置例子

"FlurryAnalytics":{
            "APIKey":"<API KEY>",
            "AppVersion":"V0.1",
            "Debug":false,
            "Level":2,
            "SessionTimeout":10,
            "CrashReport":true
}

Android上的配置文件要复杂一点，里面包含了 locations, pulse and origin 的一些设置,下面给出一个例子:

"FlurryAnalytics":{
            "APIKey":"<API KEY>",
            "AppVersion":"V0.1",
            "Debug":false,
            "LogEvent":true,
            "Level":2,
            "SessionTimeout":10,
            "CrashReport":true,
            "LocationReport":true,
            "DefLocationLat":104.06,
            "DefLocationLon":30.67,
            "Pulse":true,
            "Origin":[
                {
                    "OriginName":"sdkbox",
                    "OriginVersion":"v0.1",
                    "OriginParams":{
                        "Key1":"Val1",
                        "Key2":"Val2",
                        "Key3":"Val3"
                    }
                },
                {
                    "OriginName":"sdkbox",
                    "OriginVersion":"v0.1"
                }
            ]
}

使用

初始化 Flurry Analytics

在您的代码合适的地方初始化插件, 我们建议您在 AppDelegate::applicationDidFinishLaunching() 或 AppController:didFinishLaunchingWithOptions() 中完成初始化. 请确保您包含了对应的头文件:

#include "PluginFlurryAnalytics/PluginFlurryAnalytics.h"
AppDelegate::applicationDidFinishLaunching()
{
     sdkbox::PluginFlurryAnalytics::init();
     // start session
     sdkbox::PluginFlurryAnalytics::startSession();
}

使用 Flurry Analytics

在初始化完成后,您就可以使用 Flurry Analytics 提供的功能了. 在您的代码中任意地方,使用 logevent:

std::string eventName = "test event1";
sdkbox::PluginFlurryAnalytics::logEvent(eventName);

接收 Flurry Analytics 事件 (可选)

您可以接收 Flurry Analytics 事件, 确定 Flurry 会话是否创建成功.

让您的类继承 sdkbox::FlurryAnalyticsListener

#include "PluginFlurryAnalytics/PluginFlurryAnalytics.h"
class MyClass : public sdkbox::FlurryAnalyticsListener
{
public:
      void flurrySessionDidCreateWithInfo(std::map<std::string, std::string>& info);
};

创建一个 listener 来处理回调:

sdkbox::PluginFlurryAnalytics::setListener(this);

结束 Flurry Analytics (只在 Android 上有效)

当您不再使用 FlurryAnalytics 或您的游戏结束时, 必须要把 FlurryAnalytics 会话结束. 这个在 Android 上必须调用,但是在 iOS 上是可选的. 比如:

// 这个只在 android 上有效, 但是您在 iOS 调用,也没有关系
sdkbox::PluginFlurryAnalytics::endSession();

API Reference

Methods

static bool init ( ) ;

init plugin, must be first invoke

static void setAppVersion ( const std::string & version ) ;

Explicitly specifies the App Version that Flurry will use to group Analytics data.

static std::string getFlurryAgentVersion ( ) ;

Retrieves the Flurry Agent Build Version.

static void setShowErrorInLogEnabled ( bool value ) ;

Displays an exception in the debug log if thrown during a Session.

static void setDebugLogEnabled ( bool value ) ;

Generates debug logs to console.

static void setLogLevel ( FA_FlurryLogLevel value ) ;

Generates debug logs to console.

static void setSessionContinueSeconds ( float seconds ) ;

Set the timeout for expiring a Flurry session.

static void setCrashReportingEnabled ( bool value ) ;

Enable automatic collection of crash reports.

static void startSession ( ) ;

Start a Flurry session for the project denoted by apiKey.

static void endSession ( ) ;

end session, just valid on Android

static bool activeSessionExists ( ) ;

Start a Flurry session for the project denoted by apiKey.

static std::string getSessionID ( ) ;

Start a Flurry session for the project denoted by apiKey.

static void pauseBackgroundSession ( ) ;

Pauses a Flurry session left running in background. on valid on iOS

static void addOrigin ( const std::string & originName ,
                        const std::string & originVersion ) ;

Adds an SDK origin specified by originName and originVersion.

static void addOrigin ( const std::string & originName ,
                        const std::string & originVersion ,
                        std::map <std::string ,
                        std::string> & parameters ) ;

Adds a custom parameterized origin specified by originName with originVersion and parameters.

static void addOrigin ( const std::string & originName ,
                        const std::string & originVersion ,
                        const std::string & parameters ) ;

just for lua, js binding, have the same function with addOrigin(string, string, map)

static int logEvent ( const std::string & eventName ) ;

Records a custom event specified by eventName.

static int logEvent ( const std::string & eventName ,
                      std::map <std::string ,
                      std::string> & parameters ) ;

Records a custom parameterized event specified by eventName with parameters.

static int logEvent ( const std::string & eventName ,
                      const std::string & parameters ) ;

just for lua, js binding, have same function with logEvent(string, map)

static int logEvent ( const std::string & eventName , bool timed ) ;

Records a timed event specified by eventName.

static int logEvent ( const std::string & eventName ,
                      std::map <std::string ,
                      std::string> & parameters ,
                      bool timed ) ;

Records a custom parameterized timed event specified by eventName with parameters.

static int logEvent ( const std::string & eventName ,
                      const std::string & parameters ,
                      bool timed ) ;

just for lua, js binding, have the same function with logEvent(string, map, bool)

static void endTimedEvent ( const std::string & eventId ) ;

End a timed event

static void endTimedEvent ( const std::string & eventName ,
                            std::map <std::string ,
                            std::string> & parameters ) ;

Ends a timed event specified by eventName and optionally updates parameters with parameters.

static void endTimedEvent ( const std::string & eventName ,
                            const std::string & parameters ) ;

just for lua, js binding, have same function with endTimeEvent(string, map)

static void logError ( const std::string & errorID ,
                       const std::string & message ,
                       const std::string & info ) ;

Records an app exception. Commonly used to catch unhandled exceptions.

static void logPageView ( ) ;

Explicitly track a page view during a session.

static void setUserID ( const std::string & userID ) ;

Assign a unique id for a user in your app.

static void setAge ( int age ) ;

Set your user's age in years.

static void setGender ( const std::string & gender ) ;

Set your user's gender.

     static void setReportLocation ( bool reportLocation ) ;

Set whether Flurry should record location via GPS. Defaults to true. valid on Android

static void setLatitude ( double latitude ,
                          double longitude ,
                          float horizontalAccuracy ,
                          float verticalAccuracy ) ;

Set the location of the session.

static void clearLocation ( ) ;

clear the default location.valid on Android

static void setSessionReportsOnCloseEnabled ( bool sendSessionReportsOnClose ) ;

Set session to report when app closes.valid on iOS

static void setSessionReportsOnPauseEnabled ( bool setSessionReportsOnPauseEnabled ) ;

Set session to report when app is sent to the background.valid on iOS

static void setBackgroundSessionEnabled ( bool setBackgroundSessionEnabled ) ;

Set session to support background execution.valid on iOS

static void setEventLoggingEnabled ( bool value ) ;

Enable custom event logging.

static void setPulseEnabled ( bool value ) ;

Enables Flurry Pulse

static void setListener ( FlurryAnalyticsListener * listener ) ;

set listener for session callback

static FlurryAnalyticsListener * getListener ( ) ;

get listener

static void removeListener ( ) ;

remove listener, just set null, will not delete it the user should delete listener self

Listeners

void flurrySessionDidCreateWithInfo ( std::map <std::string ,
                                      std::string> & info );

Invoked when analytics session is created,

手动集成

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

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

iOS 平台手动集成

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

sdkbox.framework

PluginFlurryAnalytics.framework

上面的 frameworks 依赖于其他 frameworks。如果您没有添加它们，您也需要添加下列这些 frameworks：

Security.framework

SystemConfiguration.framework

Android 平台手动集成

拷贝文件

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

FlurryAnalytics-5.5.0.jar

PluginFlurryAnalytics.jar

sdkbox.jar

如果你使用 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

从 plugin/android/jni 目录拷贝 pluginflurryanalytics 以及 sdkbox 目录到您的工程的 proj.android/jni 目录。如果 sdkbox 目录在工程中已经存在，请覆盖它。

编辑 `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.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

使 hardware acceleration 属性生效。这一标签是一个在新版本 sdk 上的选项，不能用于2.3.3版本。

<android:hardwareAccelerated="true" />

编辑 `Android.mk`

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

为 LOCAL_STATIC_LIBRARIES 添加额外的库：

LOCAL_STATIC_LIBRARIES += PluginFlurryAnalytics
LOCAL_STATIC_LIBRARIES += sdkbox

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

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

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

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

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

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

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

找到 AppActivity.java 文件

find . -name "AppActivity.java"

把 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();
          }
    }

混淆 (release, optional)

编辑 project.properties 指定一个 Proguard 配置文件. 比如:

proguard.config=proguard.cfg

编辑配置文件包含如下内容:

-dontwarn android.webkit.**

注意: 混淆只在 Release 编译模式下有效 (i.e cocos run -m release) debug 编译下不会调用到混淆规则.

Flurry Analytics 集成指南

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

集成

重点注意事项

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

禁止 Bitcode 支持

游戏全屏配置

canOpenURL 白名单

关于 Creator 工程

JSON 配置

使用

初始化 Flurry Analytics

使用 Flurry Analytics

接收 Flurry Analytics 事件 (可选)

结束 Flurry Analytics (只在 Android 上有效)

API Reference

Methods

Listeners

手动集成

iOS 平台手动集成

Android 平台手动集成

拷贝文件

编辑 AndroidManifest.xml

编辑 Android.mk

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

修改 AppActivity.java

插件版本 >= 2.4.0.3

插件版本 < 2.4.0.3

混淆 (release, optional)

编辑 `AndroidManifest.xml`

编辑 `Android.mk`

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

修改 `AppActivity.java`