Get Started with Vungle SDK v. 5 - Corona

Contents

Before You Begin

  • We recommend that you use the latest Corona build for your integration. Vungle Android and iOS SDK v. 5.3.0 is available starting with the Corona daily build 2017.3154.
  • The Vungle Corona Plugin for iOS supports iOS 8 and above, limited by the Corona SDK.
  • The Vungle Corona Plugin for Android supports Android 4.0.3 (Ice Cream Sandwich - API version 15) and above, limited by the Corona SDK.
  • The Vungle Corona Plugin for Android supports Amazon OS 5.4 and above, added starting with the daily build 2017.3124.
  • Download our sample app: https://github.com/Vungle/Corona-Plugin/tree/sdk5.

Step 1: Update build.settings

Add the following entry into the plugins table in build.settings. When added, the SDK will connect to the server to integrate the Vungle SDK 5+ plugin during the build phase:

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

For Android Only

For Android, the following permissions are automatically added when using this plugin:

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

After adding Google Play Services, add below permissions into AndroidManifest. Vungle uses these information to tailor the best ad available for the user.

androidPermissions = {
"android.permission.ACCESS_COARSE_LOCATION",
"android.permission.ACCESS_FINE_LOCATION" /
},

Step 2: Add the Code

Initialize the SDK

Note: A default placement is created for each app automatically. You must provide its placement reference ID in this initialization step whether or not you plan to take advantage of the placements functionality. If you create multiple placements, provide all the reference IDs.

We recommend that you initialize the SDK as soon as your app launches to allow the SDK enough time to download ad assets for the auto-cached placement. Initializing the SDK requires:

  • importing Vungle ads
  • app ID
  • the Reference IDs for all the placements you will be using in your app

You can find these IDs on the Vungle Dashboard (refer to Setting Up and Reporting on Placements).

Sample code:

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])

Once the SDK is initialized successfully, it calls the following event:

event.type == "adAvailable"

After the Vungle SDK is initialized, it automatically requests an ad for the placement you selected as Auto-Cached in the Vungle Dashboard. We recommend selecting the most viewed placement for auto-caching. 

Once an ad is cached successfully, the adAvailable event is called with the placement reference ID matching your Auto-Cached placement. For the auto-cached placement, only when ad availability changes from true to false or from false to true is this method called. The SDK will keep requesting an ad for the auto-cached placement. For all other placements, this callback method is called in case of “Load Failed” (adAvailable returns ‘NO’ in this case).

Load an Ad for a Placement

For placements other than the auto-cached placement call the ads.load() method to load an ad. It takes a placement reference ID string as an argument and attempts to load an ad for that particular placement only when ads.load() is issued and ad is not available for that placement:

ads.load( "PLMT_1” )

Note: This method is only used for placements other than the auto-cached one, because auto-cached ads are loaded immediately after playing the pre-cached ad.

Play an Ad for a Placement

After allowing enough time for the download of ad assets to complete, you can play the ad by calling ads.show(). You should check whether there is an ad ready for this placement by calling event.adPlayble before attempting to play an ad.

Sample code:

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

Event Handling

You can pass optional event listeners to ads.init() by setting up the listener before the initialization takes place. Below is the list of event listeners available.

  • adStart
    type: adStart
    placementID: placement reference ID
    isError: true if an ad could not be played; false if an ad started playing

  • adLog
    type: adLog
    message: ad activity message

  • adInitialize
    type: adInitialize 

  • adAvailable
    type: adAvailable
    placementID: placement reference ID
    isAdPlayable: true if an ad is available to played; false otherwise

  • adEnd
    type: adEnd
    placementID: placement reference ID
    didDownload: true if the user clicked the download button; false otherwise
    completedView: true if the user watched 80% or more of the video; false otherwise

  • vungleSDKlog
    type: vungleSDKlog
    message: SDK event message

Sample code:

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

Customization Options

The ads.show() method can accept an options dictionary to customize the ad play experience.

Key

Value

Description

alertTitle

alertText

alertContinue

placement

String

You can customize a message to display to users when they attempt to close the incentivized video before completion. (Rewarded ads are in some cases referred to as incentivized ads; both terms always refer to the same kind of ad. In the SDK code and in our Reporting API, we use the term 'incentivized'.)

Note: This setting only applies to standard Vungle ads. For Dynamic Template ads, the same customization is available on the Dashboard.

isAutoRotation

Bool

For Android, if true (default), the video ad will rotate automatically with the device's orientation. If false, it will use the ad's preferred orientation.

For iOS, refer to the orientation key below.

isSoundEnabled

Bool

If true (default), sound will be enabled during video ad playback, subject to the device's sound settings. If false, video playback will begin muted. Note that the user can mute or unmute sound during playback.

immersive

Bool

For Android only, enables or disables immersive mode on KitKat+ devices.

large

Bool

For iOS only, draws larger buttons that control ad functions such as mute or close.

orientation

Integer

For iOS only, set to 4 for landscape, 0 for portrait, or 5 to rotate automatically.


Sample code:

if (platform == "Android") then
    options = {
        placementId = placements[i],
        isAutoRotation = isAutoRotate,
        immersive = isImmersive,
        isSoundEnabled = not isMuted
    }
else
    options = {
        placementId = placements[i],
        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

ads.show(options)
Have more questions? Submit a request

Comments