Integrate Vungle SDK for Windows

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 in our GitHub repository.

Before You Begin

Requirements

  • The integration requires a Vungle account, so create a Vungle account if you haven’t already done so, and create a new Windows app in your account. Refer to the Add Your Apps and Placements section of our Using the Publisher Dashboard article to learn how to set up placements in the Vungle dashboard.
  • If you are developing for Windows 8.1, you must use Visual Studio 2015, because Microsoft no longer supports Windows 8.1 for Visual Studio 2017.
  • The Back button is supported on mobile devices, but not on PCs (keyboard). This can result in different behavior and user experience for UWP builds.
  • Toggle your application to Active mode if no ads are being returned in Test mode.

Download the SDK

Download the Vungle SDK for Windows here: https://publisher.vungle.com/sdk/sdks/windows.

Reference: Sample App

Refer to the sample app we have provided as you integrate: https://github.com/Vungle/Windows-SDK/tree/master.

Step 1. Integrate the Vungle SDK Into Your Project

There are two ways to add Vungle to your Visual Studio project: using NuGet or manual integration.

Option 1. NuGet Integration

  1. In Visual Studio, right-click on your Project's name in the Solution Explorer and select Manage NuGet Packages.
  2. Click Browse, enter ‘Vungle’, and select Vungle SDK.
  3. Click Install.

Option 2. Manual Integration

  1. Download the Vungle Windows SDK from the Vungle Dashboard.
  2. Extract the archive.
  3. In Visual Studio, create a new project using the correct template for your application and programming language.
  4. Add a reference for your project to the Vungle Windows SDK file you downloaded.
    Vungle SDK has two VungleSDK.windmd files: one for Windows 10, and another for Windows 8.1 development. Use the correct SDK from the extracted directory, Win10 or Win81.
  5. Make sure that your project has the internetClient capability in the package.appxmanifest file. You can do this in Visual Studio or via manual edit.
    • To ensure internetClient capability in Visual Studio:
      1. In Visual Studio, double-click appxmanifest in Solution Explorer.
      2. Select Capabilities.
      3. Confirm that the Internet (Client) option is checked.
    • To ensure internetClient capability via manual edit, open the package.appxmanifeset file and add internetClient to the Capabilities section:
      <Capabilities>
      ...
      <Capability Name="internetClient" />
      ...
      </Capabilities>

Step 2. Import the VungleSDK Namespace

Import the VungleSDK namespace as follows:

using VungleSDK;

Step 3. Obtain a VungleAd Instance

Starting with Vungle SDK v6.3.0, the VungleAd instance takes only one parameter: your Vungle app ID.

VungleAd sdkInstance;
string appID = “app_id”;
sdkInstance = AdFactory.GetInstance(appID);

In the above example, replace appId with your Vungle app ID. We recommend that you follow these initialization steps as soon as your app finishes loading critical components, so that cache optimization can start.

For Vungle SDK v6.2.0 and lower, 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 obtained the instance.

sdkInstance = AdFactory.GetInstance(appID, placementList);

Optionally Specify Configuration Settings

Create a VungleSDKConfig object and add it as a parameter in your SDK initialization to specify optional configuration settings.

VungleSDKConfig sdkConfig = new VungleSDKConfig();
sdkInstance = AdFactory.GetInstance(appID, sdkConfig);

VungleSDKConfig contains parameters that allow you to limit Windows ASHWID tracking and set the minimum disk space required to initialize or load ads.

sdkConfig.DisableAshwidTracking = true;
sdkConfig.MinimumDiskSpaceForAd = 50 * 1024 * 1024;
sdkConfig.MinimumDiskSpaceForInit = 50 * 1024 * 1024;

Step 4. Add Code

Create and Register an Event Handler

Create an event handler for the 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)
{
if (e.AdPlayable == true)
{ // 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 the OnAdPlayableChanged event.

sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;

Load an Ad for a Placement

To load an ad, call LoadAd and allow enough time to download the ad assets. Then wait for OnAdPlayableChanged to be called:

sdkInstance.LoadAd(“placement_id”);

Note: Placement IDs are case-sensitive.

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);
}

Optional and Advanced Settings

Integrate MREC Ads

