‹ AdColony Doc Home

AdColony 集成指南

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

集成

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

sdkbox import adcolony

重点注意事项

如果您升级到了 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 Installer 将会自动在您的 sdkbox_config.json 中插入一份配置样例。请修改这份配置样例，使其能用于您自己的 app 。

下面给出一个AdColony的配置样例,你需要在AdColony注册帐号,然后对应的信息替换 <app id> 和 <zone id>.

"AdColony":{
    "id":"<app id>",
    "debug":true,
    "ads":{
        "video":{
            "zone": "<zone id>",
            "v4vc": false
        },
        "v4vc":{
            "zone": "<zone id>",
            "v4vc": true,
            "pre_popup" : true,
            "post_popup": true
        },
        "banner": {
            "zone": "<zone id>",
            "type":"banner",
            "alignment":"bottom",
            "width": 320,
            "height": 50
        }
    }
}

banner.width: banner.width 小于 10 为特殊值. 这时会解释为创建AdColony内置的类型, 目前仅用到以下四个值

• 0: kAdColonyAdSizeBanner(standard,320*50)
• 1: kAdColonyAdSizeMediumRectangle(medium,300x250)
• 2: kAdColonyAdSizeLeaderboard(Leaderboard,728x90)
• 3: kAdColonyAdSizeSkyscraper(Skyscraper,160x600)

如上, 如果设置 banner.width 为0, 则会创建一个 standard(320X250) 的 banner, 如果设置 banner.width 为1, 则会创建一个 medium(300x250) 的 banner, 当 banner.width 为特殊值时, banner.height请设置为 0.

banner.alignment: 可用值:

• center
• top
• bottom
• left
• right
• top_left
• top_right
• bottom_left
• bottom_right
• left_top
• left_bottom
• right_top
• right_bottom

用法

初始化 AdColony

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

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

显示广告

在您想要显示广告的地方,输入如下代码:

sdkbox::PluginAdColony::show("video");

或:

sdkbox::PluginAdColony::show("v4vc");

接收 AdColony 事件 (可选)

您可以接收 AdColony 的事件, 这样您可以在玩家观看完广告后给他相应的奖励.

• 让您的类继承 sdkbox::AdColonyListener

#include "PluginAdColony/PluginAdColony.h"
class MyClass : public sdkbox::AdColonyListener
{
private:

    /*
     * Interstitial Callback
     */
    void adColonyInterstitialDidLoad(const std::string& interstitial);
    void adColonyInterstitialDidFailToLoad(const std::string& error);
    void adColonyInterstitialWillOpen(const std::string& interstitial);
    void adColonyInterstitialDidClose(const std::string& interstitial);
    void adColonyInterstitialExpired(const std::string& interstitial);
    void adColonyInterstitialWillLeaveApplication(const std::string& interstitial);
    void adColonyInterstitialDidReceiveClick(const std::string& interstitial);
    void adColonyInterstitialIapOpportunity(const std::string& interstitial, const std::string& iapProductID, int engagement);

    /*
     * Banner Callback
     */
    void adColonyAdViewDidLoad(const std::string& adView);
    void adColonyAdViewDidFailToLoad(const std::string& error);
    void adColonyAdViewWillLeaveApplication(const std::string& adView);
    void adColonyAdViewWillOpen(const std::string& adView);
    void adColonyAdViewDidClose(const std::string& adView);
    void adColonyAdViewDidReceiveClick(const std::string& adView);

    /*
     * Rewards Callback
     */
    void adColonyReward(const std::string name, const std::string& currencyName, int amount, bool success);

};

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

sdkbox::PluginAdColony::setListener(this);

API Reference

Methods

static void init ( ) ;

initialize the plugin instance.

static void show ( const std::string & name ) ;

play video ad using provided name that was specified in sdkbox_config.json

static void setListener ( AdColonyListener * listener ) ;

Set listener to listen for adcolony events

static AdColonyListener * getListener ( ) ;

Get the listener

static void removeListener ( ) ;

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

static int zoneStatusForZone ( const std::string & zoneID ) ;

Returns the zone status for the specified zone.

static AdColonyAdStatus getStatus ( const std::string & name ) ;

Check the availability of the adcolony ads by name

static void setCustomID ( const std::string & customID ) ;

Assigns your own custom identifier to the current app user.

static std::string getCustomID ( ) ;

Returns the device's current custom identifier.

static std::string getUniqueDeviceID ( ) ;

Returns an AdColony-defined device identifier.

static std::string getAdvertisingIdentifier ( ) ;

Returns the device's advertising identifier.

static std::string getVendorIdentifier ( ) ;

Returns the device's vendor identifier.

static int getVideosPerReward ( const std::string & currencyName ) ;

Returns the number of ads that the user must play to earn the designated reward.

static int getVideoCreditBalance ( const std::string & currencyName ) ;

Returns the number of ads that the user has seen towards their next reward.

