MoPub iOS 14 Support Proposal

Core parts of the proposal were adopted by the IAB Tech Lab as an OpenRTB Community Extension. See our OpenRTB integration spec for the inclusion of this standard.

SKAdNetwork Support

MoPub proposes to support SKAdNetwork attribution by allowing DSPs to submit signed clicks to the SKAdNetwork API. DSPs that register with Apple may:

  • Obtain a SKAdNetwork ID
  • Obtain a private key that allows them to sign their key that can be verified by Apple
  • Specify a postback endpoint to receive install attribution notifications.

If a DSP wishes to use MoPub’s SKAdNetwork solution, after registering with Apple, they should provide MoPub with their SKAdNetwork ID.

MoPub would publish a list of the SKAdNetwork IDs of our DSPs, and our SDK integration guide would instruct publishers to include these IDs in their Info.plist, which is required for SKAdNetwork to work.

We would flag which bid requests have SKAdNetwork support so DSPs can bid accordingly. MoPub proposes new objects in the OpenRTB bid request and bid response to facilitate this, which are detailed below.

Bid request

If a DSP has at least one SKAdNetworkItem in the publisher app’s Info.plist we would include a new object in the bid request that provides the necessary information to create a signature. Object would only be present if both the MoPub SDK version and the OS version (14+) support skadnetwork. Available only on a OpenRTB 2.5 integration.

Object: BidRequest.imp.ext.skadn

Attribute Description Type Example
version Version of skadnetwork supported. Always "2.0" or higher. Dependent on both the OS version and the SDK version. string "version": "2.0"
sourceapp ID of publisher app in Apple’s App Store. Should match BidRequest.app.bundle string "sourceapp": "880047117"
skadnetids A subset of SKAdNetworkItem entries in the publisher app’s info.plist that are relevant to the DSP. array ["cDkw7geQsH.skadnetwork","qyJfv329m4.skadnetwork"]
skadnhsh A hash of the full list of SKAdNetworkItem entries. Hash table will be provided outside the bidstream for DSPs to consume. See SKAdNetwork IDs Hash for more details. string "93f901d8b1cc722e48d6bbe46f2e4ce38fb851f857131fa429eaed2489453b52"
ext Placeholder for exchange-specific extensions to OpenRTB. object "ext": {}

Example for skadnetids

Used for direct SSP to DSP connections where a DSP wants to only consume their own relevant SKAdNetwork IDs.

{
  "imp": [
    {
      "ext": {
        "skadn": {
          "version": "2.0",
          "sourceapp": "880047117",
          "skadnetids": [
            "cDkw7geQsH.skadnetwork",
            "qyJfv329m4.skadnetwork"
          ]
        }
      }
    }
  ]
}

Example for skadnhsh

Used for intermedary SSP to SSP/DSP to DSP connections where a full list SKAdNetwork IDs is required. Provided in a compact hash format. See SKAdNetwork IDs Hash for more details.

{
  "imp": [
    {
      "ext": {
        "skadn": {
          "version": "2.0",
          "sourceapp": "880047117",
          "skadnhsh": "93f901d8b1cc722e48d6bbe46f2e4ce38fb851f857131fa429eaed2489453b52"
        }
      }
    }
  ]
}

Bid response

If the bid request included the BidRequest.imp.ext.skadn object, then a DSP could choose to add the following object to their bid response. If the object is present in the response, then MoPub would submit the click data and signature to the productView for attribution.

Object: BidResponse.seatbid.bid.ext.skadn

Attribute Description Type Example
version Version of SKAdNetwork desired. Must be 2.0 or above. string "version": "2.0"
network Ad network identifier used in signature. Should match one of the items in the skadnetids array in the request string "network": "cDkw7geQsH.skadnetwork"
campaign Campaign ID compatible with Apple’s spec. As of 2.0, should be an integer between 1 and 100, expressed as a string string "campaign": "45"
itunesitem ID of advertiser’s app in Apple’s app store. Should match BidResponse.bid.bundle string "itunesitem": "880047117"
nonce An id unique to each ad response string "nonce": "473b1a16-b4ef-43ad-9591-fcf3aefa82a7"
sourceapp ID of publisher’s app in Apple’s app store. Should match BidRequest.imp.ext.skad.sourceapp string "sourceapp": "123456789"
timestamp Unix time in millis string used at the time of signature string "timestamp": "1603246928149"
signature SKAdNetwork signature as specified by Apple string "signature": "MEQCIEQlmZRNfYzK…"
ext Placeholder for exchange-specific extensions to OpenRTB. object "ext": {}

Example

{
  "seatbid": [
    {
      "bid": [
        {
          "ext": {
            "skadn": {
              "version": "2.0",
              "network": "cDkw7geQsH.skadnetwork",
              "campaign": "45",
              "itunesitem": "880047117",
              "nonce": "473b1a16-b4ef-43ad-9591-fcf3aefa82a7",
              "sourceapp": "123456789",
              "timestamp": "1603246928149",
              "signature": "MEQCIEQlmZRNfYzKBSE8QnhLTIHZZZWCFgZpRqRxHss65KoFAiAJgJKjdrWdkLUOCCjuEx2RmFS7daRzSVZRVZ8RyMyUXg=="
            }
          }
        }
      ]
    }
  ]
}

SKAdNetwork Support Flow

iOS 14 SKAdNetwork Flowchart

