optimization - Unity-Technologies/unity-ads GitHub Wiki

/* Title: Optimization features Description: Optimize your bidding strategies Sort: 7 */

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
Open Measurement (OM) extensions
Loss notifications

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+" 
    } 
}

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.

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

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.
`1004`	Missing crypte in bid extension	Bid extension did not have crypte when responding to a consolidated bid request.
`1005`	Invalid crypte in bid extension	The crypte ID was invalid or did not match any of the ad types sent in the consolidated bid request.