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.
bAge string "bAge": "17+" Content age ratings that are blocked by the publisher. If your app's age rating (as defined on its store page) exceeds this value, your bid will be filtered out.

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": "ABCDEfghijkLMNOPqrstUV", 
        "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,
        "bAge": "17+" 
    } 
} 

Back to top

Open Measurement extensions

Unity Ads supports Open Measurement-capable creatives. IAB’s Open Measurement SDK (OM SDK) offers common code and libraries for facilitating third-party access to measurement data. Sites and apps that integrate the OM SDK can send measurement signals to an Open Measurement Interface Definition (OMID) API. Measurement providers can place tags that collect these signals. In order to ingest and act on bid requests that support OM creatives, Unity has updated its OpenRTB specs to reflect related changes to the bid request and response fields.

Parent object Attribute Type Example Description
bid.source omidpn string "omidpn": "Unity3d" An identifier for the Open Measurement SDK integration. This is the same as the name parameter of the OMID Partner object.
bid.source omidpv string "omidpv": "1.2.10" The version of the Open Measurement SDK integration. This is the same as the versionString parameter of the OMID Partner object.
bid.imp.video api int array "api": [7] Supported API frameworks for this impression. A value of 7 signifies Open Measurement support.
response.seatbid.bid api int "api":7 The API framework supported for this impression. A value of 7 signifies Open Measurement (OM) support. For more information, see the API Frameworks section of the IAB Open Measurement SDK manual.

Note: Unity expects the OMID-1 API Framework value (7) for each bid inside the response. This allows the SDK to properly handle the OM creative.

See also OM specs for creative formats.

Example bid request

{
    "id": "ABCDEfghijkLMNOPqrstUV",
    "imp": [{
        "id": "1",
        "video": {
            "mimes": ["video/mp4"],
            "minduration": 5,
            "maxduration": 30,
            "protocols": [2, 3, 5, 6],
            "w": 320,
            "h": 480,
            "linearity": 1,
            "sequence": 1,
            "battr": [1, 3, 5, 6, 8, 9, 13],
            "pos": 7,
            "api": [7]
        },
        "pmp": {},
        "displaymanager": "unity sdk",
        "displaymanagerver": "3200",
        "instl": 1,
        "tagid": "com.example.enterprise-vast",
        "secure": 1
    }],
    "app": {
        "id": "1",
        "publisher": {
            "id": "12345"
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E302",
        "geo": {
            "lat": 55.5555,
            "lon": 11.1111,
            "type": 2,
            "country": "DNK",
            "region": "84",
            "metro": "0",
            "city": "Copenhagen",
            "utcoffset": 60
        },
        "ip": "111.222.111.222",
        "devicetype": 4,
        "model": "iPhone10,1",
        "os": "ios",
        "osv": "11.3.1",
        "hwv": "iPhone10,1",
        "h": 647,
        "w": 375,
        "language": "en",
        "carrier": "Sprint",
        "connectiontype": 2,
        "ifa": "A123456B-7C89-01D2-3456-E7F890123GH4"
    },
    "at": 2,
    "tmax": 500,
    "source": {
        "pchain": "11111:12345",
        "omidpn": "Unity3d",
        "omidpv": "1.2.10"
    },
    "regs": {
        "ext": {}
    },
    "ext": {
        "placementType": "",
        "gameCategory": "Games",
        "subGameCategory": "Casual",
        "sessionDepth": 0
    }
}

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 18th Nov 2019