Get Started with Vungle - Windows SDK v.5.1+

Use this guide to quickly integrate our SDK into your app and start monetizing.

The code samples in this guide are in C#, but we provide sample app files in C#, C++, Visual Basic, and DirectX+XAML from our GitHub repository.

Contents

Before You Get Started

  • This guide is for Vungle Windows SDK 5.1 and higher. The integration guide for Vungle Windows SDK version 1.3.16 and below is here: Get Started with Vungle - Windows SDK v. 1.0 - v.1.3.16.
  • The integration requires a Vungle account, so create a Vungle account if you haven’t already.
  • If you haven't already done so, head over to our dashboard and add your app to your account. Please check Setting Up and Reporting on Placements to learn how to set up placements in the Vungle dashboard.
  • You must use Visual Studio 2015 if you are developing for Windows 8.1 and Windows Phone 8.1 because Visual Studio 2017 stopped supporting these versions.
  • The Back button is supported on mobiles, but not on PCs (keyboard). This can result in different behavior and user experience for UWP builds.
  • Please switch your application to Active mode if no ads are being returned in Test mode.

Download the SDK and Add VungleSDK to Your Project

  1. Download the Vungle Windows SDK from the Vungle Dashboard.
  2. Extract the archive.
  3. In Visual Studio, create a new project using the template appropriate for your application and programming language.
  4. Add a reference for your project to the Vungle Windows SDK file you downloaded.
  5. Make sure that your project has the internetClient capability in the package.appxmanifest file, as shown:
    <Capabilities>
    ...
    <Capability Name="internetClient" />
    ...
    </Capabilities>
  6. Import the VungleSDK namespace.
    using VungleSDK;
    

Obtain a VungleAd Instance

The VungleAd instance takes two parameters: a string for your Vungle app ID and an array of strings for placement IDs. You can only use placement IDs that you have already included when you are obtaining the instance. If you do not include one auto-cached placement, the SDK will automatically assign one of your non-auto-cached placements to be auto-cached.

VungleAd sdkInstance;

string appID = “app_id”;
string[] placementArray = new string[]
{
  “placement_id_1”,
  “placement_id_2”,
  “placement_id_3”
};
sdkInstance = AdFactory.GetInstance(appID, placementArray);

In the above example, replace app_id with your Vungle app ID and placement_id_# with the placement IDs to be used in your project. We recommend that you follow these initialization steps as soon as your app finishes loading critical components, so that the auto-caching can start sooner.

Create and Register an Event Handler

Create an event handler for OnAdPlayableChanged event. This event handler is called when the ad availability state changes. You can identify which placement triggered the event by checking e.Placement.

// Event handler for OnAdPlayableChanged event
private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e)
{
  // e.Placement - placement ID in string
  // Run asynchronously on the UI thread
  await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
    new DispatchedHandler(() => methodToRun(e.Placement)));
}

Register this event handler for OnAdPlayableChanged event.

sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;

Load an Ad for a Placement

For placements other than the auto-cached placement, you must call LoadAd first, allow enough time to download ad assets, and then wait for OnAdPlayableChanged to be called:

sdkInstance.LoadAd(“placement_id”);

Note: The auto-cached placement will attempt to download a new ad asset immediately after PlayAdAsync is called, so there is no need to call LoadAd.

Sample code:

private void OnLevelStart(Object sender, RoutedEventArgs e)
{
  sdkInstance.LoadAd(“placement_id”);
}

Play an Ad

Play an ad with the default configuration:

sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”);

Sample code:

private async void OnLevelComplete(Object sender, RoutedEventArgs e)
{
  await sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”);
}

You can optionally customize the ads you play by providing options to AdConfig object. 

Sample code:

private async void PlayCustomizedAd(Object sender, RoutedEventArgs e)
{
  AdConfig adConfig = new AdConfig();

  adConfig.Orientation = DisplayOrientations.Portrait;
  adConfig.SoundEnabled = false;
  
  await sdkInstance.PlayAdAsync(adConfig, placement2);
}

Customization Options

These are the available properties in the AdConfig object instance:

Note: 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'.

Options

Default Value/
Type

Description

