Knowledge base

Optimization features

Overview

Unified Auction offers additional features that empower partners to optimize their buying strategies on the exchange. This article covers the following:

Contextual data extensions

Unity offers additional metric signals on the app or user providing the impression, to help fine-tune your bidding strategies. Contact your account manager to enable the following data sets:

Attribute Data Type Example Description
mediationOrdinal int "mediationOrdinal": 1 The developer implements Mediation Ordinal. It signifies how many ads have been in the game session across other ad networks.
mute bool "mute": true The current state of mute on the device when the request is made.
gameCategory string "gameCategory": "Games" Google Play and Apple App Store category definitions
subGameCategory string "subGameCategory": "Simulation" Google Play and Apple App Store Sub-game category definitions.
sessionDepth int "sessionDepth": 1 The number of times an ad has been delivered for the current session.

Note: Unity will not pass any of these data signals if they are not present in the request.

Bid request example with contextual data

{ 
    "id": "ueBgFDxOdJ1Y9uairdIkVB", 
        "imp": [{ 
            "id": "1", 
                "banner": { 
                    "w": 320, 
                    "h": 480, 
                    "battr": [1, 3, 5, 6, 8, 9], 
                    "pos": 7 
                }, 
            "instl": 1, 
            "tagid": "com.unity.example-vast", 
            "secure": 1 
        }], 
        "app": { 
            "id": "123abc4d5e0aa0473a80e9e1f43528d8", 
            "name": "Example Game", 
            "bundle": "123456789", 
            "storeurl": "https://itunes.apple.com/us/app/ExampleGame/id123456789?mt=8" 
        }, 
        "device": { 
            "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_2_5 like Mac OS X) AppleWebKit/604.5.6 (KHTML, like Gecko) Mobile/15D60", 
            "geo": { 
                "lat": 50.0144, 
                "lon": -50.2772, 
                "type": 2, 
                "country": "USA", 
                "city": "San Francisco", 
                "utcoffset": -480 
            }, 
            "ip": "123.123.12.123", 
            "devicetype": 4, 
            "model": "iPhone7,2", 
            "os": "ios", 
            "osv": "11.2.5", 
            "hwv": "iPhone 6", 
            "h": 667, 
            "w": 375, 
            "language": "en", 
            "carrier": "ATT", 
            "connectiontype": 2, 
            "ifa": "12345AB-C6789-DEFG-0123" 
        }, 
    "at": 2, 
    "tmax": 200, 
    "regs": {}, 
    "ext": { 
        "mediationOrdinal": 1, 
        "mute": true, 
        "gameCategory": "Games", 
        "subGameCategory": "Simulation" 
        "sessionDepth": 1 
    } 
} 

Back to top

Viewability data extensions

Unified Auction provides specific viewability metrics within the bid request. Through select viewability partnerships (MOAT Analytics), Unity can pass historical viewability measurements based on the Media Rating Council (MRC) and GroupM definition within each bid request.

Viewability standard definition

The MRC viewability requirement states that at least 50% of a video ad must be in view on-screen for 2 seconds before it counts as viewable.

metrics object

Based on OpenRTB specification 2.5 section 3.2.5, Unity sends viewability data through the metrics object in the bid request.

Attribute Data Type Example Description
type string valid_and_viewable_perc The specific metric measured by viewability partner (in this case, the MOAT Valid and Viewable Rate, defined as the number of valid impressions that were viewable under the MRC standard).
value float 0.995 Value of the metric in numeric format (precision-3).
vendor string MOAT Viewabilty measurement partner.

Example bid request

