This guide runs through a quick integration of our Vungle Marmalade Plugin into a basic sample application. The source code referenced here is available on our public GitHub repository.
- The Vungle Marmalade Plugin requires Marmalade 8.0.0 and higher.
- 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 on your app’s page.
- The Vungle Marmalade Plugin isn't included in the sample code linked above, so you'll want to make sure you've downloaded it first from the Vungle dashboard. Once the download's complete...
Add a link to the Vungle Marmalade Plugin into the MKB file of your project. To do this, open the MKB file of your project in a text editor and add the following line to the end of your file:
In this walkthrough, we're going to initialize all of our Vungle-related code. It's best to initialize the Vungle Marmalade Plugin as soon as possible, however, to ensure that the included Vungle SDKs have completed configuration in time to present an ad to the user when 'playAd' is called.
Initialization is just one line. It only needs to be called once, and is used to prepare the Vungle Marmalade Plugin to present ads to the user. Try to initialize the Vungle SDK as early as possible in your application, as the SDK will need 30-45 seconds to initialize and cache an ad for playback:
//Your App IDs can be found in the Vungle Dashboard on your apps' pages
Playing an ad is another one-liner.
//Short and simple!
The VunglePlayAdWithOptions method can accept an options to customize the ad play experience:
// Plays an ad with more options. Use structure VungleSDKPlayOption to set options.
VungleSDKPlayOption* opts =
The options structure contains the following fields:
|incentivized||You can choose to be notified whenever a user has completed an ad. A typical use case of this is when you are offering some sort of value exchange (‘watch this video and receive 100 gems!’). If you choose to make your ads incentivized, we’ll immediately send a message to your server along with a user id (that you provide) so that you can reward your users. YES means this ad will be incentivized. Refer to our instructions for setting up incentivized ads.|
Sets the orientation of the ad.
|userTag||The key user is the one passed as user in the S2S call (if there are any).|
|placement||Metadata noting the placement detail of an individual ad play. This is used to filter different ad experiences when retrieving report data for your application's performance.|
|alertTitle||String that is used as the title of the alert dialog presented when a user closes an incentivized ad experience prematurely.|
|alertText||String that is used as the body text of the alert dialog presented when a user closes an incentivized ad experience prematurely.|
|alertCloseText||String title for the close button text of the alert dialog presented when a user closes an incentivized ad experience prematurely.|
|alertContinueText||String title for the close button text of the alert dialog presented when a user closes an incentivized ad experience prematurely.|
|key1..8||We have eight keys built in here.|
The Vungle Marmalade Plugin allows an app to subscribe to 5 events surrounding ad presentation:
- VUNGLESDK_CALLBACK_ADPLAYABLECHANGED - Fired when a Vungle ad is ready to be displayed
- VUNGLESDK_CALLBACK_ADSTART - Fired when a Vungle ad starts
- VUNGLESDK_CALLBACK_ADEND - Fired when the user leaves the ad and control is returned to your application / game
- VUNGLESDK_CALLBACK_VIDEOVIEW - Fired each time an ad completes
- VUNGLESDK_CALLBACK_LOG - Fired when the SDK sends a log event
Callback functions has a two parameters of type void*. First parameter links to the additional event information.
|ADPLAYABLECHANGED||bool||If value is true, you can now play an ad|
|ADEND||bool||True if a user tapped Download button to go store|
|LOG||const char*||Log message|
Subscribing to these events is easy. Adding an event listener would look like this:
And that's it! For more information about Vungle Marmalade plugins check out our other plugin articles, or look through the source code for our Marmalade Sample app.