Orientation

AutoRotate

DisplayOrientations

Orientation.AutoRotate (default) makes the ad autorotate with the device orientation.

Orientation.Portrait makes the ad play only in the portrait orientation. 

Orientation.Landscape makes the ad play only in the landscape orientation. 

Note: This option only applies to mobile applications.

SoundEnabled

true 

bool

Sets the starting sound state for the ad.

If true (default), the audio respects device volume and sound settings.

If false, video begins muted but user may modify.

BackButtonImmediatelyEnabled

false

bool

If true, allows the user to immediately exit an ad using the back button.

If false (default), the user cannot use the back button to exit the ad until the on-screen close button is shown. 

Note: This option only applies to mobile applications.

UserId

null

string

Passes the unique user ID to your application to verify that this user should be rewarded for watching an incentivized ad when server-to-server callback is used for verification.

Note: This setting is applicable only for rewarded placements.

IncentivizedDialogTitle

“Close this ad?”

string

Sets the title of the confirmation dialog when skipping an incentivized ad.

Note: This setting is applicable only for rewarded placements.

IncentivizedDialogBody

“Are you sure you want to skip this ad? You must finish watching to claim your reward.”

string

Sets the body of the confirmation dialog when skipping an incentivized ad.

Note: This setting is applicable only for rewarded placements.

IncentivizedDialogCloseButton

"Close"

 

string

Sets the 'cancel' button text of the confirmation dialog when skipping an incentivized ad. 

Note: This setting is applicable only for rewarded placements.

IncentivizedDialogContinueButton

"Continue"

string

Sets the 'keep watching' button text of the confirmation dialog when skipping an incentivized ad. 

Note: This setting is not applicable if the ad is not incentivized.

Incentivized

-

DEPRECATED

You can set the rewarded configuration at the placement level from the dashboard. Refer to Setting Up and Reporting on Placements.


Note:
The options for SoundEnabled and incentivized dialogs for Dynamic Template and Flex View ads are available on the dashboard to configure. Programmatic configuration will only apply to legacy ads.

Showing the Close Button

To control whether a user has the option to close out of an ad, use the forced view options in your app's advanced settings on the Vungle Dashboard.

Subscribing to Event Handlers

The Windows SDK raises several events that you can handle programmatically. You can use these event handlers to control features of your app, such as pause/resume of background music.

UI Thread Note

The event listeners are executed on a background thread, so any UI interaction or updates resulting from an event listener must be passed to the main UI thread before executing. Here is one way to do it:

await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() =>
{ // This block will be executed in the UI thread
} );

VungleAd Event Handlers

Event Handlers

Description

OnInitCompleted

Called immediately after initialization of the SDK has completed. You can check whether there is an ad downloaded from a previous session, or load an ad for placements.

OnAdPlayableChanged

Notifies about change of ad availability for the placement. Wait for this event handler to perform an action when an ad becomes available after loading an ad for placement.

OnAdStart

Called before playing an ad. You can perform actions such as pausing background music.

OnAdEnd

Called when the user closes the end card and control is returned to your application. If either IsCompletedView or CallToActionClicked is true, the user watched the ad or clicked the download button in the ad. In this case, if it was a rewarded ad, the user should be rewarded. You can perform actions such as resuming app features.

Diagnostic

Called when the SDK wants to print diagnostic logs.

Sample code:

//Register event handlers
sdkInstance.OnInitCompleted     += SdkInstance_OnInitCompleted;
sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;
sdkInstance.OnAdStart           += SdkInstance_OnAdStart;
sdkInstance.OnAdEnd             += SdkInstance_OnAdEnd;
sdkInstance.Diagnostic          += SdkInstance_Diagnostic;

...