Vungle Windows SDK 5.1.0+ supports non-fullscreen ads in 300 x 250 Medium Rectangle size. VungleAdControl achieves video ads in MREC 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.

MREC Ad Requirements

  • Windows SDK 5.1.0+
  • Windows 10 UWP
  • MREC placement configured on Vungle dashboard
  • VungleAdControl with width 300 and height 250

VungleAdControl

Vungle MREC creatives are optimized to play in viewing container with size of 300 x 250. Please make sure VungleAdContrl has viewing size that is no smaller than width of 300 and height of 250.

.xaml

<UI:VungleAdControl x:Name="embeddedControl" 
                    Width="300"
                    Height="250" />

Load an MREC Ad

Loading a MREC ad using a MREC placement is identical as loading a full-screen ad.

.cs

sdkInstance.LoadAd("MREC_PLACEMENT_REFERENCE_ID")

Play an MREC Ad

Playing an ad using VungleAdControl requires you to pass AppID, Placements, and Placement. You can also configure MREC ads to start playing as muted by setting SoundEnabled to false.

Parameter Description
AppID Application ID must identical
Placement Placement reference ID for your MREC
Placements Please provide the same placement reference ID you provided Placement (to be removed)
SoundEnabled Set to false to start playing muted (optional, default is true)

.cs

embeddedControl.AppID = "VUNGLE_APP_ID";
embeddedControl.Placements = "MREC_PLACEMENT_REFERENCE_ID";
embeddedControl.Placement = "MREC_PLACEMENT_REFERENCE_ID";

embeddedControl.SoundEnabled = false; // Optional (default = true)

await embeddedControl.PlayAdAsync();

Stop Displaying an MREC Ad

You can use StopBannerAd to stop displaying an MREC ad at anytime.

.cs

embeddedAdControl.StopBannerAd();

Event Handlers for MREC Ads

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

Sample code:

vungleEmbedded.OnAdStart += (sender, arg) => { ... }
vungleEmbedded.OnAdEnd += (sender, arg) => { ... }
vungleEmbedded.OnAdPlayableChanged += (sender, arg) => { ... }
await vungleEmbedded.PlayAdAsync();

Simple MREC Integration Using XAML

VungleAdControl provides a simpler way to integrate MREC ads if you don't need event listeners, or to control the timing of ad load. Once the SDK is initialized, it will load an MREC ad automatically, and you can issue PlayAdAsync once the ad assets complete downloading.

.xaml

<UI:VungleAdControl x:Name="embeddedControl" 
                    Width="300"
                    Height="250"
                    Placement="MREC-5209003"
                    Placements="MREC-5209003"
                    SoundEnabled="False" />

.cs

await embeddedControl.PlayAdAsync();

Integrate Banner Ads

Vungle Banner is currently in BETA phase and you may get limited fill for banner ad requests. Please contact your account manger directly for access to ensure a successful launch.

The Vungle SDK v6.5.2 for Windows supports banner ads. Use VungleAdControl to load and play a banner ad in a container. For a simpler and easier integration, you can hand control over to VungleAdControl, and integrate using XAML only. For an integration that gives you more detailed control, you can specify the ad container in XAML and programmatically control the banner ad.

Banner Ad Requirements

  • Vungle SDK v6.5.2 for Windows
  • Windows 10 UWP

Supported Banner Sizes

The container size to render banner ads can be 320 x 50, 300 x 50 or 728 x 90 (for tablets). You can set banner ads anywhere on the screen, and the user can continue using the app while the ad plays.

Banner Size Dimensions
VungleBannerSizes.Banner_320x50 320x50
VungleBannerSizes.BannerShort_300x50 300x50
VungleBannerSizes.BannerLeaderboard_728x90 728x90

Simple Banner Integration Using XAML

You must declare VungleAdControl with the Vungle app ID and placement ID for the banner placement. Specify that this VungleAdControl is for a banner ad by passing isBannerAd set to 'True' and allow it to automatically load and play a banner ad by passing AutoRun set to 'True'.

Sample code:

<UI:VungleAdControl x:Name="vungleBannerControl" AutomationProperties.AutomationId="vungleBannerControl"
IsBannerAd="True"
AutoRun="True"
AppID="YOUR_VUNGLE_APP_ID"
Placement="BANNER_PLACEMENT_ID">
    <Border BorderBrush="Black" BorderThickness="1" Margin="10">
        <TextBlock Text="Banner Ads will show here..." VerticalAlignment="Center" HorizontalAlignment="Center"/>
    </Border>
