SKAdNetwork 2.2 Support Proposal

The following is a proposal for discussion and feedback purposes only, and is subject to change.1

Goals

  • Define which bid requests support the different versions of SKAdNetwork
  • Provide support for view through attribution (VTA)

View Through Attribution (VTA)

The following proposal discusses possible SKAdNetwork v2.2 improvements. The current spec can be viewed here.

SKAdNetwork v2.2 introduces View Through Attribution (VTA) which allows buyers to claim credit for intalls that occur when a user installs an app after having seen an ad within 24 hours. Credit submission is done using a new Apple API, and requires the ad renderer to define a startImpression time and an endImpression time. Apple will only consider views that lasted 3+ seconds for attribution credit.

Apple distinguishes a click attribution claim from a view attribution claim using a new fidelity-type attribute. The fidelity-type must be declared inside the attribution signature, and in the click claim itself. (Currently, it does not appear that it needs to be declared in the view claim). It is also present in the install postback, which allows advertisers to measure how many installs were driven by each fidelity-type.

Current fidelity-types:

Attribution Claim Fidelity-type
View (min. 3 seconds) 0
Click 1

It’s possible that additional fidelity types will be defined by Apple in the future, so we kept that in mind when designing this protocol.

The new SKAdImpression object also features 3 properties that are not featured in SKAdNetwork 2.0 or 2.1:

Apple’s documentation currently states that these properties are not used, and it’s currently unclear if these are required. This proposal includes them in the specification, but implementation may be left until clarification is received from Apple on their intended use. Therefore we are not including them in the proposal until we have more clarity on their future use.

Bid Request

There are no additional changes required in the bid request. The versions field was recently accepted as a proposal by the IABTL.

Old Bid Request v2.0 New Bid Request v2.1, v2.2
BidRequest.imp.ext.skadn BidRequest.imp.ext.skadn
{
   "version": "2.0"
}
{
   "version": "2.0",
   "versions": ["2.0", "2.1", "2.2"]
}

Note: For graceful deprecation of the version field, SSPs should consider continuing to include the field with a hard coded 2.0 or 2.1.

Bid Response

Given that each fidelity type requires its own signature, the bid response for SKAdNetwork v2.2 needs to change such that the SSP can accept signatures for multiple fidelity types. The bidder should be able to chooose which fidelity types they wish to submit claims for. The proposed spec allows for a bidder to submit for single or multiple fidelity types, each of which are optional.

Given the clarification of Apple’s current documentation by Apple, MoPub is proposing the following option for how to adapt the bid response.

Fields that should have different values for the different fidelity types (e.g. fidelity, nonce, signature) are wrapped into an array of objects that define the click and impression object. These include:

  • fidelity-type
  • nonce
  • signature
  • timestamp

Adding timestamp to this list allows bidders to parallelize the cryptography portions of creating their bid response. You can use the same timestamp if you want to, but it allows two cryptography codepaths to generate a signature each without having to synchronize time to the millisecond. This provides more implementation flexibility to bidders ultimately.

This is a tradeoff between managing the size of the response, and remaining flexible for future changes.

Old Bid Response v2.0, v2.1 New Bid Response v2.2
BidResponse.seatbid.bid.ext.skadn BidResponse.seatbid.bid.ext.skadn
{
   "version": "2.0",
   "network": "bidder1.skadnetwork",
   "itunesitem": "123456789",
   "sourceapp": "880047117",
   "campaign": "45",
   "nonce": "12345",
   "timestamp": "1594406341",
   "signature": "abc"
}
{
   "version": "2.2",
   "network": "bidder1.skadnetwork",
   "itunesitem": "123456789",
   "sourceapp": "880047117",
   "campaign": "45",
   "fidelities": [
      {
         "fidelity": 0,
         "signature": "abc",
         "nonce": "12345",
         "timestamp": "1594406341"
      },
      {
         "fidelity": 1,
         "signature": "def",
         "nonce": "67890",
         "timestamp": "1594406342"
      }
   ]
}

Client Behavior

Clicks

Click behavior is largely unchanged. Per Apple’s documentation, the fidelity-type field should be included in the call to loadProduct() when using v2.2.

Views

If view through attribution is requested by the bidder, the client should create the SKAdImpression object and set the startImpression time at the same time as when the client considers an impression to have been rendered. This is typically the time at which other impression trackers are fired.

The client should submit the endImpression when an impression is deemed to be complete. Note that impressions must always have an endImpression, per Apple’s docs:

Apple Impression

Future Enhancements

SKAdNetwork Trackers

A future extension to the SKAdNetwork section of the OpenRTB protocol could be to include trackers that get dispatched whenever interactions with the Apple APIs occur.

Changelog

  • [02/23/2021]
    • Removed Option 1 and Option 3 given Apple’s clarifications
    • Removed protversion from Option 2
    • Removed Version Compatibility since IABTL approved of that proposal.
  • [02/19/2021]
    • Removed adtype, addescription, and adpurchasername until more clarity is provided by Apple
    • Updated the nonce examples to be different in Option 2 and 3
    • Provided guidance that sending bid response fidelity-types are optional. e.g. a Bidder can opt to only send a click fidelity-type on the bid response.

1 MoPub will be free to use any feedback, comments or suggestions in any way without compensation or obligation.


Last updated August 10, 2021

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2021 MoPub (a division of Twitter, Inc.)