‹ Review Doc Home

Review 集成指南

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

集成

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

$ sdkbox import review

重点注意事项

如果您升级到了 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 安装器会为您自动生成一个配置文件 res/sdkbox_config.json,在您使用前,请修改里面的值为您自己的应用所需的值.

下面给一个 Review 的配置.

"Review":{
    "ios": {
        "Review":{
            "AppID":"587767923",            //appid, ios 上有效
            "DayLimit": 0,                  //在评价弹出框显示前的天数限制
            "LaunchLimit": 3,               //在评价弹出框显示前的启动次数限制
            "UserEventLimit": 0,            //在评价弹出框显示前的用户事件限制, 用户事件是集成应用来增加事件记数的,调用 userDidSignificantEvent 增加用户事件记数
            "DayForReminding": 1,           //用户选择 稍后提示 后再次弹出的天数限制
            "LaunchForReminding": 2,        //用户选择 稍后提示 后再次弹出的启动次数限制
            "tryPromptWhenInit": true       //在初始化后，是否自动弹出评价提示框
        }
    },
    "android": {
        "Review":{
            "DayLimit": 0,
            "LaunchLimit": 3,
            "UserEventLimit": 0,
            "DayForReminding": 1,
            "LaunchForReminding": 2,
            "tryPromptWhenInit": true
        }
    }
}

使用

修改 Lua Code

修改 ./frameworks/runtime-src/Classes/lua_module_register.h 包含必要的头文件,并调用相应的注册函数,同时注意它的参数 lua_State*:

#include "PluginReviewLua.hpp"
#include "PluginReviewLuaHelper.h"

static int lua_module_register(lua_State* L)
{
  register_all_PluginReviewLua(L);
  register_all_PluginReviewLua_helper(L);
}

初始化 Review

在您的 Lua 代码中 init() 插件,初始化可以在任何时候做，但是必须要在您要使用相关的接口前.我们强烈建议在应用启动时就初始化插件.

sdkbox.PluginReview:init()

设置 Review (可选)

如果您不要使用默认的提示字串,您可以设置自己的字串

注意: 如果您在 sdkbox.config 中把 tryPromptWhenInit 项设置为真,那必须在 init() 之前调用以下函数

sdkbox.PluginReview:setCustomPromptTitle("custom title");
sdkbox.PluginReview:setCustomPromptMessage("custom message");
sdkbox.PluginReview:setCustomPromptCancelButtonTitle("custom cancel");
sdkbox.PluginReview:setCustomPromptRateButtonTitle("custom rate");
sdkbox.PluginReview:setCustomPromptRateLaterButtonTitle("custom rate later");

如果您的 sdkbox.config 中把 tryPromptWhenInit 项为 false, 那您可以调用 tryToShowPrompt 尝试提示用户评价您的应用, 如果所有的限制条件都满足,那提示框就会显示

sdkbox.PluginReview:show();

您也可以强制显示评价提示框

sdkbox.PluginReview:show(true);

如果您的 sdkbox.config 中的 UserEventLimit 项大于0的话，那您需要自已增加用户事件记数

sdkbox.PluginReview:userDidSignificantEvent(true);

接收 Review 事件 (可选)

您可以接收 Review 事件，以像对不同的事件做不同的处理，一个简单的用法可能如下:

local plugin = sdkbox.PluginReview
plugin:setListener(function(args)
    local event = args.event
    if "didDisplayAlert" == event then
        print("didDisplayAlert")
    elseif "didDeclineToRate" == event then
        print("didDeclineToRate")
    elseif "didToRate" == event then
        print("didToRate")
    elseif "didToRemindLater" == event then
        print("didToRemindLater")
    end
end)
plugin:init()

本地化字符

如果你想要在弹出框中显示定制的字符, 有以下两种方式:

• 修改 plugin_review_res_project 工程中的资源 (强烈推荐使用这种)

• 也可以在 sdkbox_config.json 中配置字符串, 如下

{
    "ios": {
        "Review":{
            ...
            "promptTitle":"cutom tile",
            "promptMessage":"this is custom message",
            "promptCancel":"取消",
            "promptRate":"rate打分",
            "promptRateLater":"稍后later"
            ...
        }
    }
}

在 sdkbox_config.json 中配置会关掉字符串本地化, 只有你不需要本地化时，可以使用这种方式.

Amazon Market