</UI:VungleAdControl>

Banner Integration With Programmatic Control

You can use XAML in conjunction with code to programmatically control when to LoadBannerAd, PlayBannerAd, or LoadAndPlayBannerAd to load and play banner ad at your preferred timing in your app's lifecycle.

  1. Specify the ad container In XAML. You must configure VungleAdControl in XAML with isBannerAd set to 'True'. Specify the ad container size to fit the banner size that you want to display by passing the correct Width and Height values.

    Sample XAML:
    <UI:VungleAdControl x:Name="vungleBannerControl" AutomationProperties.AutomationId="vungleBannerControl"
        IsBannerAd="True"
        Width="320" Height="50" Margin="10" HorizontalAlignment="Left">
        <Border BorderBrush="Black" BorderThickness="1" Margin="10">
            <TextBlock Text="Banner Ads will show here..." VerticalAlignment="Center" HorizontalAlignment="Center"/>
        </Border>
    </UI:VungleAdControl>
  2. Set the app ID for VungleAdControl. Start by sending the app ID for the VungleAdControl using AppID API. Note that the Vungle SDK is a singleton class, and you can use only one app ID at any one time. If you are playing a banner ad with fullscreen ads, pass in the identical app ID that you use in the GetInstance function to initialize the SDK.

    Instantiate VungleAdControl:

    VungleSDKConfig sdkConfig = new VungleSDKConfig();
    sdkConfig.DisableBannerRefresh = true; // Default: false
    
    sdkInstance = AdFactory.GetInstance(vungleAppID, sdkConfig);
    this.vungleBannerControl.AppID = vungleAppID;
  3. Load and play the banner ad. You can load and play a banner ad at the same time using the LoadAndPlayBannerAd API. If you prefer to preload a banner ad and play it later, you can use the LoadBannerAd and PlayBannerAd instead, to have finer control of the banner placement timing. You must pass the placement ID for banner ad and supported banner size when using these APIs, called on a UI thread. You can use StopBannerAd to stop displaying a banner ad at anytime.

    LoadAndPlayBannerAd:

    await vungleBannerControl.Dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () =>
    {
        this.vungleBannerControl.LoadAndPlayBannerAd("YOUR_PLACEMENT_ID", VungleBannerSizes.Banner_320x50);
    });

    LoadBannerAd:

    this.vungleBannerControl.LoadBannerAd("YOUR_PLACEMENT_ID", VungleBannerSizes.Banner_320x50);

    PlayBannerAd:

    this.vungleBannerControl.PlayBannerAd("YOUR_PLACEMENT_ID", VungleBannerSizes.Banner_320x50);

    StopBannerAd:

    this.vungleBannerControl.StopBannerAd();

Ad Configuration Options

These are the available properties in the AdConfig object instance.

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.

Volume

1.0

double

This setting represents a fraction of the device volume and accepts values between 0.0 and 1.0.

Note: This setting is only available for v6.3.0 and above.

Incentivized

-

DEPRECATED

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

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

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

Show 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.

GDPR Recommended Implementation Instructions

As of May 25, 2019, 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 sample code below 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.
// To set the user’s consent status as opted in to version 1.0 of your consent dialog:
sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentAccepted,"1.0");

// To set the user’s consent status as opted out of version 2.0 of your consent dialog:
sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentDenied,"2.0"); // To find out what the user’s current consent status is: // This will return null if the GDPR Consent status has not been set // Otherwise, it will return VungleConsentStatus.VungleConsentAccepted or // VungleConsentStatus.VungleConsentDenied UpdateConsentStatus? currentStatus = sdkInstance.GetCurrentConsentStatus();

// To find out which version of your consent dialog the user was last shown:
sdkInstance.GetConsentMessageVersion();

If you are using Vungle SDK v6.2 or lower, set the consent status as follows:

// To set the user’s consent status on SDK versions 6.2 and below:
sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentAccepted);

Subscribe 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) { }
Powered by Creativity Driven by Performance Sign Up Here

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Was this article helpful?