‹ Tune Doc Home

Tune 集成指南

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

集成

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

sdkbox import tune

~~从 China 服务器下载~~ 服务器已停止

如果你在中国, 并且下载插件的速度比较慢, 可以尝试使用位于中国的服务器来下载, 查询插件, 使用方法为在你的 sdkbox import 后加 --server china 及可, 比如:

sdkbox import xxx  --server china

xxx 为你的插件名字

重点注意事项

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

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

添加以下项到 plist:

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

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

禁止 Bitcode 支持

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

游戏全屏配置

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

canOpenURL 白名单

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

JSON 配置

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

对于一个 Tune 插件的配置样例,您需要将其中的 <TUNE id> 以及 <TUNE KEY> 替换成您特定的 Tune ID 帐号中的信息。 如下是一个添加 Tune 插件的配置样例:

"Tune":{
    "id":"<TUNE ID>",
    "key":"<TUNE KEY>",
    "debug":false
}

使用

初始化 Tune

在您的代码的合适的位置初始化这个插件,我们建议您在 AppDelegate:applicationDidFinishLaunching() 或者 AppController:didFinishLaunchingWithOptions() 中进行初始化。并确保您的代码中包含了正确的头文件。init() 以及 mesaureSession() 函数将会被调用。举例如下:

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

使用 Tune

在初始化之后,您可以开始使用 Tune 插件的功能了。Tune 使用 events 这个概念(就像 MAT Native Event Types__一样)。您可以在您需要的地方将 __events 记入日志,并且在稍后通过基于 web 的报告阅读器查看它们。Tune 在文档中为这些 events 提供一种结构。举例如下:

{
    PluginTune::measureEventName("purchase");
    PluginTune::measureEventId(1122334455);
        TuneEvent event;
    event.eventName = "purchase2";
    event.refId     = "RJ1357";
    event.searchString = "sweet crisp red apples";
    event.attribute1 = "crisp";
    event.attribute2 = "red";
    event.quantity = 3;
    PluginTune::measureEvent(event);
}

需要注意的是,在 event PluginTune::measureEvent(event) 被调用之后,我们的事件将会被记入日志。

API Reference

Methods

static void setListener ( TuneListener * listener ) ;

set a listener to listen for event changes.

static TuneListener * getListener ( ) ;

Get the listener

static void removeListener ( ) ;

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

static void init ( ) ;

init the instance.

static void setDebugMode ( bool enable ) ;

Specifies that the server responses should include debug information.

static void setAllowDuplicateRequests ( bool allow ) ;

Set to YES to allow duplicate requests to be registered with the MAT server.

// use "checkForDeferredDeepLink"
static void checkForDeferredDeeplinkWithTimeout ( double timeout ) ;

Check for a deferred deeplink entry point upon app installation. This is safe to call at every app launch, since the function does nothing unless this is the first launch.

static void checkForDeferredDeepLink ( ) ;

Check for a deferred deeplink entry point upon app installation. This is safe to call at every app launch, since the function does nothing unless this is the first launch.

static void automateIapEventMeasurement ( bool automate ) ;

Enable automatic measurement of app store in-app-purchase events. When enabled, your code should not explicitly measure events for successful purchases related to StoreKit to avoid event duplication.

static void setFacebookEventLogging ( bool logging , bool limit ) ;

Set whether the MAT events should also be logged to the Facebook SDK. This flag is ignored if the Facebook SDK is not present.

static void setExistingUser ( bool existingUser ) ;

Set whether this is an existing user or a new one. This is generally used to distinguish users who were using previous versions of the app, prior to integration of the MAT SDK. The default is to assume a new user.

static void setAppleAdvertisingIdentifier ( const std::string & appleAdvertisingIdentifier ,
                                            bool adTrackingEnabled ) ;

Set the Apple Advertising Identifier available in iOS 6.

static void setAppleVendorIdentifier ( const std::string & appleVendorIdentifier ) ;

Set the Apple Vendor Identifier available in iOS 6.

static void setCurrencyCode ( const std::string & currencyCode ) ;

Sets the currency code.

static void setJailbroken ( bool jailbroken ) ;

Sets the jailbroken device flag.

static void setPackageName ( const std::string & packageName ) ;

Sets the package name (bundle identifier). Defaults to the Bundle Identifier of the app that is running the sdk.

static void setShouldAutoDetectJailbroken ( bool autoDetect ) ;

Specifies if the sdk should auto detect if the iOS device is jailbroken.

static void setShouldAutoGenerateAppleVendorIdentifier ( bool autoGenerate ) ;

Specifies if the sdk should pull the Apple Vendor Identifier from the device. Note that setting to false will clear any previously set value for the property.

// use "setPackageName"
static void setSiteId ( const std::string & siteId ) ;

Sets the site ID.

static void setTRUSTeId ( const std::string & tpid ) ;

Set the TRUSTe Trusted Preference Identifier (TPID).

static void setUserEmail ( const std::string & userEmail ) ;

Sets the user's email address.

static void setUserId ( const std::string & userId ) ;

Sets the user ID.

static void setUserName ( const std::string & userName ) ;

Sets the user's name.

static void setPhoneNumber ( const std::string & phoneNumber ) ;

Sets the user's phone number.

static void setFacebookUserId ( const std::string & facebookUserId ) ;