Flow diagram of MoPub’s SKAdNetwork support. Objects in blue have a change required to pre-iOS-14 ad flows.

  1. MoPub SDK retrieves the SKAdNetworkItems from the publisher app’s Info.plist
  2. SDK makes ad request to ad server including SKAdNetworkItems
  3. MoPub determines from Info.plist which DSPs have SKAdNetwork capabilities. Bid request to eligible DSPs includes the imp.ext.skadn object, defined above
  4. DSP responds, including seatbid.bid.ext.skadn if the campaign requires SKAdNetwork support
  5. Ad response to SDK includes skadn object
  6. If the impression is shown and the user clicks, MoPub calls loadProduct() with the appropriate data, including the DSP-signed signature. If valid, Apple will consider the app for install attribution
  7. Target app must register that user for SKAdNetwork attribution on app launch.
  8. (Optional). Target app can choose to provide an additional 6 bits of conversion value information.
  9. If SKAdNetwork determines that the DSP’s click led to the install, Apple will send a postback to the DSP’s registered endpoint with the ids of the source app, target app and campaign, and conversion value if provided by the target app.

SKAdNetwork IDs Hash

Problem: How to represent large lists of IDs programmatically where there may not be a standard list or there is publisher customization?

Solution/Implementation: SSP/SDK retrieves a list of all SKAdNetwork IDs and generates a standardized hash of the values. These hashes would be identical across SSP/SDK networks. The hashes would be available in a downloadable table, giving everyone access to a full list of IDs on each app version. A standardized list could be generated easily from the client device, simplifying transmission for prebid or other use cases.

Proposed Hash:

  1. Pull all SKAdNetwork IDs from Info.plist
  2. String to lower (assumes Apple SKAdNetwork IDs are case insensitive, checking with Apple to confirm)
  3. Sort Ascending
  4. Dedupe
  5. Concatenate comma-separated (no whitespace)
  6. Use SHA function to hash IDs (preference towards SHA256 but SHA512 is another option)

Sent in an BidRequest.imp.ext.skadn.skadnhsh field as a string.

Example (using a SHA256 hash):

Grab list from Info.plist:

2U9PT9HC89.skadnetwork
4FZDC2EVR5.skadnetwork
7UG5ZH24HU.skadnetwork
mlmmfzh3r3.skadnetwork
T38B2KH725.skadnetwork
W9Q455WK68.skadnetwork
YCLNXRL5PM.skadnetwork

Process list:

2U9PT9HC89.skadnetwork,4FZDC2EVR5.skadnetwork,7UG5ZH24HU.skadnetwork,mlmmfzh3r3.skadnetwork,T38B2KH725.skadnetwork,W9Q455WK68.skadnetwork,YCLNXRL5PM.skadnetwork

Output sha (example uses SHA256):

93f901d8b1cc722e48d6bbe46f2e4ce38fb851f857131fa429eaed2489453b52

Looking up the above hash in the lookup table (provided for download/API from MoPub) will yield the list:

2U9PT9HC89.skadnetwork,4FZDC2EVR5.skadnetwork,7UG5ZH24HU.skadnetwork,mlmmfzh3r3.skadnetwork,T38B2KH725.skadnetwork,W9Q455WK68.skadnetwork,YCLNXRL5PM.skadnetwork

Device IDs

We recognize that if the IDFA is not available, DSPs require an alternative, limited-scope device ID in order to provide basic non-targeting functionality to advertisers.

Examples of this include frequency capping, fraud detection and analytics. Pending further analysis, we propose the following changes to the bid request:

Bid request

Attribute Description Type Example
BidRequest.device.ifa Preferred device ID to pass. For iOS, is all zeros unless permission to track has been granted. string "ifa": "5CD1D2BF-7958-4955-A964-95DBF9ABF780"
BidRequest.user.id Equal to BidRequest.device.ifa if the idfa is non-zeroes. Else, the IDFV if available. Else, a MoPub-specific device ID for each user within each app. string "id": "9B9BF1EF-0646-467D-A09A-5478B7DFC130"
BidRequest.device.ext.ifv IDFV of device in that publisher. Only passed when IDFA is unavailable or all zeros. Listed as ifv to match ifa field format. string "ifv": "336F2BC0-245B-4242-8029-83762AB47B15"

Click Through

Click Through behavior when SKAdNetwork is enabled:

  • MoPub’s iOS SDK will open productView with the skadn for the creative.
  • All other clicks or click throughs in the creative or in external clicktracker fields will be fired in the background as click trackers. Examples:
    • VAST ClickThrough becomes a clicktracker.
    • mraid.open becomes a clicktracker.
    • HTTP redirects will be followed for the click response, but any response that is not a 3xx HTTP redirect will be ignored.
  • If there is no skadn for the creative, the SDK will fallback to the current behaviour of following the click through to its destination.

Click Tracking

We propose an BidResponse.seatbid.bid.ext.clicktrackers array that accepts a list of click trackers provided in the bid response, and is fired by the SDK in addition to any other click urls supported by a creative or in the creative spec. This is a convenience feature that also helps address the change in click behaviour with SKAdNetwork.

Bid Response

Object: BidResponse.seatbid.bid.ext

Attribute Description Type Example
clicktrackers Array of click tracking URLs to fire string "clicktrackers": ["https://tracker.example.com/click?id=57750EF0-3125-49FF-89AA-0B6A398B21FA"]

Changelog

  • [08/13/2020]
    • Added BidRequest.ext.skadn.skadnhsh for hash list support
    • Added Click Through change description
    • Added BidResponse.seatbid.bid.ext.clicktrackers

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

Last updated October 21, 2020

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.

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