实现广告

adListener 函数

每个插件都支持一个侦听器或回调函数，该函数在发生广告事件时执行。这些事件可能是诸如让您知道插件已完成初始化、广告已成功加载或激励视频观看已完成之类的事情。每个插件都会为这些**阶段**使用不同的名称，您可以在此侦听器函数中对其进行测试。

您将只有一个函数来处理所有这些事件。基本的侦听器函数如下所示（使用 AdMob 作为示例）

-- AdMob listener function
local function adListener( event )
    local json = require( "json" )
    print("Ad event: ")
    print( json.prettify( event ) )
 
    if ( event.phase == "init" ) then  -- Successful initialization
        print( event.provider )
    elseif ( event.phase == "loaded" ) then -- Ads were loaded
    elseif ( event.phase == "reward" ) then -- A rewarded video was completed
    end
end

调用 .init()

编写完核心侦听器函数后，您可以调用插件的 `.init()` 方法。这些方法通常需要您传递**侦听器函数的地址**、您的 `AppId` 以及其他其他参数，例如测试模式、GDPR 同意和其他选项。

由于广告提供商可能需要针对不同平台使用不同的 `AppId`，因此您的代码可能应该执行以下操作

local myAppId = "your_Android_AppId"
local myInterstitialAdUnitId = "YOUR_ANDROID_ADMOB_INTERSTITAL_AD_UNIT_ID"
local myBannerAdUnitId = "YOUR_ANDROID_ADMOB_BANNER_AD_UNIT_ID"
local myRewardedAdUnitId = "YOUR_ANDROID_ADMOB_REWARDED_AD_UNIT_ID"

if "ios" == system.getInfo("platform") then
    myAppId = "your_iOS_AppId"
    myInterstitialAdUnitId = "YOUR_IOS_ADMOB_INTERSTITAL_AD_UNIT_ID"
    myBannerAdUnitId = "YOUR_IOS_ADMOB_BANNER_AD_UNIT_ID"
    myRewardedAdUnitId = "YOUR_IOS_ADMOB_REWARDED_AD_UNIT_ID"
end

admob.init( adListener, { appId = myAppId, testMode = true } )

此时，使用正确的 `appId` 初始化插件的请求将完成。插件完成初始化后，将调用您的 `adListener` 函数。在您收到此事件之前，您无法对插件进行任何其他调用。

请注意，该代码还设置了变量来保存我们的广告位 ID（AdMob 的 `adUnitId`）

横幅广告

许多开发者认为在游戏过程中展示横幅广告是有意义的，定期轮换它们以产生更多广告观看次数。根据游戏类型，这可能是对广告的不良浪费使用。在用户不会与其互动时滥用展示横幅广告是这些广告的支出率 (eCPM) 如此之低的原因之一。

如果您的游戏是用户专注于游戏并且查看和与广告互动会导致他们在游戏中失败或表现不佳的游戏，他们**不会**中断游戏来与广告互动。这是展示横幅广告的糟糕时机。

例如，在像纸牌游戏这样的纸牌游戏中，对用户没有时间限制，因此在游戏中展示横幅广告是可以的，但对于像无尽的跑酷游戏或平台游戏这样的游戏，玩家将专注于游戏，并且他们不会与您的横幅广告互动。大多数游戏都属于这种类型的游戏。在菜单屏幕、高分屏幕、下一关屏幕或用户没有时间压力时展示横幅广告是可以的。

假设您使用 Composer 进行场景管理，在您希望横幅广告出现的场景中，只需将此添加到 `scene:show()` 函数中的 `did` 阶段

function scene:show( event )
    if "did" == event.phase then
        local adTimer = nil
        local adShowAttempts = 10
        local function showAd()
            if adTimer then 
                timer.cancel( adTimer )
            end
            adShowAttempts = adShowAttempts - 1
            if adShowAttempts <= 0 then 
                return
            end
            if not admob.isLoaded( "banner" ) then
                adTimer = timer.performWithDelay( 500, showAd )
            else
                admob.show( "banner", { y = "bottom" } )
            end
        end
        adTimer = timer.performWithDelay( 100, showAd )
    end
end    
   
function scene:hide( event )
    if "will" == event.phase then
        admob.hide()
    end
end

场景终止时，横幅广告也会自动隐藏。

如果您使用自己的场景控制，则可以在您的框架中使用类似的代码。

让我们稍微分解一下代码。在典型的用例中，您可能希望在菜单上显示横幅广告。通常，您希望尽快在屏幕上显示菜单。由于插件初始化需要时间并在后台执行，因此很可能在插件完成初始化之前菜单就已经显示在屏幕上。这段代码利用初始化的完成来加载第一组广告，这同样需要时间。

您可能无法在显示菜单后立即显示广告。更实际的做法是测试广告是否准备好显示，然后在广告准备好时调用 [admob.show()][plugin/admob/show.html] API。

由于填充率低或其他原因，您可能无法展示广告。您不希望持续检查广告是否已准备好。以上代码将使用一个简短的计时器（延迟 100 毫秒）来调用一个函数，该函数将尝试显示广告。这给了插件初始化的时间，但它只会在放弃之前检查有限的次数。

插屏广告

插页式广告是全屏广告。您永远不希望在游戏过程中显示这些广告。这些广告适合在游戏过程和下一个关卡/游戏结束画面之间显示。但是，如果您的游戏每次游玩只持续几秒钟，那么您可能不希望每次游戏结束都显示广告。例如，您可能只想每五次显示一次广告。

