Vungle SDK v. 5 - Corona 入门指南

目录

开始之前

  • 广告不能在 Corona 模拟器中工作。您必须构建到设备来测试我们的广告。
  • 我们建议您使用最新版本的 Corona 来构建您的集成。本指南采用每日构建 3103 进行撰写和测试。请联系 tech-support@vungle.com,如果托管的插件不能用于您正在使用的 Corona SDK 版本的话。
  • 受限于 Corona SDK,面向 iOS 的 Vungle Corona Plugin 支持 iOS 8 及更新版本。
  • 受限于 Corona SDK,面向 Android 的 Vungle Corona Plugin 支持 Android 4.0.3(Ice Cream Sandwich - API 版本 15)及更新版本。
  • 下载我们的示例应用程序:https://github.com/Vungle/Corona-Plugin/tree/sdk5

步骤 1:更新 build.settings

Corona 的官方服务器还未提供针对 Vungle SDK v5.1 的 Corona Plugin,但您可以使用来处 Vungle 的自托管的插件。添加以下条目到 build.settings 中的插件表。添加后,SDK 将连接到服务器以便在构建阶段集成 Vungle SDK 5+ 插件:

plugins =
{ ["plugin.vungle"] = { publisherId = "com.vungle",
},
..
}

仅针对 Android

对于 Android,使用此插件时会自动添加以下权限:

androidPermissions = {
    "android.permission.INTERNET",
    "android.permission.WRITE_EXTERNAL_STORAGE",
    "android.permission.ACCESS_NETWORK_STATE"
},

步骤 2:添加代码

初始化 SDK

注:系统自动为每个应用程序创建一个默认广告位置。您必须在初始化步骤中提供其广告位置参考 ID,无论您是否计划利用该广告位置功能。如果您创建多个广告位置,请提供所有的参考 ID。

我们建议您在启动应用程序时尽快初始化 SDK,以便给予 SDK 足够的时间来为自动缓存的广告位置下载广告资源。初始化 SDK 需要:

  • 导入 Vungle 广告
  • 应用程序 ID
  • 您将在您的应用程序中使用的所有广告位置的参考 ID

您可以在 Vungle 仪表板中找到这些 ID(请参阅广告位置的设置和报告)。

示例代码:

local ads = require "plugin.vungle"
platform = system.getInfo( "platformName" )
placements = {}