// OnInitCompleted
//   e.Initialized - true if initialization succeeded, false if failed
//   e.ErrorMessage - reason for failure when e.Initialized is false
private async void SdkInstance_OnInitCompleted(object sender, ConfigEventArgs e)
{
  var placementsInfo = "OnInitCompleted: " + e.Initialized;
  // Initilization was success
  if (e.Initialized == true)
  {
    // Print out list of placements
    for (var i = 0; i < e.Placements.Length; i++)
    {
      placementsInfo += "\n\tPlacement" + (i + 1) + ": " + e.Placements[i].ReferenceId;
      if (e.Placements[i].IsAutoCached == true)
        placementsInfo += " (Auto-Cached)";
    }
  }
  // Initilization failed
  else
  {
    placementsInfo += "\n\t" + e.ErrorMessage;
  }
  System.Diagnostics.Debug.WriteLine(placementsInfo);
  await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() =>
    NotifyInitialization(e.Initialized)));
}

// OnAdPlayableAdPlayable
//   e.AdPlayable - true if an ad is available to play, false otherwise
//   e.Placement  - placement ID in string
private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnAdPlayable(" + e.Placement + ") - " + e.AdPlayable);
  await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() =>
    NotifyWatcher(e.AdPlayable, e.Placement)));
}

// OnAdStart
//   e.Id - Vungle app ID in string
//   e.Placement - placement ID in string
private void SdkInstance_OnAdStart(object sender, AdEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnAdStart(" + e.Id + "): " + e.Placement);
}

// OnAdEnd
//   e.Id - Vungle app ID in string
//   e.Placement - placement ID in string
//   e.IsCompletedView- true when 80% or more of the video was watched
//   e.CallToActionClicked - true when the user has clicked download button on end card
//   e.WatchedDuration - DEPRECATED
private void SdkInstance_OnAdEnd(object sender, AdEndEventArgs e)
{
  System.Diagnostics.Debug.WriteLine("OnVideoEnd(" + e.Id + "): "
    + "\n\tPlacement: " + e.Placement
    + "\n\tIsCompletedView: " + e.IsCompletedView
    + "\n\tCallToActionClicked: " + e.CallToActionClicked
    + "\n\tWatchedDuration: " + e.WatchedDuration);
}

// Event handler called when SDK wants to print diagnostic logs
private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e)
{
  System.Diagnostics.Debug.WriteLine("Diagnostic - "
+ e.Level + " "
+ e.Type + " "
+ e.Exception + " "
+ e.Message); } // DEPRECATED - Use SdkInstance_OnAdEnd() instead private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { }

Playing Native Flex Ads

Vungle Windows SDK 5.1.0+ supports our new Native Flex ad feature. VungleAdControl achieves video ads in native formats by passing a custom container to the Vungle SDK through the AdConfig.AdContainer property and managing the content of Container.Content of the host app.

Requirements for Native Flex Ads

  • Windows SDK 5.1.0+
  • Windows 10 UWP

Please consult your account manager or contact tech-support@vungle.com to configure Native Flex Ad placements.

UI Setup for Native Flex Ads - XAML

VungleAdControl must be declared with the Vungle app ID, all of the placement IDs used in the app, and the placement ID for the particular Native Flex view or feed placement. You can also set the UserId that is used for rewarded placements here.

Sample code:

<Grid
<UI:VungleAdControl x:Name="vungleEmbedded"
Height="200"
                     Width="300"
                      AppID="vungle_app_id"
                      Placements="placement_id_1,placement_id_2,native_flex_id"
                      Placement = "native_flex_id"
                      UserId="vungle_test_user">
    <TextBlock x:Name="Vungle Native Flex Ad"/>
  </UI:VungleAdControl>
</Grid>

Load a Native Flex Ad

Loading an ad using Native Flex placement is identical to loading a full-screen ad.

Sample code:

sdkInstance.LoadAd(“native_flex_id”); 

Play a Native Flex Ad

Playing an ad using Native Flex placement is similar to playing a full-screen ads, but any customization must be configured in .xaml or on the Dashboard, including starting the ad with sound disabled.

Sample code:

await vungleEmbedded.PlayAdAsync();

Event Handlers for Native Flex Ads

Consider registering separate event handlers to manage the different behaviors of full-screen and native ads for a smoother user experience.

Sample code:

vungleEmbedded.OnAdStart += (sender, arg) => {
    ...
}
vungleEmbedded.OnAdEnd += (sender, arg) => {
    ...
}
await vungleEmbedded.PlayAdAsync();
Have more questions? Submit a request

Comments