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 Universal 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 your Windows app and 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 or 2019.
  • In the Dashboard, toggle your application to Active mode if no ads are being returned in Test mode.

Download the SDK

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 from the Vungle Dashboard.
  2. Extract the archive.
  3. In Visual Studio, create a new Universal Windows 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. We recommend that you only use the Windows 10 VungleSDK.windmd file.
  5. 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 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 = “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 Publisher 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().

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

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.

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?