如果你的 App 是针对 Amazon 市场, 请用如下配置:

"Review":{
    "android": {
        "Review":{

            ...

            "market": "amazon"
        }
    }
}

API Reference

Methods

sdkbox.PluginReview:setGDPR(enabled)

Set GDPR

sdkbox.PluginReview:init(jsonconfig)

initialize the plugin instance.

sdkbox.PluginReview:setListener(listener)

Set listener to listen for adcolony events

sdkbox.PluginReview:show(force)

Tells 'SDKBox review plugin' to try and show the prompt (a rating alert). if you call show with false or null params, the prompt will be showed if there is connection available, the user hasn't declined to rate or hasn't rated current version. if the item tryPromptWhenInit in sdkbox.config is false, you can call this try to show prompt if you call show with true params the prompt will be showed without checks (the prompt is always displayed). The case where you should call this is if your app has an explicit "Rate this app" command somewhere. This is similar to rateApp, but instead of jumping to the review directly, an intermediary prompt is displayed. another case is for debug

sdkbox.PluginReview:rate()

goto rating page directly

sdkbox.PluginReview:userDidSignificantEvent(canPromptForRating)

sdkbox.PluginReview:rateInAppstore(yes)

sdkbox.PluginReview:setCustomPromptTitle(title);

Set customized title for alert view.

sdkbox.PluginReview:setCustomPromptMessage(message);

Set customized message for alert view.

sdkbox.PluginReview:setCustomPromptCancelButtonTitle(cancelTitle);

Set customized cancel button title for alert view.

sdkbox.PluginReview:setCustomPromptRateButtonTitle(rateTitle);

Set customized rate button title for alert view.

sdkbox.PluginReview:setCustomPromptRateLaterButtonTitle(rateLaterTitle);

Set customized rate later button title for alert view.

Listeners

onDisplayAlert()

trigger when alert prompt show

onDeclineToRate()

trigger when user refuse to rate

onRate()

trigger when user want to rate

onRemindLater()

trigger when user want to remind later

手动集成

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

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

iOS 手动集成步骤

把 plugins/ios 里的如下的 framework 拖到您的 Xcode 工程里的 Review 项,添加时,把 Copy items if needed 勾选上:

sdkbox.framework

PluginReview.framework

plugin_review_res_bundle

把 plugin/luabindings 文件夹中所有的头文件和源文件都拷贝到你的工程的 Classes 文件夹中.

把刚刚拷贝的文件拖动到 Xcode 中或使用 File -> Add files to... 来添加.

Android 手动集成步骤.

拷贝文件

从安装包中的 plugin/android/libs 文件夹下拷贝下面的 jar 文件到您的工程中的 proj.android/libs 文件夹.

PluginReview.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 拷贝 pluginreview 和 sdkbox 目录到您的工程的 proj.android/jni/ 目录.如果 sdkbox 目录已存在，覆盖它.

从 plugin/android 拷贝 plugin_review_res_project 到您工程中的 proj.android,同时让您的工程引用到 plugin_review_res_project 这个工程

编辑 AndroidManifest.xml

在 application tag 这个项前面添加如下权限:

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

编辑 Android.mk

在 proj.android/jni/Android.mk 中:

给 LOCAL_STATIC_LIBRARIES 添加如下要求:

LOCAL_STATIC_LIBRARIES += PluginReview
LOCAL_STATIC_LIBRARIES += sdkbox

在所有的 import-module 项前，添加如下调用:

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

在所有的 import-module 后，新增如下项:

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

修改后，应该和下面的修改类似:

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

注意: 如果您使用预编译包, 必须要保证这些修改是在 $(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

把 plugin/luabindings 文件夹中所有的头文件和源文件都拷贝到你的工程的 Classes 文件夹中.

把你刚刚拷贝的 .cpp 文件添加到 Android.mk 文件的的 LOCAL_SRC_FILES 项.比如

LOCAL_SRC_FILES := hellocpp/main.cpp \
                ../../Classes/AppDelegate.cpp \
                ../../Classes/HelloWorldScene.cpp \
                                ../../Classes/NewSourceFile.cpp

修改 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 配制文件. 例如:

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 com.google.protobuf.** { *; }
-dontwarn com.google.protobuf.**

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

注意: 混淆只在 Release 模式下有效 (例如 cocos run -m release) ,在 debug 模式下不会调用混淆配置文件.