Appnext 集成指南

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

集成

首先，您必须到 Appnext 注册并配置好您的应用。

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

$ sdkbox import appnext

重点注意事项

如果您升级到了 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 对工程的配置修改. 所以可以有以下做法(任选其一):

保存导出工程中的修改, 对于 SDKBox 来说可能有这些文件(mk, gradle, gradle.properties, AppDelegate.cpp, ...), 导出后再恢复对应该文件
在每一次 Creator 导出工程后, 重新 import 插件.

推荐第一种, 但是第一种的麻烦点在于, 对于第一次(或很久没接触的人)可能会有露掉某个文件第二种, 很方便, 它的麻烦点在于, 如果你对工程有自己的修改, SDKBox 的重新 import 不能帮你恢复.

JSON 配置

SDKBOX 安装器会自动在您的工程中添加一个样例配置文件sdkbox_config.json.在您编译工程前,请修改里面的参数,用您自己的应用信息

id: 广告 id
cache: 时候缓存广告
- true : 缓存该广告，一种类型广告只能缓存一个广告，配置多个缓存，结果未定义
- false [默认]: 不缓存广告
type: 广告类型
- "interstitial"
- "fullscreen"
- "reward"

可选配置

creative_type:
- "managed"
- "video"
- "static"
progress_type:
- "clock"
- "bar"
- "none"
video_lenght:
- "short"
- "long"
button_text
button_color
categories
postback
can_close
skip_text
mute
autoplay
progress_color
show_close_button

更多信息请参考以下链接:

例子:


{
    "ios": {
        "Appnext":{
            "debug":true,
            "ads": {
                "default": {
                    "cache":true,
                    "id":"6d596bc5-b4c1-48ca-be95-3758fd29a3a5",
                    "type":"interstitial"
                }
            }
        }
    },
    "android": {
        "Appnext":{
            "debug":true,
            "ads": {
                "default": {
                    "cache":true,
                    "id":"2f6850dd-190a-499d-aa50-1f4a3dd1ed5f",
                    "type":"interstitial",

                    "button_text":"Button Text",
                    "button_color":"#6AB344",
                    "categories":"Action,Puzzle",
                    "postback":"postback",
                    "can_close":false,

                    "skip_text":"Skip Text",
                    "mute":false,
                    "autoplay":true,
                    "creative_type":"managed"
                },
                "fullscreen": {
                    "cache":true,
                    "id": "17322152-1ef3-4e72-9677-eaf7c09f1054",
                    "type": "fullscreen",

                    "button_text":"Button Text",
                    "button_color":"#6AB344",
                    "categories":"Action,Puzzle",
                    "postback":"postback",
                    "can_close":false,

                    "progress_type":"clock",
                    "progress_color":"#ffffff",
                    "show_close_button":true,
                    "video_lenght":"short"
                },
                "reward": {
                    "cache":true,
                    "id": "8d653a16-129b-4c14-bd22-fae625f70cf4",
                    "type": "reward",

                    "button_text":"Button Text",
                    "button_color":"#6AB344",
                    "categories":"Action,Puzzle",
                    "postback":"postback",
                    "can_close":false,

                    "progress_type":"bar",
                    "progress_color":"#ffff00",
                    "show_close_button":false,
                    "video_lenght":"long"
                }
            }
        }
    }
}

使用

注册 Javascript 函数

修改 ./frameworks/runtime-src/Classes/AppDelegate.cpp 包含如下头文件:

#include "PluginAppnextJS.hpp"
#include "PluginAppnextJSHelper.h"

修改 ./frameworks/runtime-src/Classes/AppDelegate.cpp 确保有如下调用:

sc->addRegisterCallback(register_all_PluginAppnextJS);
sc->addRegisterCallback(register_all_PluginAppnextJS_helper);

初始化 Appnext

在您的代码中合适的地方调用 init(), 我们建议在 app.js 初始化,比如:

sdkbox.PluginAppnext.init();

缓存插屏或者视频广告

sdkbox.PluginAppnext.cacheAd("default");
sdkbox.PluginAppnext.cacheVideo("fullscreen");

注意 : Appnext 的广告需要先缓存，再使用。

