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

  • As of Vungle Windows SDK v6.11, 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, 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:
    1. Right-click on the project in Visual Studio.
    2. Select Properties.
    3. 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)

  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 and extract the archive.
  2. In Visual Studio, create a new Universal Windows project using the correct template for your application and programming language.
  3. Add a reference for your project to VungleSDK.winmd you downloaded.
  4. Make sure that your project has the internetClient capability in the package.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:
      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 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 call PlayAdAsync(), be sure to do that on the UI Thread.
  • If e.AdPlayable is 'false', then try to call LoadAd() 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.

Questions?

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

Was this article helpful?