Attribute iOS installs with SKAdNetwork

Page Summary

outlined_flag

• Apple's SKAdNetwork API is designed to measure app install ad campaign success while preserving user privacy.

• SKAdNetwork attribution is initiated by a Google Mobile Ads SDK ad click only if the click lands directly or indirectly in the Apple App Store.

• For view-through attribution supported in SKAdNetwork v2.2+, an ad must be displayed for a minimum of 3 seconds to allow attribution.

• Ad requests enabled for SKAdNetwork attribution are backward compatible as of SKAdNetwork v4.0, allowing ad networks to respond with earlier supported versions.

The Google exchange supports signals that the Google Mobile Ads SDK uses to initiate SKAdNetwork attribution with the Apple SKAdNetwork API. You can integrate with SKAdNetwork signals to let advertisers measure the success of App Install Ad campaigns for iOS devices while maintaining user privacy.

The following list covers how app installation attribution behavior changes depending on the SKAdNetwork version:

• 2.0-2.1: Attribution for installation of an advertised app is driven by the StoreKit-rendered App Store product page when the user clicks your ad, leading to the user installing the app.
• 2.2+: Additional support for view-through ads, where attribution for installation of an advertised app is given when the user installs the app after viewing your ad.

To learn more about differences in SKAdNetwork versions, see SKAdNetwork release notes.

Configure SKAdNetwork IDs in the UI

To receive bid requests containing SKAdNetwork IDs, you must specify your SKAdNetwork IDs in the Authorized Buyers or Open Bidding UI. For example, a SKAdNetwork ID might have a value such as a1b2c3d4e5.skadnetwork.

To specify your SKAdNetwork ID in the Authorized Buyers or Open Bidding UI, do the following:

1. In the Bidder Settings navigation menu, click RTB Settings. The RTB Setting page appears.
2. Navigate to the Allowed iOS SKAdNetworks IDs box to view and configure SKAdNetwork IDs.

The following image shows an example SKADNetwork ID in the Allowed iOS SKAdNetwork IDs box:

Configure creatives for attribution

Google Mobile Ads SDK initiates SKAdNetwork attribution only if the click-through URL lands in the Apple App Store. When you submit creatives for review using the Real-time Bidding API, the creatives must use a click-through URL that either is a direct link to the advertised app in the App Store, or uses HTTP redirects where the final destination is to the advertised app in the App Store. Google Mobile Ads SDK initiates attribution if the final destination of your creative's click-through URL begins with any of the following prefixes:

• https://apps.apple.com
• https://itunes.apple.com
• itms-apps://
• itms://

If the final destination of your creative's click-through URL doesn't match these prefixes, or your click-through URL uses any other client-side redirect methods that don't lead to the App Store, Google Mobile Ads SDK might not initiate SKAdNetwork attribution. The following list covers examples of where this process might apply:

• An HTML page that requires user action to redirect to the app store.
• An HTML page that has an automated JavaScript-based redirect script to the app store.
• Meta refresh tags.

Initiate attribution by creative type

The click action to initiate SKAdNetwork attribution can be set up for the different creative types as follows:

HTML

This can be set up as the destination URL on the anchor tags surrounding the clickable element, or as the target URL of window.location operations from JavaScript-based on-click events.

MRAID

The click action needs to call Mraid.open() to initiate the SKAdNetwork attribution.

VAST video

The app store URL should be set in the ClickThrough element in the VAST XML.

Native

The app store URL must be set on the BidResponse.seatbid.bid.{adm/adm_native}.link.url field.

Identify BidRequest signals

You can find information about your registered SKAdNetwork IDs that the publisher app supports with the BidRequest.imp.ext.skadn field. If the skadn field is specified, you can use the attributes to build a response for an app install ad or re-engagement ad that associates an installation or conversion with one of the included SKAdNetwork IDs. The skadn field is a SKAdNetworkRequest object with the following attributes:

The following example shows a bid request for mobile inventory where the publisher's app supports your SKAdNetwork IDs:

{
  "id": "9NaI48SmPW7Zf3MAHR43DY",
  "imp": [
    {
      "id": "1",
      // OMITTED...
      "ext": {
        // OMITTED...
        "skadn": {
          "sourceapp": "com.google.testapp",
          "skadnetids": [
            "cF58w81X"
          ],
          "versions": [
            "2.0",
            "2.1",
            "4.0"
          ],
          "fidelities": [
            1,
            0
          ]
        }
        // OMITTED...
      }
    }
  ],
  "app": {
    "name": "Test App",
    "ver": "5.6.0",
    "bundle": "com.google.testapp",
    "publisher": {
      "id": "pub-6156239328255091",
      "ext": {
        "country": "JP"
      }
    },
    "content": {
      "url": "https://www.google.com",
      "livestream": 0,
      "language": "ja"
    },
    "storeurl": "https://www.google.com"
  }
  // OMITTED...
}

Populate BidResponse fields

You can include attribution information in your bid response that enables the advertiser to receive a postback notification when a user interacts with the advertiser's ad. To learn more about postback notifications, see Receiving ad attributions and postbacks.

