Get Started with Vungle (SDK v.1.0 - v.4.1) - Corona

This guide runs through a quick integration of our Corona plugin. Check out our Corona sample app to see how it all fits together.

Table of Contents

  1. Update Build Settings
  2. Initialize Vungle
  3. Play Ad
  4. Advanced Settings

A few notes before you get started...

  • Ads will not work in the Corona simulator. You will need to build to a device to test our ads.
  • The Vungle Corona plugin only supports:
    • iOS 7+ and supports both 32bit and 64bit apps
    • Android 3.0 (Honeycomb - API version 11) or later
  • The integration requires a Vungle account, so create a Vungle account if you don't have one handy.

  • If you haven't already done so, head over to our dashboard and add your app to your account. You need to do this so that you can get your App ID that you’ll be adding to your app with our SDK. It’s in red on your app’s page.
 

Now let's get started.  We'll need 4 steps to get up and running : 

1. Update build.settings

To use this plugin, add an entry into the plugins table of build.settings. When added, the build server will integrate the plugin during the build phase. You will not need to download anything, Vungle will be automatically included in your project:

settings = {
        plugins = {
                ["CoronaProvider.ads.vungle"] = {
                        publisherId = "com.vungle"
                },
        },
}

iOS

For iOS, add the following to your plist in build.settings:

iphone = { 
plist= {
NSAppTransportSecurity =
{
NSAllowsArbitraryLoads = true },
}
}

Android

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

android = {
        usesPermissions = {
                "android.permission.INTERNET",
         },
},

2. Initialize Vungle

Vungle ads are accessed through Corona's ads library. You'll need to import ads, then initialize Vungle as early as possible, in your project's core file:

main.lua:

-- import in any file using Vungle Ads
local ads = require "ads"

-- you need to change this to your App ID
appID = "Test_iOS";

-- an ad will begin caching on init
ads.init( "vungle", appID );

3. Play an ad!

When you are ready to play a video, simply call ads.show. You'll need to pass in an ad type- "interstitial" or "incentivized":

ads.show( "interstitial" );

or

ads.show( "incentivized" );

This will also return a boolean true or false depending on the availability of a cached ad.

Also note that ads.hide is not operational — unlike other ad providers, Vungle video ads hide themselves when closed by the user.

NOTE: While your app is in Test mode, you will not be able to download any of the apps advertised. Additionally, the Dashboard will not report the number of impressions. This is because test ads are used only to verify that you have integrated the SDK correctly. This functionality becomes available once your app has gone live in active mode.

Advanced Settings

These advanced settings are also covered in the sample app.

1. Play Ad Options

Now that you've gotten an ad to play, you may want to customize the experience by passing these optional params to ads.show:

isAnimated (Bool)

This parameter only applies to iOS. If true (default), the video ad will transition in with a slide effect. If false, it will appear instantaneously.

isAutoRotation (Bool)

If true (default), the video ad will rotate automatically with the device's orientation. If false, it will use the ad's preferred orientation. This is Android only. For iOS, look into the orientations key.

orientations (Bool) (api.type.Integer)

Bitmaks with the possible orientation values. Default is UIInterfaceOrientationMaskAll.

isBackButtonEnabled (Bool)

This parameter only applies to Android. If true, the Android back button will stop playback of the video ad and display the post-roll. Iffalse (default), the back button will be disabled during playback. Note that the back button is always enabled in the post-roll — when pressed, it exits the ad and returns to the application.

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 un-mute sound during playback.

username (String)

This parameter only applies to the "incentivized" ad unit type. When specified, it represents the user identifier that you wish to receive in a server-to-server callback that rewards the user for a completed video ad view.

Example:

local adShown = ads.show( "interstitial", { isAnimated=false, isBackButtonEnabled=true } )

 

2. Event Listener

Optionally, you can also pass an event listener to ads.init.

ads.init( providerName, appId [, adListener] )

It will notify you of these events:

adStart

  • name: adsRequest
  • provider: vungle
  • type: adStart
  • isError: false if an ad started playing; true if an ad could not be played
  • response: reason why ad could not be played if isError is true

adView

  • name: adsRequest
  • provider: vungle
  • type: adView
  • isError: false
  • totalAdSeconds: the total length of the video in seconds
  • secondsWatched: the length of the longest view by the user, in seconds
  • isCompletedView: true if the user watched 80% of the video; false otherwise

adEnd

  • name: adsRequest
  • provider: vungle
  • type: adEnd
  • isError: false
  • wasCallToActionClicked: true if the user clicked on the call-to-action (usually 'Download'); false otherwise

cachedadavailable

  • name: adsRequest
  • provider: vungle
  • type: cachedAdAvailable
  • isError: false 

Example:

local function vungleAdListener( event )
if ( event.type == "adStart" and event.isError ) then
-- Ad has not finished caching and will not play
end
if ( event.type == "adStart" and not event.isError ) then
-- Ad will play
end
if ( event.type == "cachedAdAvailable" ) then
-- Ad has finished caching and is ready to play
end
if ( event.type == "adView" ) then
-- An ad has completed
end
if ( event.type == "adEnd" ) then
-- The ad experience has been closed- this
-- is a good place to resume your app
end
end

 

3. Additional Functions

vungle.isAdAvailable()

Vungle downloads and caches the next video ad for optimal user experience. This function returns true or false depending on the availability of a cached ad.

vungle.getVersionString()

Returns the plugin and underlying SDK version numbers as a string.

vungle.showCacheFiles()

Writes the list of files in the Vungle cache to the log. This feature is only available for iOS.

iOS Only: Application Transport Security

iOS 9 introduced an ATS (Application Transport Security) measure. Apps deployed on iOS 9 must be updated to work around the ATS measure; refer to Preparing Your Apps for iOS 9 for instructions. 

Google Play Services

If targeting Android and using Corona SDK version 2014.2264 or greater, you will also need to add Google Play Services to the plugins table:

settings = {
        plugins = {
                ["plugin.google.play.services"] = {
                        publisherId = "com.coronalabs"
                },
        },
}

 

Have more questions? Submit a request

Comments