{ 
    "id": "abCdEFgOdJ1Y9abcdeIkZB", 
    "imp": [{ 
        "id": "1", 
        "video": { 
            "mimes": [ 
                "video/mp4" 
            ], 
            "minduration": 15, 
            "maxduration": 30, 
            "protocols": [2, 3, 5, 6], 
            "w": 375, 
            "h": 667, 
            "linearity": 1, 
            "sequence": 1, 
            "battr": [1, 3, 5, 6, 8, 9, 13], 
            "pos": 7 
        }, 
        "instl": 1, 
        "tagid": "com.unity.example-vast", 
        "secure": 1, 
        "metrics": [{ 
            "type": "valid_and_viewable_perc", 
            "value": 0.994, 
            "vendor": "MOAT" 
        }], 
        "app": { 
            "id": "123abc4d5e6fg7890a80e9e1f43528d8", 
            "name": "Example Game", 
            "bundle": "123456789", 
            "storeurl": "https://itunes.apple.com/us/app/ExampleGame/id123456789?mt=8" 
        }, 
        "device": { 
            "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_2_5 like Mac OS X) AppleWebKit/604.5.6 (KHTML, like Gecko) Mobile/15D60", 
            "geo": { 
                "lat": 50.0144, 
                "lon": -50.2772, 
                "type": 2, 
                "country": "USA", 
                "city": "San Francisco", 
                "utcoffset": -480 
            }, 
            "ip": "123.123.12.123", 
            "devicetype": 4, 
            "model": "iPhone7,2", 
            "os": "ios", 
            "osv": "11.2.5", 
            "hwv": "iPhone 6", 
            "h": 667, 
            "w": 375, 
            "language": "en", 
            "carrier": "ATT", 
            "connectiontype": 2, 
            "ifa": "12345AB-C6789-DEFG-1234" 
        }, 
        "at": 2, 
        "tmax": 200, 
        "regs": { 
            "ext": {} 
        } 
    }] 
}

Back to top

Loss notifications

Unity strives to enable partner success on its exchange by providing real-time loss notifications. These notifications communicate the reason that the participating bid lost in the auction. Advertising partners can leverage real-time information to inform their bidding strategies effectively across Unity’s inventory.

Integration

To receive loss notifications, include an optional lurl (loss URL) attribute in your response's bid object (for a complete guide on generating bid responses, see Unity's OpenRTB bid responses specs). This allows Unity to populate the loss reason code within the bid response.

Attribute Type Example Description
lurl string "lurl": "http://example.com/?bid=123456&loss=${AUCTION_LOSS}" Loss notice URL called by the exchange when a bid loses in auction.

Unity will return the loss reason code within the ${AUCTION_LOSS} macro.

Loss reason codes

The following are loss reason codes Unity may return. Note that codes below 1001 are custom loss reasons that are not defined in the OpenRTB 2.5 spec.

Code Reason Description
1 Internal error A Unity internal error.
2 Impression opportunity expired The impression took too long to show, such that the impression tracker was no longer valid.
3 Invalid bid response The partner responded with no fill, did not respond at all, or failed in Unity’s OpenRTB validator.
4 Invalid Deal ID The Deal ID in the bid response does not match the deal(s) in the bid request.
5 Invalid auction ID The ID in the bid request is not same as the ID in the bid response.
6 Invalid (malformed) advertiser domain The adomain (ad domain) attribute field in the bid response is an invalid format.
7 Missing ad markup The adm (ad markup) attribute field is empty.
8 Missing creative ID The crid (creative ID) attribute field is empty.
9 Missing bid price The price (bid price) attribute field is empty.
101 Bid below deal floor The bid price was below the bid floor set in the request.
102 Lost to higher bid The bid lost the auction because to a higher bid price.
104 Buyer seat blocked The publisher has blocked the buyer or partner.
200 Creative filtered (reason unknown) A catch-all for creatives that were filtered when the reason is unknown.
201 Creative filtered (pending approval) The creative’s status is pending approval for the exchange.
202 Creative filtered (approval denied) The creative was disapproved by Unity’s exchange review.
203 Creative filtered (invalid size) The width and height of the creative does not match the dimensions defined in the request.
205 Creative filtered (advertiser exclusions) The publisher has excluded the advertiser.
206 Creative filtered (app bundle exclusions) The publisher has blocked the app bundle.
209 Creative filtered (category exclusions) The publisher has blocked the advertising content category.
212 Creative filtered (video length) The video length exceeds 30 seconds.
1000 Failed Unity validator The bid failed validation due to compliance with Unity’s OpenRTB standards described in the request-response integration guides.
1001 Invalid JSON format The bid response is a malformed JSON.
1002 General marketplace rule block A catch-all error for marketplace blocks that occur in the Unity Auction.
1003 Max age rating exceeded The publisher blocked the bid due to the advertised app's age rating.

Back to top

Still need help? Get in touch!
Last updated on 26th Jun 2019