‹ SdkboxAds Doc Home

SdkboxAds 集成指南

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

集成

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

$ sdkbox import sdkboxads

JSON 配置

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

这里有一个 SdkboxAds 配置的例子：

    "SdkboxAds": {
        "units": [
                "AdColony",
                "Fyber",
                "Chartboost",
                "Vungle"
            ],
        "placements": [
            {
                "id" : "placement-1",
                "strategy" : "round-robin",
                "units" : [
                    {
                      "unit": "AdColony",
                      "name": "video"
                    },
                    {
                      "unit": "Chartboost",
                      "name": "Default"
                    }
                ]
            },
            {
                "id" : "placement-2",
                "strategy" : "round-robin",
                "units" : [
                    {
                      "unit": "Vungle",
                      "name": "reward"
                    },
                    {
                      "unit": "AdColony",
                      "name": "v4vc"
                    },
                    {
                      "unit": "Chartboost",
                      "name": "Next Level"
                    }
                ]
            }
        ]
    }

使用

初始化 SdkboxAds

修改您的 Lua 代码， 调用 init() 初始化插件。初始化可以放在代码的任何位置，但是，必须在使用插件功能之前完成。

sdkbox.PluginSdkboxAds:init();

使用 SdkboxAds

请求显示一个在默认的 AdUnit 中的默认广告，并以此完成一次简单的集成测试：

sdkbox.PluginSdkboxAds:play()

请求显示默认 AdUnit 中的广告：

sdkbox.PluginSdkboxAds:play( zone_place_location, params );

// params is an object with string keys and values.

提示：每一个 AdUnit 都有自己的参数，可以参考每一个插件的文档。

请求显示一个指定的 AdUnit 中的广告：

sdkbox.PluginSdkboxAds:play( ad_unit_name, zone_place_location, params );

请求显示定义在 sdkbox_config.json 的 Placement 中的广告：

sdkbox.PluginSdkboxAds:placement( placement_name );

更好的控制广告数据缓冲：

sdkbox.PluginSdkboxAds:cacheControl( ad_unit, cacheOpts );

// cacheOpts is an object with keys and values as strings.

缓冲的选项是由 AdUnit 指定的， 请参考每个插件的相关文档。

SdkboxAds 事件

这个插件允许您捕捉事件。

sdkbox.PluginSdkboxAds:setListener(function(args)
    if "onAdAction" == args.name then
        local ad_unit_id = args.ad_unit_id;
        local ad_name = args.ad_name;
        local ad_action_type = args.ad_action_type;
    elseif "onRewardAction" ==  args.name then
        local ad_unit_id = args.ad_unit_id;
        local ad_name = args.ad_name;
        local reward_amount = args.reward_amount;
        local reward_success = args.reward_success;
    end
end)

API Reference

Methods

sdkbox.PluginSdkboxAds:init ( ) ;

initialize the plugin instance.

sdkbox.PluginSdkboxAds:setListener ( listener ) ;

Set listener to listen for SdkboxAds events

sdkbox.PluginSdkboxAds:playAd()

Each unit knows how to play an ad by default. So this method will play a default Ad for the default AdUnit.

sdkbox.PluginSdkboxAds:playAd( ad_name, params );

Play An Ad in the default AdUnit with extra hints. These hints are i.e. position on screen, transparency, etc. Each AdUnit will document what extra hints can be passed to play an Ad. Currently none of the AdUnits need this parameter.

sdkbox.PluginSdkboxAds:playAd( ad_unit, ad_name, params );

Play an Ad in an specific AdUnit with extra hint parameters. If you pass values to an AdUnit that does need need, they will simply be ignored.

sdkbox.PluginSdkboxAds:placement(placement_name);

When you want to invoke a placement, just call this method. If the placement does not exist, the call will just be ignored. A placement will take care of AdUnit’s cache control, so if the current AdUnit has no cached content, or the AdUnit fails to load an ad, the next adUnit will be used.

sdkbox.PluginSdkboxAds:cacheControl( ad_unit, cacheOpts );

Some Ad units expose fine-grained cache control. For example Chartboost offers specific cache control for each location, as well as general Ads cache control. This method interfaces with the AdUnit’s cache mechanism. If no cache control is exposed for a given AdUnit, the call will silently be ignored. Each AdUnit will document what valid values to pass to the cacheOpts parameter. E.g. for Chartboost, these are valid values:

"Default": true, // a configuration location "Level Complete": true, // a configuration location "ADS": true // a general placeholder chartboost specific

Listeners

onAdAction( ad_unit_id, ad_name, action_type);

This method notifies back with the AdUnit identifier, the Ad name it tried to play, and an enum type of the action it is communicating about. The Action type is the following enum:

    enum AdActionType {

        LOADED=0,               // content loaded
        LOAD_FAILED,            // content failed to load

        CLICKED,                // clicked on content

        REWARD_STARTED,     // reward started
        REWARD_ENDED,           // reward achieved
        REWARD_CANCELED,        // reward aborted

        AD_STARTED,             // start showing.
        AD_CANCELED,            // start showing.
        AD_ENDED,               // content shown

        ADACTIONTYPE_UNKNOWN    // mostly on error situations.

    };

Not all AdUnits will expose all types of events. For example, Chartboost notifies CLICKED action, but AdColony does not. Each AdUnit’s documentation will reflect what events will notify.

onRewardAction( ad_unit_id, ad_name, reward_amount, reward_succeed);

手动集成

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

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

iOS 平台手动集成

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

sdkbox.framework

PluginSdkboxAds.framework

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

Security.framework

AdSupport.framework

另外，每一个 AdUnit 需要的 所有的 库文件都需要被添加。

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

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

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 目录。

PluginSdkboxAds.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/libs 目录下拷贝 sdkboxads_lib 目录到您的 proj.android/libs/ 目录下。

拷贝 jni 库

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

编辑 AndroidManifest.xml

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

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

编辑 Android.mk

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

为 LOCAL_WHOLE_STATIC_LIBRARIES 添加额外的库：

LOCAL_WHOLE_STATIC_LIBRARIES += PluginSdkboxAds
LOCAL_WHOLE_STATIC_LIBRARIES += sdkbox

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

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

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

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

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

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

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

重要事项

对于每一个 AdUnit 您必须添加以下文件：

JNI ： 每一个 AdUnit 的 JNI 库文件。

Manifest： 每一个 AdUnit 插件的所有 Manifest 文件的改动。

jar： Jar文件对于被包含的 AdUnit 来说是必须的。基本所有的在插件 lib 目录下的 jar 文件都需要。

为项 LOCAL_WHOLE_STATIC_LIBRARIES 针对每一个 Adunit 添加库, 比如：

LOCAL_WHOLE_STATIC_LIBRARIES += pluginvungle
LOCAL_WHOLE_STATIC_LIBRARIES += pluginadcolony

为每一个 AdUnit 添加 Android.mk 中的 import-module 项，比如：

$(call import-module, ./pluginadcolony)
$(call import-module, ./pluginvungle)

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

使用 Proguard （release模式下可选）

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

proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt

• 编辑这个配置文件加入每一个 AdUnit 在使用混淆时所需要的配置内容。

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