static void cancelAd ( ) ;

Cancels any full-screen ad that is currently playing and returns control to the app.

static bool videoAdCurrentlyRunning ( ) ;

Whether a full-screen AdColony ad is currently being played.

static void turnAllAdsOff ( ) ;

This method permanently turns off all AdColony ads for this app on the current device.

static void setUserMetadata ( const std::string & metadataType ,
                              const std::string & value ) ;

Provide AdColony with per-user non personally-identifiable information for ad targeting purposes.

static void userInterestedIn ( const std::string & topic ) ;

Provide AdColony with real-time feedback about what a user is interested in.

static void notifyIAPComplete ( const std::string & transactionID ,
                                const std::string & productID ,
                                int quantity ,
                                float price ,
                                const std::string & currencyCode ) ;

Call this method to report IAPs within your application. Note that this API can be leveraged to report standard IAPs as well as those triggered by AdColony’s IAP Promo (IAPP) advertisements and will improve overall ad targeting.

Listeners

void adColonyInterstitialDidLoad(const std::string& interstitial) = 0;

called when AdColony interstitial is loaded

void adColonyInterstitialDidFailToLoad(const std::string& error) = 0;

called when AdColony interstitial fails to load

void adColonyInterstitialWillOpen(const std::string& interstitial) {};

called when AdColony interstitial will open

void adColonyInterstitialDidClose(const std::string& interstitial) {};

called when AdColony interstitial did close

void adColonyInterstitialExpired(const std::string& interstitial) {};

called when AdColony interstitial expired

void adColonyInterstitialWillLeaveApplication(const std::string& interstitial) {};

called when AdColony interstitial will leave application

void adColonyInterstitialDidReceiveClick(const std::string& interstitial) {};

called when AdColony interstitial did receive click

void adColonyInterstitialIapOpportunity(const std::string& interstitial, const std::string& iapProductID, int 
engagement) {};

void adColonyAdViewDidLoad(const std::string& adView) = 0;

called when AdColony banner is loaded

void adColonyAdViewDidFailToLoad(const std::string& error) = 0;

called when AdColony banner fails to load

void adColonyAdViewWillLeaveApplication(const std::string& adView) {};

called when AdColony banner will leave application

void adColonyAdViewWillOpen(const std::string& adView) {};

called when AdColony banner will open

void adColonyAdViewDidClose(const std::string& adView) {};

called when AdColony banner did close

void adColonyAdViewDidReceiveClick(const std::string& adView) {};

called when AdColony banner did receive click

void adColonyReward(const std::string& name, const std::string& currencyName, int amount, bool success) {};

called when AdColony banner reward

手动集成

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

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

iOS 平台手动集成

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

sdkbox.framework

PluginAdColony.framework

AdColony.framework

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

libz.1.2.5.dylib

AdSupport.framework (Set to Optional)

AudioToolbox.framework

AVFoundation.framework

CoreGraphics.framework

CoreMedia.framework

CoreTelephony.framework

EventKit.framework

EventKitUI.framework

MediaPlayer.framework

MessageUI.framework

QuartzCore.framework

Security.framework

GameController.framework

Social.framework (Set to Optional)

StoreKit.framework (Set to Optional)

SystemConfiguration.framework

WebKit.framework (Set to Optional)

在以下位置添加两个单独的链接选项： Target -> Build Settings -> Linking -> Other Linker Flags:

-ObjC

-fobjc-arc (this allows AdColony to use ARC even if your project does not)

Android 平台手动集成

拷贝文件

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

adcolony.jar

PluginAdColony.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 目录拷贝 PluginAdColony 以及 sdkbox 目录到您的工程的 proj.android/jni 目录。如果 sdkbox 目录在工程中已经存在，请覆盖它。

编辑 AndroidManifest.xml

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

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

使 hardware acceleration 属性生效。这一标签是一个在新版本 sdk 上的选项，不能用于2.3.3版本。

<android:hardwareAccelerated="true" />

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

<activity android:name="com.jirbo.adcolony.AdColonyOverlay"
      android:configChanges="keyboardHidden|orientation"
      android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen" />
<activity android:name="com.jirbo.adcolony.AdColonyFullscreen"
      android:configChanges="keyboardHidden|orientation"
      android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" />
<activity android:name="com.jirbo.adcolony.AdColonyBrowser"
      android:configChanges="keyboardHidden|orientation"
      android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" />

Note: 如果您的 app targets 版本低于 API 13，您可能需要从上面的 activity tags 的 configChanges 属性里删除 screenSize 。

编辑 Android.mk

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

为 LOCAL_STATIC_LIBRARIES 添加额外的库：

LOCAL_STATIC_LIBRARIES += PluginAdColony
LOCAL_STATIC_LIBRARIES += sdkbox

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

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

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

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

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

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

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

• 编辑这个文件，加入如下内容:

-dontwarn android.webkit.**

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