Set user's Facebook ID.

static void setTwitterUserId ( const std::string & twitterUserId ) ;

Set user's Twitter ID.

static void setGoogleUserId ( const std::string & googleUserId ) ;

Set user's Google ID.

static void setAge ( int userAge ) ;

Sets the user's age.

static void setGender ( Gender userGender ) ;

Sets the user's gender.

static void setLatitude ( double latitude , double longitude ) ;

Sets the user's location.

static void setLatitude ( double latitude ,
                          double longitude ,
                          double altitude ) ;

Sets the user's location including altitude.

static void setAppAdTracking ( bool enable ) ;

Set app-level ad-tracking.

static void setPayingUser ( bool isPayingUser ) ;

Set whether the user is generating revenue for the app or not. If measureEvent is called with a non-zero revenue, this is automatically set to YES.

static void setPreloadData ( const TunePreloadData & preloadData ) ;

Sets publisher information for attribution.

static void setPreloadDataForScript ( const std::string & jsonString ) ;
// use "tuneId"
static std::string matId ( ) ;

Get the MAT ID for this installation (mat_id).

static std::string tuneId ( ) ;

Get the Tune ID for this installation.

static std::string openLogId ( ) ;

Get the MAT log ID for the first app open (open_log_id).

static bool isPayingUser ( ) ;

Get whether the user is revenue-generating.

static void measureSession ( ) ;

To be called when an app opens; typically in the AppDelegate::applicationWillEnterForeground() event.

static void measureEventName ( const std::string & eventName ) ;

Record an event for an Event Name.

static void measureEventId ( int eventId ) ;

Record an event by providing the equivalent Event ID defined on the MobileAppTracking dashboard.

static void measureEvent ( const TuneEvent & event ) ;

Record an event with a MATEvent.

static void measureEventForScript ( const std::string & jsonString ) ;
static void setUseCookieTracking ( bool enable ) ;

Sets whether or not to use cookie based tracking.

static void setRedirectUrl ( const std::string & redirectUrl ) ;

Sets a url to be used with app-to-app tracking so that the sdk can open the download (redirect) url. This is used in conjunction with the setTracking:advertiserId:offerId:publisherId:redirect: method.

static void startAppToAppTracking ( const std::string & targetAppPackageName ,
                                    const std::string & targetAppAdvertiserId ,
                                    const std::string & targetAdvertiserOfferId ,
                                    const std::string & targetAdvertiserPublisherId ,
                                    bool shouldRedirect ) ;

Start an app-to-app tracking session on the MAT server.

static void applicationDidOpenURL ( const std::string & urlString ,
                                    const std::string & sourceApplication ) ;

Record the URL and Source when an application is opened via a URL scheme. This typically occurs during OAUTH or when an app exits and is returned to via a URL. The data will be sent to the HasOffers server when the next measureXXX method is called so that a Re-Engagement can be recorded.

static void setDeepLink ( const std::string & deepLinkUrl ) ;

Record the URL and Source when an application is opened via a URL scheme.

Listeners

void onMobileAppTrackerEnqueuedActionWithReferenceId ( const std::string & referenceId );
void onMobileAppTrackerDidSucceedWithData ( const std::string & data );
void onMobileAppTrackerDidFailWithError ( const std::string & errorString );
void onMobileAppTrackerDidReceiveDeeplink ( const std::string & deeplink ,
                                            bool timeout );
void onMobileAppTrackerDidFailDeeplinkWithError ( const std::string & errorString );

手动集成

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

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

iOS 平台手动集成

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

sdkbox.framework

PluginTune.framework

MobileAppTracker.framework

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

CoreTelephony.framework

Security.framework

SystemConfiguration.framework

AdSupport.framework

iAd.framework

MobileCoreServices.framework

StoreKit.framework

Android 平台手动集成

拷贝文件

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

PluginTune.jar

sdkbox.jar

MobileAppTracker-3.9.jar

plugin/android/jni 目录拷贝 plugintune 以及 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"/>

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

<android:hardwareAccelerated="true" />

application tag 也需要被创建:

<application ... >
    <receiver android:name="com.mobileapptracker.Tracker">
        <intent-filter>
            <action android:name="com.android.vending.INSTALL_REFERRER" />
        </intent-filter>
    </receiver>
    <meta-data android:name="com.google.android.gms.version"
               android:value="@integer/google_play_services_version" />
</application>

编辑 Android.mk

编辑 proj.android/jni/Android.mk

LOCAL_STATIC_LIBRARIES 添加额外的库:

LOCAL_STATIC_LIBRARIES += PluginTune
LOCAL_STATIC_LIBRARIES += sdkbox

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

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

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

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

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

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

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

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
import android.content.Intent;
import com.sdkbox.plugin.SDKBox;
onLoadNativeLibraries();
SDKBox.init(this);
    @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模式下可选)

proguard.config=proguard.cfg
-keep public class com.mobileapptracker.** {
    public *;
}

-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;
}

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

修改 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

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
import android.content.Intent;
import com.sdkbox.plugin.SDKBox;
onLoadNativeLibraries();
SDKBox.init(this);
    @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模式下可选)

proguard.config=proguard.cfg
-keep public class com.mobileapptracker.** {
    public *;
}

-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;
}

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