Get Started with Vungle SDK v. 6 - Corona

Contents

GDPR Recommended Implementation

As of May 25th, the General Data Protection Regulation (GDPR) will be enforced in the European Union. To comply with GDPR, developers have two options.

  • Option 1 (recommended): Publisher controls the GDPR consent process at the user level, then communicates the user’s choice to Vungle. To do this, developers can collect the user’s consent using their own mechanism, and then use Vungle APIs to update or query the user’s consent status. Refer to the GDPR Recommended Implementation Instructions section for details.

  • Option 2: Allow Vungle to handle the requirements. Vungle will display a consent dialog before playing an ad for a European user, and will remember the user’s consent or rejection for subsequent ads.

Before You Begin

  • We recommend that you use the latest Corona build for your integration. The latest Vungle Corona plugin v. 6.3.0 has Vungle Android SDK v. 6.3.24 and iOS SDK v. 6.3.2.
  • Corona SDK version 2018.3326 and above is integrated with Vungle Plugin version 6.3.0  
  • The Vungle Corona Plugin for iOS supports iOS 8 and above.
  • 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/master

 

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:

android = {
        usesPermissions = {
         "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.

android = {
       usesPermissions = {
        "android.permission.ACCESS_COARSE_LOCATION",
        "android.permission.ACCESS_FINE_LOCATION",
       
       },
   }, 

IMPORTANT: If you are developing with Corona Enterprise, you must include Android Support Library v4 for the integration to be successful. 

Step 2: Add the Code

Initialize the SDK

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
  • Vungle app ID
  • Placement 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). For the Amazon platform, use the Amazon Application ID from your Vungle Dashboard.

Sample code:

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

if (platform == "Android") then
    appData = {
appID="ANDROID_APP_ID",
placement1 = "ANDROID_PLACEMENT_REFERENCE_ID_1",
placement2 = "ANDROID_PLACEMENT_REFERENCE_ID_2",
placement3 = "ANDROID_PLACEMENT_REFERENCE_ID_3"
} else if (platform == "Amazon") then
appData = {
appID="AMAZON_APP_ID",
placement1 = "AMAZON_PLACEMENT_REFERENCE_ID_1",
placement2 = "AMAZON_PLACEMENT_REFERENCE_ID_2",
placement3 = "AMAZON_PLACEMENT_REFERENCE_ID_3"
}
else
appData = {
appID="IOS_APP_ID",
placement1 = "IOS_PLACEMENT_REFERENCE_ID_1",
placement2 = "IOS_PLACEMENT_REFERENCE_ID_2",
placement3 = "IOS_PLACEMENT_REFERENCE_ID_3"
} end -- vungleAdListner is optional ads.init("vungle", appData.appID, vungleAdListener)

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

event.type == "adInitialize"

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. The SDK will keep requesting an ad for the auto-cached placement.

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(appData.placement1)

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.placement1) then
    if (event.adPlayable == true) then
        ads.show( { placementId = appData.placement1 } )
    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 playability 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.

userTag

String

Set your user ID to reward the user for watching rewarded ads.

ordinal

String

Set ordinal data that tracks how many ads have been shown in a session. Custom reports available upon request.

flexCloseSec

Integer

Automatically closes Flex-View ads after specified time in seconds.


Sample code:

if (platform == "Android") then
    options = {
        placementId = placement1,
        isAutoRotation = isAutoRotate,
        immersive = isImmersive,
        isSoundEnabled = not isMuted
    }
else
    options = {
        placementId = placement1,
        large = large.isOn,
        isSoundEnabled = not muted.isOn
    }
end

options.userTag = "USER_ID"
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)

 

GDPR Recommended Implementation Instructions

To use Vungle APIs to update or query the user’s consent status (as recommended in Option 1 of Vungle's GDPR: Recommended Implementation),use the functions as suggested below. 

The first parameter specifies whether the user has opted in to (1) or out of (2) the message being displayed by the publisher. The second parameter (for plugin version 6.3.0 and above) indicates the publisher-controlled consent policy version, which enables the publisher to ask for consent again when the GDPR policy changes by pooling users by the message version.


// To set user's consent status to opted in (plugin version 6.3.0 and above):
vungle.updateConsentStatus(1, "corona consent v1.0")

//To set user's consent status to opted in (plugin version below 6.3.0): 
vungle.updateConsentStatus(1)

// To set the user's consent status to opted out (plugin version 6.3.0 and above): 
vungle.updateConsentStatus(2, "corona consent v1.0") 

// To set the user's consent status to opted out (plugin version below 6.3.0): 
vungle.updateConsentStatus(2) 

// To find out what the user's current consent status is (plugin version 6.3.0 and above): 
local consentStatus consentStatus = vungle.getConsentStatus() 
//To get the current consent message version use the below API (plugin version 6.3.0 and above): //If the version is not not found, nil is returned consentVersion.text = vungle.getConsentMessageVersion()
Have more questions? Submit a request

Comments