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
- As of Vungle Windows SDK v6.11.0, Vungle supports Windows 11. The support for Windows 8.1 has been deprecated as of Vungle Windows SDK v6.10.1, making Vungle Windows SDK v6.8.0 the last SDK that supported Windows 8.1. Vungle Windows SDK now supports Universal Windows Platform application only.
- As of Vungle Windows SDK v6.11.0, Vungle supports ARM64. This requires you to set your minimum target version in Microsoft Project to Windows 10.0 build 16299 (also known as the Fall Creators Update, or version 1709). To do this:
- Right-click on the project in Visual Studio.
- Select Properties.
- Update Min version to ‘Windows 10 Fall Creators Update (10.0; Build 16299)’ or higher.
Note that this is required for all publishers, even those unaffected by ARM64.
- The integration requires a Liftoff account, so create an account if you haven’t already done so, and create a new Windows Universal Windows app in your account. Refer to the Add Your Apps and Placements section of our Using the Monetize Dashboard article to learn how to set up your Windows app and placements in the Liftoff Monetize dashboard.
Download the SDK
We strongly recommend following the NuGet integration steps to download the Vungle SDK for Windows. If you opt for the manual integration option, you can 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 (recommended) or manual integration.
Option 1. NuGet Integration (Recommended)
- In Visual Studio, right-click on your Project's name in the Solution Explorer and select Manage NuGet Packages.
- Click Browse, enter ‘Vungle’, and select Vungle SDK.
- Click Install.
Option 2. Manual Integration
- Download the Vungle Windows SDK and extract the archive.
- In Visual Studio, create a new Universal Windows project using the correct template for your application and programming language.
- Add a reference for your project to
VungleSDK.winmd
you downloaded. - Make sure that your project has the
internetClient
capability in thepackage.appxmanifest
file. The Internet (Client) capability is turned on by default when you create a new project. You can verify this in Visual Studio or via manual edit. Note that when you create a new UWP app, this capability is turned on by default.- To verify
internetClient
capability in Visual Studio:- In Visual Studio, double-click
appxmanifest
in Solution Explorer. - Select Capabilities.
- Confirm that the Internet (Client) option is checked.
- In Visual Studio, double-click
- To ensure
internetClient
capability via manual edit, open thepackage.appxmanifeset
file and addinternetClient
to theCapabilities
section:<Capabilities> ... <Capability Name="internetClient" /> ... </Capabilities>
- To verify
Step 2. Import the VungleSDK
Namespace
Import the VungleSDK
namespace into your code file as follows:
using VungleSDK;
Step 3. Obtain a VungleAd
Instance
Starting with Vungle Windows SDK v6.3.0, the VungleAd
instance takes only one parameter: your Vungle app ID. In this example below, replace appId
with your Vungle app ID.
VungleAd sdkInstance;
string appId = “VUNGLE_APP_ID”;
sdkInstance = AdFactory.GetInstance(appId);
Next, set up an initialization handler as instructed below, to know when Vungle has finished initialization and is ready for you to call other Vungle method calls, such as LoadAd()
and PlayAdAsync()
.
Step 4. Add Code
Create and Register 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 if you need any UI interaction or updates resulting from an event listener, you must do that on 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
}
);
Diagnostic
This event handler is called when the SDK wants to print diagnostic logs. Use this handler to debug problems when integrating Vungle into your application.
Sample code:
//Register event handler
sdkInstance.Diagnostic += SdkInstance_Diagnostic;
...
// 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);
}
OnInitCompleted
This event handler is called immediately after initialization of the SDK has completed. Wait for this event to fire before calling any Vungle methods such as LoadAd()
or PlayAdAsync()
.
Inside this handler, you may choose to call LoadAd()
ad for any placements you want to load right away, to ensure that they will be loaded immediately, and that the ads are available to play as soon as possible. You can later use IsAdPlayable()
to check if the ad is loaded, and then PlayAdAsync()
to play the ad.
If you don't want to use an event handler, you can also use the IsInitialized()
call to determine if the SDK is initialized. If e.IsInitialized
is 'false' when this event is fired, first check to make sure that the app ID you used in your call to GetInstance()
is correct. If the app ID is correct, and you have very recently set up or changed your Vungle account on our Monetize Dashboard, wait 30 minutes before trying again.
Sample code:
//Register event handler
sdkInstance.OnInitCompleted += SdkInstance_OnInitCompleted;
...
// 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;
// Initialization was a 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)";
}
}
}
// Initialization failed; check to make sure your appID is correct, and that your machine is connected to the Internet
else
{
placementsInfo += "\n\t" + e.ErrorMessage;
}
System.Diagnostics.Debug.WriteLine(placementsInfo);
// If we are updating the UI, we need to run our update code on the UI thread
await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() => NotifyInitialization(e.Initialized)));
}
OnAdPlayableChanged
Create an event handler for the OnAdPlayableChanged
event. This event handler is called when the ad availability state changes. This event is called shortly after you call LoadAd()
when required ad assets complete downloading.
In your code, wait for this event to fire before playing a PlayAdAsync()
. After you call LoadAd()
, this event fires to notify you whether the ad was successfully downloaded. Note that sometimes an ad can fail to load due to a temporary shortage of appropriate ads.
- If
e.AdPlayable
is 'true', then your ad is ready to play. If you callPlayAdAsync()
, be sure to do that on the UI Thread. - If
e.AdPlayable
is 'false', then try to callLoadAd()
again at a later time.
You can identify which placement triggered the event by checking e.Placement
, and you can check if the placement has loaded successfully by checking e.AdPlayable
.
If you don’t want to use an event handler to determine when a placement is loaded or playable, you can instead use the IsAdAvailable()
method to poll for when the placement is ready to play.
// Event handler for OnAdPlayableChanged event
private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e)
{
// If the Ad has been successfully loaded, then
if (e.AdPlayable == true)
{
// e.Placement - Vungle placement ID which has had a change in availability;
// that is, this placement is now either ready to play (
// If you need to update the UI, run asynchronously on the UI thread
await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() => methodToUpdateUI(e.Placement)));
}
else
{
// You may need to try to call LoadAd() again later, as Vungle may be short on Ad supply
}
}
OnAdStart
This event handler is called before playing an ad. You can use this handler to perform actions such as pausing your application's background music so that it doesn’t interfere with sounds from the playing advertisement.
Sample code:
//Register event handler
sdkInstance.OnAdStart += SdkInstance_OnAdStart;
...
// 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);
}
CampaignID
and CreativeID
Starting with Vungle Windows SDK v6.8.0, the OnAdStart
event will pass CampaignID
and CreativeID
within AdEventArgs parameter which can be used to track creative that is just about to be displayed.
The following contains an example of how users can access CreativeID
and CampaignID
values.
// e.CreativeID - Vungle Creative ID in string
// e.CampaignID- Vungle campaign iD in string
private void SdkInstance_OnAdStart(object sender, AdEventArgs e)
{
System.Diagnostics.Debug.WriteLine(“CreativeID: “ + e.CreativeID + "\nCampaignID is “ + e.CampaignID);
}
OnAdEnd
This event handler is called when the user closes the ad 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, like music or sounds.
Sample code:
//Register event handlers
sdkInstance.OnAdEnd += SdkInstance_OnAdEnd;
...
// 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);
}
Integrate Ad Formats
Complete your SDK integration for each ad format you plan to display in your app. Refer to our instructions for each ad format:
Further Customize Your Ads
Follow the instructions in our Advanced Settings article to fine-tune your app's integration with additional configuration options, such as GDPR, CCPA implementation, and many other settings.