‹ SdkboxAds Doc Home

SdkboxAds 集成指南

For the C++ 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

在您的代码的合适的位置初始化这个插件，我们建议您在 AppDelegate:applicationDidFinishLaunching() 或者 AppController:didFinishLaunchingWithOptions() 中进行初始化。并确保您的代码中包含了正确的头文件。举例如下：

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

使用 SdkboxAds

配置

SdkboxAds 是一个提供调控广告显示服务的插件。这意味着它将在运行时管理一堆在预先定义好的 AdUnit 。 它的配置分为两个部分：配置 AdUnits 以及 配置 Placement 。每一个 AdUnit 都是对一个Sdkbox 广告插件的映射。 举例如下：

    "SdkboxAds": {
        "units": [
            "AdColony",
            "Fyber",
            "Chartboost",
            "Vungle"
        ]
    }

Placement 则设定了对于某一个给定的 AdUnit 将会被显示的广告类型。一个完整的 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"
                    }
                ]
            }
        ]
    }

使用

调用 sdkbox::PluginSdkboxAds::init() 将完成 SdkboxAds 实例化并且开始管理所有的定义在配置文件里的 AdUnit 。

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

sdkbox::PluginSdkboxAds::playAd()

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

sdkbox::PluginSdkboxAds::playAd( const std::string& zone_place_location );
sdkbox::PluginSdkboxAds::playAd( const std::string& zone_place_location, const AdUnitParams& params );

// AdUnitParams is a typedef for std::map<std::string,std::string>

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

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

sdkbox::PluginSdkboxAds::playAd(
        const std::string& ad_unit_name,
        const std::string& zone_place_location );

sdkbox::PluginSdkboxAds::playAd(
        const std::string& ad_unit_name,
        const std::string& zone_place_location,
        const AdUnitParams& params );

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

sdkbox::PluginSdkboxAds::placement( const str::string& placement );

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

sdkbox::PluginSdkboxAds::cacheControl(
        const std::string& ad_unit,
        const std::map<std::string, std::string>& cacheOpts );

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

SdkboxAds 事件

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

• 允许您自己的类继承 sdkbox::SdkboxAdsListener 并且覆盖（override）下列函数的实现：

#include "PluginSdkboxAds/PluginSdkboxAds.h"
class MyClass : public sdkbox::SdkboxAdsListener
{
private:
    void onAdAction(
            const std::string& ad_unit_id,
            const std::string& zone_location_place_you_name_it,
            sdkbox::AdActionType action_type);

    void onRewardAction(
            const std::string& ad_unit_id,
            const std::string& zone_id,
            float reward_amount,
            bool reward_succeed);

};

sdkbox::AdActionType 是一个枚举类型， 定义如下：

    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.

    };

• 创建一个 listener 处理回调：

sdkbox::PluginSdkboxAds::setListener( new MyClass() );

API Reference

Methods

static void init ( ) ;

initialize the plugin instance.

static void setListener ( SdkboxAdsListener * listener ) ;

Set listener to listen for SdkboxAds events

static void playAd()

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

static void playAd(const std::string& );

Play an identified by name on the Default AdUnit

static void playAd(const std::string&, const AdUnitParams& params );

Eventually, an AdUnit may need some extra hints to play an ad, like 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.

static void playAd(
        const std::string& ad_unit, 
        const std::string& zone_place_location );

Play an ad name, for a given AdUnit. AdUnits are idenfitied by name. So a valid example call would be: sdkbox::SdkboxAds::playAd(“AdColony”, “video”);.

static void playAd(
        const std::string& ad_unit, 
        const std::string& zone_place_location, 
        const AdUnitParams& params );

Again, should an AdUnit need extra parameters, use this method. If you pass values to an AdUnit that does need need, they will simply be ignored.

static void placement(const std::string& placement);

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.

static void cacheControl( 
        const std::string& ad_unit, 
        const std::map<std::string, std::string>& 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

void onAdAction( 
        const std::string& ad_unit_id, 
        const std::string& zone_location_place_you_name_it, 
        sdkbox::AdActionType 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.

void onRewardAction( 
        const std::string& ad_unit_id, 
        const std::string& zone_id, 
        float reward_amount, 
        bool reward_succeed);

手动集成

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

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

iOS 平台手动集成

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

sdkbox.framework

PluginSdkboxAds.framework

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

Security.framework

AdSupport.framework

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

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)

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