关于在显示插页式广告之间应该等待多长时间，没有硬性规定。您最好不要惹恼用户以至于他们删除您的应用程序。这是一种平衡行为。

插页式广告的收益明显高于横幅广告。您应该考虑在游戏中尽可能使用这些广告。

当您进入游戏结束场景、下一级场景等时显示广告是有意义的。您可以在场景显示在屏幕上后，在 `scene:show()` 函数中执行此操作。

function scene:show( event )
    if "did" == event.phase then
        local adTimer = nil
        local adShowAttempts = 10
        local function showAd()
            if adTimer then 
                timer.cancel( adTimer )
            end
            adShowAttempts = adShowAttempts - 1
            if adShowAttempts <= 0 then 
                return
            end
            if not admob.isLoaded( "interstitial" ) then
                adTimer = timer.performWithDelay( 500, showAd )
            else
                admob.show( "interstitial" )
            end
        end
        adTimer = timer.performWithDelay( 100, showAd )
    end
end

用户必须采取操作关闭插页式广告才能返回应用程序，因此您无需执行任何操作来隐藏广告。您可以实施类似的测试，以在调用 show 函数之前验证广告是否已加载。

视频广告

视频广告类似于插页式广告，它们是全屏的并且会完全打断用户体验。您应该考虑在显示插页式广告的相同位置显示这些广告。事实上，对于许多广告插件来说，插页式广告可能是视频广告。它们遵循与插页式广告相同的广告展示规则。

激励视频广告

激励视频广告是一种特殊类型的视频广告，用户可以通过观看这些类型的广告来获得一些游戏内奖励。这些广告通常与 UI 中的按钮绑定，而不是像插页式广告那样打断游戏流程的广告。

也许您的按钮显示视频和大量硬币的图标。当用户与视频互动并完整观看后，他们将获得奖励。

**重要提示** 几乎所有支持激励视频广告的广告提供商都会以不同的方式处理这部分。在某些情况下，您可能只会收到一个表示奖励已完成的事件，并且由您的应用决定是否授予奖励。

另一个提供商可能允许您设置多个具有不同值的激励视频广告位置。也就是说，观看视频位置 A 并获得 50 个硬币，观看视频位置 B 并获得 10 个宝石。在这种情况下，您在 `adListener` 中获得的事件可能会告诉您要给予的奖励金额和类型。

其他提供商可能要求您设置一个 Web 服务器，并在其中放置一个 Web 脚本，以便广告提供商可以调用该脚本记录奖励，然后当您收到一个表示激励视频广告已完成的事件时，您可以与您的服务器核对以获取奖励的金额和类型。所有这些都应在广告提供商的网站上 documented。

在 AdMob 的情况下，没有服务器要求，但您将获得一个包含奖励信息的 “reward” 事件。您将在事件表中获得一个名为 `event.data` 的成员，其中包含一个可以转换为 Lua 表以供您使用的 JSON 字符串。考虑对 `adListener` 函数进行以下更改

-- AdMob listener function
local function adListener( event )
    local json = require( "json" )
    print("Ad event: ")
    print( json.prettify( event ) )
 
    if ( event.phase == "init" ) then  -- Successful initialization
        print( event.provider )
        admob.load( "interstitial", { adUnitId = myInterstitialAdUnitId, hasUserConsent = true } )
        admob.load( "banner", { adUnitId = myBannerAdUnitId, hasUserConsent = true } )
        admob.load( "rewardedVideo", { adUnitId = myRewardedAdUnitId, hasUserConsent = true } )
    elseif event.phase == "failed" then
        if event.type == "banner" then
            -- Put your ad loading failover code here
            -- The most common failure reason is lack of ads to show, so simply try to load another ad
            -- You don't want to do this over and over. Eventually you should give up or try after a longer period of time
        elseif event.type == "interstitial" then
            -- Put your ad loading failover code here
        elseif event.type == "rewardedVideo" then
            -- Put your ad loading failover code here
        end
    elseif ( event.phase == "displayed" ) then -- Ads were loaded
        if event.type == "interstitial" then
            admob.load( "interstitial", { adUnitId = myInterstitialAdUnitId, hasUserConsent = true } )
        elseif event.type == "rewardedVideo" then
            admob.load( "rewardedVideo", { adUnitId = myRewardedAdUnitId, hasUserConsent = true } )
        end
    elseif ( event.phase == "reward" ) then -- A rewarded video was completed
        local data = json.decode( event.data )
        local rewardAmount = data.rewardAmount
        local rewardItem = data.rewardItem
        -- code to give these to your user
    end
end

讲解如何将这些奖励给予用户超出了本教程的范围。

要显示激励视频广告，请使用您喜欢的任何按钮方法（即，widget.newButton()，带有 `touch` 或 `tap` 侦听器的 display.newImageRect() 等）在用户界面中创建一个按钮，并在处理按钮交互的函数中调用 `.show()` 函数。

local function handleRewardedVideoButton( event )
    if "began" == event.phase then -- touch type event
        admob.show( "rewardedVideo" )
    end
    return true
end

您还应该考虑在向用户呈现 UI 按钮之前测试广告是否可用。

要了解有关激励广告和实施策略的更多信息，请查看 AppsFlyer 的这篇文章。