In-App Bidding With Vungle SDK for Windows

Julia Stein

January 14, 2025 01:44

Use this article to monetize your Windows app through in-app bidding with Vungle SDK.

Brief Overview

Data Flow: Rendering an In-App Bidding (Mediated) Ad

Each of these data flow diagrams is described in detail later in this document.

Data Flow, Part 1: Involving the Vungle SuperToken

Data Flow, Part 2: Involving Ad Markup

Terminology Used in This Article

The following concepts are depicted in the data flow diagrams above:

ad markup: A subsection of the bid response sent back by the Vungle Server to the Bidding Server.
bid request: Information sent by the Bidding Server to the Vungle Server that includes the Vungle SuperToken. The bid request informs Vungle of an impending auction for a placement and provides it with the information necessary to decide whether to bid.
bid response: Information sent by the Vungle Server to the Bidding Server in response to a bid request. If Vungle decides to bid, the bid response includes various bits of information; most importantly to this document are the bid amount and the ad markup. (If Vungle decides not to bid, it responds with a sleep code, or no response.)
Bidding Server: Sometimes referred to as the Server Adapter, this is the publisher-side server that sends out bid requests, collects all bids, runs the auction, and sends out win/loss notifications.
initialization: Initialization prepares the Vungle SDK to send ad requests to the Vungle Server. Initialization sends information about the device, such as the local time, the IP address, the app in use, the current volume setting, etc.
pre-cached bid token: The essential portion of the Vungle SuperToken, the bid token identifies a single creative and is used by Vungle's bidding server to decide if this particular creative is worth bidding on for a particular user of the customer's app. The Vungle SDK receives this bid token from the /ads response.
SDK Adapter: Sometimes referred to as the Mediation Adapter, this is the publisher-side app software that allows the app to support ad networks within its mediation integration. It connects the publisher app to ad networks, allowing publishers to display ads from multiple networks with a single integration.
Vungle SDK: The Software Development Kit (SDK) is code provided by Vungle and integrated in the publisher app. The Vungle SDK enables the publisher to communicate with the Vungle Server, and to request and show ads.
Vungle Server: Sometimes referred to as the Mediation Server, this Vungle component receives bid requests from the Bidding Server, reads the Vungle SuperToken within each bid request to decide whether to bid on the placement, and, if bidding, sends a bid response containing ad markup back to the Bidding Server.
Vungle SuperToken: A base64-encoded and gzip compressed JSON blob used by the Vungle Server to determine whether to bid on a placement. The SuperToken is described here; refer to a decoded sample of the SuperToken payload.

Vungle SuperToken

Data Flow, Part 1: Involving the Vungle SuperToken

Part 1 of the data flow is as follows:

On the user’s device, the SDK Adapter initializes the Vungle SDK.

Vungle ads are automatically cached. On initialization, the Vungle SDK makes a request to the Vungle /ads endpoint, and caches the ad received; as that ad is playing, the Vungle SDK makes another request to the /ads endpoint.

Privacy settings must be updated prior to initialization.
The SDK Adapter must learn whether the Vungle SDK is ready to furnish it a SuperToken for a given placement. You must check if a placement is ready for a SuperToken every time you want to load and play an ad. The SDK Adapter can check this either asynchronously by listening to the OnReadyForSuperToken event (recommended), or by calling the static IsMediatedAdReadyForSuperToken method.

To listen asynchronously (recommended), subscribe to the OnReadyForSuperToken event as follows:
```
m_sdk.OnReadyForSuperToken += Sdk_OnReadyForSuperToken; 
private void Sdk_OnReadyForSuperToken(object sender, MediatedAdReadyForSuperToken e)  
{
    try  
    {   if (e.IsReadyForSuperToken)  
        {  
            System.Diagnostics.Trace.WriteLine(String.Format("Placement {0} is ready for SuperToken", e.Placement));
        } 
    } 
    catch (Exception ex)
    { 
        // log error
    }
}
```
Note that OnReadyForSuperToken is not guaranteed to fire, even if initialization was successful. There are cases where Vungle AI systems contraindicate showing an ad to a given user, and no ad/creative is sent.