if (platform == "Android") then
    appData = {
        appID="YOUR_ANDROID_APP_ID",
        placements={“PLMT_DEFAULT","PLMT_1","PLMT_2"}
    }
else
    appData = {
        appID="YOUR_IOS_APP_ID",
        placements={“PLMT_DEFAULT","PLMT_1","PLMT_2"}
}

-- vungleAdListner is optional
ads.init("vungle", appData.appID .."," .. appData.placements[1] .."," .. appData.placements[2] .."," .. appData.placements[3] [, vungleAdListener])

一旦 SDK 成功初始化,它将调用以下事件:

event.type == "adAvailable"

SDK 初始化之后,它将自动为您在 Vungle 仪表板中选为自动缓存的广告位置请求广告。我们建议选择观看次数最多的广告位置用于自动缓存。

一旦广告缓存成功,拥有匹配您的自动缓存广告位置的广告位置参考 ID 的 adAvailable 事件将被调用。对于自动缓存的广告位置,只有当广告可用性从 true 变为 false 或者从 false 变为 true 时,此方法才将被调用。SDK 将会一直为自动缓存的广告位置请求广告。对于其他广告位置,此回调方法将在“加载失败”(在这种情况下,adAvailable 返回‘NO')时被调用。

您还可以通过以下属性来检查广告位置的广告可用性:

- (BOOL)isAdCachedForPlacementID:(nonnull NSString *)placementID;

为广告位置加载广告

对于自动缓存广告位置之外的广告位置,请调用 ads.load() 方法来加载广告。只有当 ads.load() 被发布且广告不可用于那个广告位置时,它才把一个广告位置参考 ID 字符串作为一个变元,并试图为那个特定的广告位置加载广告。

ads.load( "PLMT_1” )

注:此方法只用于除自动缓存广告位置之外的广告位置,因为自动缓存的广告将在播放预缓存的广告后立即被加载。

为广告位置播放广告

给予足够的时间来完成广告资源的下载之后,您可以通过调用 ads.show() 来播放广告。在试图播放广告之前,您应当通过调用 event.adPlayble 来检查这个广告位置是否有准备好的广告。

示例代码:

if (event.placementID == appData.placements[1]) then
    if ( event.adPlayable == true ) then
        ads.show( "PLMT_DEFAULT")
    end
end

事件处理

您可以通过在初始化之前设置侦听器来将可选的事件侦听器传递给 ads.init()。如下是可用的事件侦听器清单。

  • adStart
    type: adStart
    placementID: 广告位置参考 ID
    isError: 为 true,如果一个广告无法播放;为 false,如果一个广告已经开始播放

  • adLog
    type: adLog
    message: 广告活动消息

  • adInitialize
    type: adInitialize 

  • adAvailable
    type: adAvailable
    placementID: 广告位置参考 ID
    isAdPlayable: 为 true,如果一个广告可供播放;否则为 false

  • adEnd
    type: adEnd
    placementID: 广告位置参考 ID
    didDownload: 为 true,如果用户点击了下载按钮;否则为 false
    completedView: 为 true,如果用户观看了视频的 80% 或更多;否则为 false

  • vungleSDKlog
    类型: vungleSDKlog
    消息: SDK 事件消息

示例代码:

local function vungleAdListener( event )
    if ( event.type == "adStart" and not event.isError ) then
        -- adStart event is called and ad will play
    end
    if ( event.type == "adStart" and event.isError ) then
        -- Ad has not finished caching and will not play
    end
    if ( event.type == "adLog") then
        -- adLog event is called to pass ad activity information
    end
    if ( event.type == "adInitialize") then
        -- adInitilizaed is called when placement has successfully initialized
    end
    if ( event.type == "adAvailable" ) then
        -- adAvailable is called when playablility changes to/from true/false
        -- Usage example: setting a flag to true when download completes
        --   Check event.placementID and event.isAdPlayable to set a flag to true
        --   Then check this flag later in your app and play an ad when it is true
    end
    if ( event.type == "adEnd" ) then
        -- adEnd is called when the end card is closed and and control is return to the hosting app

    end
    if ( event.type == "vungleSDKlog" ) then
        -- vungleSDKlog is called when logging event from SDK takes place
    end
end

自定义选项

ads.show() 方法可以接受一个选项词典来自定义广告播放体验。

密匙

说明

alertTitle

alertText

alertContinue

广告位置

字符串

您可以自定义一条信息,当用户试图关闭未播放完的奖励视频时,他们将会看到这条信息。

注:此设置仅适用于标准的 Vungle 广告。对于动态模板广告,同样的自定义可在仪表板上进行设置。

isAutoRotation

布尔

对于 Android,如果为 true(默认),视频广告将根据设备的方向自动旋转。如果为 false,它将使用广告的首选方向。

对于 iOS,请参考下面的方向键。

isSoundEnabled

布尔

如果为 true(默认),则视频广告播放期间将启用声音,具体取决于设备的声音设置。如果为 false,视频播放开始时为静音。请注意,用户可以在播放过程中设置静音或取消静音。

沉浸

布尔

对于 Android,请在 KitKat+ 设备上启用或禁用沉浸模式。

布尔

对于 iOS,绘制更大的按钮来控制广告功能,如静音或关闭。

方向

整数

对于 iOS,设为 4 用于横向,0 用于纵向,或者 5 用于自动旋转。


示例代码:

if (platform == "Android") then
    options = {
        placementId = placements[i],
        incentivized = isIncentivized,
        isAutoRotation = isAutoRotate,
        immersive = isImmersive,
        isSoundEnabled = not isMuted
    }
else
    options = {
        placementId = placements[i],
        incentivized = incentivized.isOn,
        large = large.isOn,
        isSoundEnabled = not muted.isOn
    }
end
if (not isempty(alertTitle.text)) then
            options.alertTitle = alertTitle.text
        end
        if (not isempty(alertText.text)) then
            options.alertText = alertText.text
        end
        if (not isempty(alertClose.text)) then
            options.alertClose = alertClose.text
        end
        if (not isempty(alertContinue.text)) then
            options.alertContinue = alertContinue.text
        end
        if (not isempty(placement.text)) then
            options.placement = placement.text
        end
end

ads.show(options)
还有其它问题?提交请求

评论