‹ Valuepotion Doc Home

Valuepotion 集成指南

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

集成

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

$ sdkbox import valuepotion

重点注意事项

如果您升级到了 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 安装器会自动在您的工程中添加一个样例配置文件 sdkbox_config.json .

下面给出一个 Valuepotion 的配置样例, 您需要替换 <client id> 和 <secret key> : - Valuepotion ID. - <sender id> 在 Android 上有效, 它是 GCM(google cloud message) 项目 id

"ValuePotion":{
    "clientId":"9666f9668a4db516c8aaea439464da44",
    "secretKey":"1c110ebcdeeda25d",
    "senderId":"111111"
}

使用

初始化 Valuepotion

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

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

使用 Valuepotion

sdkbox::PluginValuePotion::setTest(true);
sdkbox::PluginValuePotion::hasCachedInterstitial("default");

sdkbox::PluginValuePotion::trackEvent("test event");
sdkbox::PluginValuePotion::trackEvent("test event with value 23", 23);
sdkbox::PluginValuePotion::trackEvent("category", "event name", "label", 45);

sdkbox::PluginValuePotion::trackPurchaseEvent("test event", 56, "RMB", "order id", "product id");
sdkbox::PluginValuePotion::trackPurchaseEvent("test event", 67, "USD", "order id", "product id", "campaign id", "content id");
sdkbox::PluginValuePotion::trackPurchaseEvent("categroy", "event name", "label", 78, "ILY", "order id", "product id", "campaign id", "content id");

sdkbox::PluginValuePotion::userinfo("id", "user id");
sdkbox::PluginValuePotion::userinfo("serverid", "server id");
sdkbox::PluginValuePotion::userinfo("birth", "19991111"); //YYYYMMDD
sdkbox::PluginValuePotion::userinfo("gender", "M");
sdkbox::PluginValuePotion::userinfo("level", "9");
sdkbox::PluginValuePotion::userinfo("friends", "3");
sdkbox::PluginValuePotion::userinfo("accounttype", "facebook");

接收 ValuePotion 事件 (可选)

• 让您的类继承 sdkbox::ValuePotionListener

#include "PluginValuePotion/PluginValuePotion.h"
class MyClass : public sdkbox::ValuePotionListener
{
private:
    virtual void onCacheInterstitial(const char *placement);

    virtual void onFailToCacheInterstitial(const char *placement, const char *errorMessage);

    virtual void onOpenInterstitial(const char *placement);

    virtual void onFailToOpenInterstitial(const char *placement, const char *errorMessage);

    virtual void onCloseInterstitial(const char *placement);

    virtual void onRequestOpenURL(const char *placement, const char *URL);

    virtual void onRequestPurchase(const char *placement, const char *name, const char *productId, int quantity, const char *campaignId, const char *contentId);

    virtual void onRequestRewards(const char *placement, std::vector<sdkbox::ValuePotionReward> rewards);
};

• 创建一个监听类来接收回调:

sdkbox::PluginValuePotion::setListener(this);

API Reference

Methods

static bool init ( ) ;

initialize the plugin instance.

static void setListener ( ValuePotionListener * listener ) ;

Set listener to listen for adcolony events

static ValuePotionListener * getListener ( ) ;

Get the listener

static void removeListener ( ) ;

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

static void setTest ( bool isTest ) ;

for intergation test

static bool hasCachedInterstitial ( const char * placement ) ;

check if ad is cached

static void cacheInterstitial ( const char * placement ) ;

cached ad

static void openInterstitial ( const char * placement ) ;

show ad

static void trackEvent ( const char * eventName ) ;

track game event

static void trackEvent ( const char * eventName , double eventValue ) ;

static void trackEvent ( const char * category ,
                         const char * eventName ,
                         const char * label ,
                         double eventValue ) ;

static void trackPurchaseEvent ( const char * eventName ,
                                 double revenueAmount ,
                                 const char * currency ,
                                 const char * orderId ,
                                 const char * productId ) ;

track purchase event

static void trackPurchaseEvent ( const char * eventName ,
                                 double revenueAmount ,
                                 const char * currency ,
                                 const char * orderId ,
                                 const char * productId ,
                                 const char * campaignId ,
                                 const char * contentId ) ;

static void trackPurchaseEvent ( const char * category ,
                                 const char * eventName ,
                                 const char * label ,
                                 double revenueAmount ,
                                 const char * currency ,
                                 const char * orderId ,
                                 const char * productId ,
                                 const char * campaignId ,
                                 const char * contentId ) ;

static void userinfo ( const char * attribute , const char * value ) ;

set user info

Listeners

void onCacheInterstitial ( const char * placement ) {

void onFailToCacheInterstitial ( const char * placement ,
                                 const char * errorMessage ) {

void onOpenInterstitial ( const char * placement ) {

void onFailToOpenInterstitial ( const char * placement ,
                                const char * errorMessage ) {

void onCloseInterstitial ( const char * placement ) {

void onRequestOpenURL ( const char * placement , const char * URL ) {

void onRequestPurchase ( const char * placement ,
                         const char * name ,
                         const char * productId ,
                         int quantity ,
                         const char * campaignId ,
                         const char * contentId ) {

void onRequestRewards ( const char * placement ,
                        std::vector <ValuePotionReward> rewards ) {

手动集成

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

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

iOS 平台手动集成

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

sdkbox.framework

PluginValuePotion.framework

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

UIKit.framework

Foundation.framework

CoreGraphics.framework

SystemConfiguration.framework

CoreTelephony.framework

AdSupport.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 目录拷贝下列 jar 文件到您的工程的 proj.android/libs 目录。

valuepotion.jar

PluginValuePotion.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

拷贝 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.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

在接近文件底部的位置，拷贝并且粘贴下列3个 activity 定义到 application tags 标签结尾处。

<application>

......

<meta-data android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />

<!-- Valuepotion Components -->
<!-- for interstital ad interface -->
<activity
        android:name="com.valuepotion.sdk.VPInterstitialActivity"
        android:theme="@android:style/Theme.Translucent" >
</activity>

<!-- for CPI tracking -->
<receiver
        android:name="com.valuepotion.sdk.VPInstallReceiver"
        android:exported="true" >
        <intent-filter>
                <action android:name="com.android.vending.INSTALL_REFERRER" />
        </intent-filter>
</receiver>
<!-- Valuepotion Components End -->

.....

</application>

编辑 Android.mk

编辑 <project_root>/jni/Android.mk :

为 LOCAL_STATIC_LIBRARIES 添加额外的库：

LOCAL_WHOLE_STATIC_LIBRARIES += PluginValuePotion
LOCAL_WHOLE_STATIC_LIBRARIES += sdkbox

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

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

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

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

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

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

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

混淆 (release, 可选)

• 编辑 project.properties,写入一个 Proguard 配置. Example:

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.**

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

注意: 混淆只在 Release 模式下有效 (比如 cocos run -m release), 在 debug 模式下,不会调到混淆规则.