You must pass attribution information that is consistent with what was included in the bid request. The attribution information is specified in the BidResponse.seatbid.bid.ext.skadn field, which is a SKAdNetworkResponse object with the following attributes:

The following example shows a bid response including app install attribution information:

{
  "id": "9NaI48SmPW7Zf3MAHR43DY",
  "seatbid": [
    {
      "bid": [
        {
          "id": "9NaI48SmPW7Zf3MAHR43DY",
          // OMITTED...
          "ext": {
            // OMITTED...
            "skadn": {
              "version": "4.0",
              "network": "cF58w81X",
              "itunesitem": "788729094",
              "sourceapp": "1422994973",
              "fidelities": [
                {
                  "fidelity": 0,
                  "nonce": "017e597c-3c7d-4a44-afeb-41cd9a17066f",
                  "timestamp": "1757235407882",
                  "signature": "11iF1L96q2cw8tu790p301c10530ogr7h250k1P9pLxqcJ2qe37klG8xB3M592YbpafQ9861493838C521XA6AEF4A40DK8X"
                },
                {
                  "fidelity": 1,
                  "nonce": "017e597c-3c7d-4a44-afeb-41cd9a17066f",
                  "timestamp": "1757235407882",
                  "signature": "f67L3C138Y6XB7940141011Pd58AZbdBk9Xo1Mlf1973706DsB5808ILLKumU2ic9fr72b9bSs3CD25CCZo8DJB65JB0615L"
                }
              ],
              "sourceidentifier": "5507"
            },
            "app_promotion_type": 1
            // OMITTED...
          }
        }
      ]
      // OMITTED...
    }
  ]
  // OMITTED...
}

The following list shares the expected behavior of SKAdNetwork corresponding to the bid response:

• When the advertised app is installed in 24 hours after the ad is viewed for at least three seconds, the SKAdNetwork view-through attribution postback notification is sent to the advertiser.
• When the ad is clicked, an inlined store overlay of the advertised app is shown, and the SKAdNetwork click-through attribution postback notification is sent to the advertiser if the user installs and opens the advertised app.

Increase attribution with SKOverlay

You can increase attribution for StoreKit-rendered ads you place by displaying an SKOverlay when SKOverlay is supported. An SKOverlay lets the publisher's app display an overlay that lets users download the advertised app without navigating away from the publisher's app. To learn more about SKOverlay, see SKOverlay.

When all of the following conditions are met, you receive attribution for installation of the advertised app:

• Your SKOverlay is displayed for three or more seconds.
• The advertised app is installed within 30 days of your SKOverlay being displayed.
• Your SKOverlay was the last displayed before the advertised app was installed.

Google supports SKOverlay for HTML snippet and VAST video creatives placed in interstitial or rewarded ads.

Determine if SKOverlay is supported

When you receive a bid request, you can find whether SKOverlay is supported by checking the value of the BidRequest.imp.ext.skadn.skoverlay field. SKOverlay is supported in cases where the skoverlay field is set to true for bidding endpoints using the OpenRTB Protobuf format, or 1 for bidding endpoints using the OpenRTB JSON format.

Place your ad with an SKOverlay

When SKOverlay is supported, you can specify the BidResponse.seatbid.bid.ext.skadn.skoverlay field to indicate that you want to display an SKOverlay. The skoverlay field has the following attributes:

• delay: An integer representing the delay in seconds between the time the ad displays and the time the SKOverlay displays. For video creatives, the display time is the time when the video starts to play. If this field is unset, the SKOverlay isn't shown.
• endcarddelay: An integer representing the delay in seconds between the time a video creative's end card is displayed and the time the SKOverlay displays. If this field is unset, the SKOverlay won't be shown after the end card. Only applicable to VAST video creatives placed in interstitial or rewarded ads.
• dismissible: A boolean representing whether the SKOverlay can be dismissed by the user.

The following example shows a bid response:

{
  // OMITTED...
  "seatbid": [
    {
      "bid": [
        {
          // OMITTED...
          "ext": {
            // OMITTED...
            "skadn": {
              // OMITTED...
              "itunesitem": "422689480",
              "skoverlay": {
                "delay": 5,
                "endcarddelay": 0
              },
              "productpageid": "some_id"
            }
          }
        }
      ]
    }
  ]
}

Review expected SKOverlay behavior

Here is the expected behavior of SKOverlay corresponding to the preceding bid response:

• Show the SKOverlay five seconds after video starts.
• Show the SKOverlay immediately after the end card.

• Open the app store when the user clicks the SKOverlay.

• If BidResponse.seatbid.bid.ext.skadn.productpageid is specified, the app listing data on the SKOverlay is the icon in the custom product page.

• For VAST video creatives, when a user clicks the SDKoverlay, the click-through and click tracking URLs are pinged.

• For VAST video creatives, even if a user dismisses the SKOverlay during the video, the SKOverlay is still shown after the end card if the BidResponse.seatbid.bid.ext.skadn.skoverlay.endcarddelay field is set.