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

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.

Contents

  1. Before you get started
  2. Install the Vungle Marmalade Plugin
  3. Add the code!

Before you get started...

  1. The Vungle Marmalade Plugin requires Marmalade 8.0.0 and higher.
  2. The integration requires a Vungle account, so create a Vungle account if you don't have one handy.
  3. 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.
  4. 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...

Install the Vungle Marmalade plugin

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:

subproject <path_to_the_Vungle_Marmalade_Plugin_directory>/VungleSDK 

For example: 

subproject ../publisher-marmalade-plugin/VungleSDK

Add the code!

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.

Initialize

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:

#include "VungleSDK.h"
//...
int main()
{
    //Your App IDs can be found in the Vungle Dashboard on your apps' pages
    VungleInit("Test_Android""Test_iOS""Test_Windows");
}

Playing ads

Playing an ad is another one-liner.

//Short and simple!
VunglePlayAd();

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 = new VungleSDKPlayOption();
VunglePlayAdWithOptions(opts); 

The options structure contains the following fields:

Key  Description 
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
orientation

Sets the orientation of the ad.

  • 0 - Autorotate (Windows, iOS, android)
  • 1 - Landscape (Windows, iOS), match video (android)
  • 2 - Portrait (Windows, iOS)
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.
 

Event handling

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.

CallbackTypeDescription
ADPLAYABLECHANGED bool If value is true, you can now play an ad
ADSTART  
ADEND bool True if a user tapped Download button to go store
VIDEOVIEW VungleSDKAdViewInfo*

struct VungleSDKAdViewInfo
{
bool IsCompletedView; // True if at least 80% of the video was watched
int VideoDuration; // Total duration of a Vungle ad in milliseconds
int WatchedDuration; // Duration a Vungle ad watched in milliseconds
};

LOG const char* Log message

Subscribing to these events is easy. Adding an event listener would look like this:

int32 OnAdPlayableChanged(void* systemData, void* userData) {
    bool adPlayble = (bool)systemData;
    if (adPlayble){
        // An ad is ready to show!
    }else{
        // No ad is available at this moment.
    }
    return 0;
}
  
int main()
{
    VungleSDKRegister(VUNGLESDK_CALLBACK_ADPLAYABLECHANGED, (s3eCallback)OnAdPlayableChanged, (void*)NULL);
}

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.

또 다른 질문이 있으십니까? 문의 등록

댓글