To use the static method, call:
```
String targetPlacement = “My placement’s name” 
bool isReady = s_sdk.IsMediatedAdReadyForSuperToken(targetPlacement);
```
If the above method returns ‘true’, proceed. Otherwise, wait until this call returns ‘true’.
Once the placement is ready for a Supertoken, the SDK Adapter calls the Vungle SDK with:
```
String superToken = m_sdk.GetMediationSuperToken();
```
to request and receive a SuperToken for a specific placement.
The SDK Adapter sends the Vungle SuperToken, along with the equivalent information from any other SDKs, to the Bidding Server.
The Bidding Server now sends out bid requests to the SDK servers that correspond to all SDKs on the device. In its bid request to the Vungle Server, it forwards the SuperToken, which Vungle uses to decide whether to bid.
If the Vungle Server decides to bid on the placement, it returns a bid response containing a real-time token/ad markup (and, of course, a bid amount) to the Bidding Server.
The Bidding Server runs the auction, and, if Vungle wins, sends a win notification to the Vungle Server.
These steps continue in Data Flow, Part 2: Involving Ad Markup.

About the Vungle SuperToken

The Vungle SDK must receive a SuperToken to get a Vungle ad. The Vungle SuperToken is a set of specialized data that Vungle uses to decide to bid. The SuperToken consists of compressed JSON objects, base64 encoded.

Refer to the decoded and encoded samples of the SuperToken payload below:

Examining the decoded sample payload below, the essential content of the SuperToken is the pre-cached bid tokens; this is the precached_tokens object inside the request object, highlighted in yellow.
Examining the encoded sample payload below, the ‘3’ (highlighted in yellow) at the start indicates the version of the SuperToken.

When the Vungle SDK makes an ad request (to the Vungle /ads endpoint) on initialization, the response from /ads contains either a pre-cached bid token or a sleep code. In the case that the /ads response is a sleep code or there is no response at all, the Vungle SDK doesn’t receive the needed pre-cached bid token for the placement in question (which is the most important component of the SuperToken), and Vungle does not accept the bid.

Sample SuperToken Payload, Decoded

{
    "consent": {
        "ccpa": {
            "status": "opted_in"
        },
        "gdpr": {
            "status": "unknown",
            "source": "publisher",
            "message_version": "",
            "timestamp": 0
        }
    },
    "device": {
        "battery_saver_enabled": false,
        "language": "en-US",
        "time_zone": "America/Los_Angeles",
        "ifa": "5712383640816a4f91698da444611b28",
        "windows": {
            "ashwid": "0300dc0f0800b4ef0500328c05004192050023b40500c7c605006ae3060001000400105b0400ce60040062790400c6850400f69001007efb0200004f0900a6e0"
        }
    },
    "request": {
        "config_extension": "CvABEiEKCURWX0FwcF9NQRIPU29mdF9CbG9ja19MaXN0GAEiATESIQoJRFZfSVZUX01BEg9Tb2Z0X0Jsb2NrX0xpc3QYASIBMRIlCiFleHBsb3JlX2V4dF9mbGF0Y3BtX1VTX211bHRpcGxpZXIYAhIpCiVleHBsb3JlX2V4dF9mbGF0Y3BtX25vbi1VU19tdWx0aXBsaWVyGAISKAokZXhwbG9yZV9leHRfaGJfVVNfcmVzZXJ2ZV9mbG9vcl9wY3QxGAISLAooZXhwbG9yZV9leHRfaGJfbm9uLVVTX3Jlc2VydmVfZmxvb3JfcGN0MRgC",
        "ordinal_view": 1,
        "sdk_user_agent": "VungleWindows/6.11.5-qa2 (Windows 10; native)",
        "precached_tokens": [
            "2|GoeHyA==|crqr0a1j956c9lkfq250"
        ]
    }
}

Sample SuperToken, Encoded

3:H4sIAAAAAAAACn1Ua2+bMBT93l8R8WmTuu5iEhpv2gcSJWnSNlqThtJME7LNJfEChmLIY4//PpPuwbp1SOiI43PvPdhH/nLSMo8lMqVRldab1pcj8UiKnP3BHFldsrLShreyvMQolMr6Jfh2+rt6FeXF/6ortVHZTlmnTwRZVQisBXnFE6nXWDyVpKg1W2G4xULLTNXap5JSGlHJ0twswm97Jw2TVoRbeZzU+GXOyhKLQ6iZaR6iYjzByEhilmhs/FzC1KoyHurZqF4t5g0Dx+Hh50wdV70UCynY66tMh55aYYK6qZVxvcWWTaOuDS5rR6QdYccF5nLArs1d4XZshzdLdlJF2U7/vbdMr3eydmuBAxAJiKELwNsYQwfAIV1RY9umpEbi8HaN4ly4NboMHXABwDZv

Ad Markup

Data Flow, Part 2: Involving Ad Markup

The second portion of the data flow is as follows:

Having been notified that it won, the Vungle Server sends the ad markup to the Bidding Server.
The Bidding Server forwards the ad markup to the SDK Adapter.
The SDK Adapter calls the LoadMediatedAd API in the Vungle SDK, sending the ad markup, as follows:
```
bool startedLoad = m_sdk.LoadMediatedAd(targetPlacement, RealtimeAdm);
```
The SDK Adapter must check the return value (startedLoad) to ensure everything worked.

The SDK Adapter must check whether the ad has completed loading either by subscribing to OnAdPlayableChanged event, or by calling:
```
IsMediatedAdPlayable(String placement, String adMarkup)
```
Note that LoadMediatedAd returns ‘false’ if it has bad inputs. The return value is mainly for your debugging.

In this call, the event_id object in the ad markup is used to identify which ad response to use to download the assets.
The SDK Adapter must check with the Vungle SDK that the ad has been loaded.

To use the static method (recommended), call:
```
IsMediatedAdPlayable(placement, markup)
```
To listen asynchronously, subscribe to the OnAdPlayableChanged event.
The SDK Adapter calls the PlayMediatedAd API in the Vungle SDK, again forwarding the ad markup, as follows:
```
var adConfig = new AdConfig(); // you can change any defaults you like
String eventId = await m_sdk.PlayMediatedAd(
    placement,
    adConfig,
    Adm);
```
The event_id object in the ad markup is used by Vungle to identify which ad response to use when calling the TPATs. You can use the event_id for debugging purposes (to send to Vungle if there’s a problem with a creative).
The SDK Adapter plays the ad.

About Ad Markup

The ad markup is contained in the bid object, and defines the ads. The Vungle SDK only looks at the ad markup portion of the bid object (highlighted in yellow in the sample payload below).

In the Monetize Dashboard, publisher accounts are set for Real-Time Ad or Multi-Cache ad delivery.

For real-time ads, the Ad Markup contains the actual ad.
For multi-cache ads (recommended), which is a hybrid of two delivery types, the Ad Markup may contain the entire ad, or it may contain only an identifier to a previously loaded ad.

`event_id`

Referring to the Sample ADM Payload, the event_id (highlighted in yellow) is used by the Vungle SDK which /ads response to use when showing the ad. With mediated ads, when the Vungle SDK receives the /ads response, it retrieves the bid token from that response and inserts it into the SuperToken. Now, when the Vungle SDK receives the ad markup containing the event_id , the Vungle SDK searches the /ads response to know which assets to download.

The event_id is also an identifier Vungle uses for internal debugging. In the case that a given ad/creative was downloaded and displayed by the SDK but encountered some problem that the SDK couldn't detect (such as a bug in the creative that interfered with the user playing the game–rare, but it has happened), reporting this event_id back to Vungle enables us to very quickly find the bad ad/creative.

Sample Ad Markup Payload

{
    "id": "123456",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "66e4ab03c8ff9239288c4948",
                    "impid": "234567",
                    "price": 50.001,
                    "nurl": "https://events.ads.vungle.com/api/win?settlement_price=${AUCTION_PRICE}\u0026ext=eyJpZCI6IjY2ZTM1YTI5YjlmMDY2M2JiODc4MjJkNiIsIm5hbWUiOiJtYXgiLCJwcmljZSI6NTAuMDAxLCJiZmxhdF9w

                    "event_id": "66e35a29b9f0663bb87822d6",
                    "impression": [
        "https://events.ads.vungle.com/api/impression?ext=eD6QTyW7s-qGcEbz5TWuA0VFz7JmpccfNUuKmHB6uCatujjm1d866Wbvohp6My5zlf39tZQjkkTlK8UROWtGdAgqGnDEcPS3t2MmqaTEw1HTQLW68fwlgjJPh37DvtA82ba6IENYiLtraOGrYQWFKTsSl-bO2ehCE-gSjlN8iwvrC-wyT9uxkGbuEmVWZ9Vy6QLZdXt6QZE7fZrNAvzq-BBEyI5h5FUPWeeYAapQ5IsbG5vNfjz1PlBavcXSAvCGrEwZYB-ZZjTaOriIOAOdGBJnAHpVNn6G88_bZB-NmmetC_ZSQWEaBAn5wR

Enabling In-App Bidding (Mediation) for Placements in the Monetize Dashboard

To enable in-app bidding/mediation for a placement, in the Monetize Dashboard:

Toggle the In-App Bidding option to Enabled, as shown above.
For the Ad Delivery Method, we recommend the Multi-Cache option, as shown above.
Toggle the Auto Cache option to Enabled, as shown below.