刷新插屏或者视频广告

sdkbox.PluginAppnext.refreshAds();
sdkbox.PluginAppnext.refreshVideo("fullscreen");

NOTE : 您需要在一个广告关闭时刷新它，否则下次不会显示广告。

显示插屏或者视频广告

sdkbox.PluginAppnext.showAd("default");
sdkbox.PluginAppnext.showVideo("fullscreen");

隐藏插屏广告

sdkbox.PluginAppnext.hideAd();

检查插屏或者视屏广告是否可以播放

sdkbox.PluginAppnext.isAdReady();
sdkbox.PluginAppnext.isVideoReady("fullscreen");

接受 AppnextListner 事件（可选）


sdkbox.PluginAppnext.setListener({
    onAdError : function(msg) { },
    onAdLoaded : function() { },
    onAdOpened : function() { }, // android 上没有回调
    onAdClosed : function() { },
    onAdClicked : function() { },

    onVideoLoaded : function(name) { },     // ios 上没有回调
    onVideoClicked : function(name) { },    // ios 上没有回调
    onVideoClosed : function(name) { },     // ios 上没有回调
    onVideoEnded : function(name) { },      // ios 上没有回调
    onVideoError : function(name, msg) { }  // ios 上没有回调
});

API Reference

Methods

sdkbox.PluginAppnext.init();

initialize the plugin instance.

sdkbox.PluginAppnext.setListener(listener);

Set listener to listen for appnext events

sdkbox.PluginAppnext.hideAd();

Hide advertisement

sdkbox.PluginAppnext.showAd();

Show advertisement

sdkbox.PluginAppnext.refreshAds();

Refresh advertisement

sdkbox.PluginAppnext.cacheAd(name);

Cache advertisement

sdkbox.PluginAppnext.isAdReady();

Check if advertisement is ready

sdkbox.PluginAppnext.cacheVideo(name);

Cache video with @name

sdkbox.PluginAppnext.showVideo(name);

show video with @name

sdkbox.PluginAppnext.refreshVideo(name);

Refresh video with @name

sdkbox.PluginAppnext.isVideoReady(name);

Check if video is ready with @name

sdkbox.PluginAppnext.setRewardsTransactionId(transactionId);

Set reward video transaction id

sdkbox.PluginAppnext.setRewardsUserId(userId);

Set reward video user id

sdkbox.PluginAppnext.setRewardsRewardTypeCurrency(currency);

Set type of reward, such as life / credit / points.

sdkbox.PluginAppnext.setRewardsAmountRewarded(amount);

Set the amount of currency that was rewarded.

sdkbox.PluginAppnext.setRewardsCustomParameter(parameter);

Set reward video custom parameter.

Listeners

onAdError(msg);

onAdLoaded();

onAdOpened();

onAdClosed();

onAdClicked();

onVideoLoaded(name);

onVideoClicked(name);

onVideoClosed(name);

onVideoEnded(name);

onVideoError(name, msg);

手动集成

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

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

Manual Integration For iOS

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

sdkbox.framework

PluginAppnext.framework

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

AdSupport.framework

SystemConfiguration.framework

把 plugin/jsbindings 文件夹中所有的头文件和源文件都拷贝到你的工程的 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 .

Android 平台手动集成

拷贝文件

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

如果你使用 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" />

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

<service android:name="com.appnext.core.DownloadService" />
<activity android:name="com.appnext.ads.interstitial.InterstitialActivity"
  android:hardwareAccelerated="true" android:configChanges="keyboardHidden|orientation|screenSize"
  android:theme="@android:style/Theme.NoTitleBar.Fullscreen" />
<activity android:name="com.appnext.ads.fullscreen.FullscreenActivity"
  android:hardwareAccelerated="true" android:configChanges="keyboardHidden|orientation|screenSize"
  android:theme="@android:style/Theme.NoTitleBar.Fullscreen" />

编辑 `Android.mk`

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

为 LOCAL_STATIC_LIBRARIES 添加额外的库：

LOCAL_WHOLE_STATIC_LIBRARIES += PluginAppnext
LOCAL_WHOLE_STATIC_LIBRARIES += sdkbox

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

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

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

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

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

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

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