SKAdNetwork Mobile Integration

Overview

Using Branch to manage your Advertiser SKAdNetwork integration and display SKAdNetwork data in Branch, requires updating the Branch dashboard and updating your iOS app in one of two ways:

  • OPTION 1 - Use the Branch SDK to manage all calls to SKAdNetwork
  • OPTION 2 - Integrate directly with SKAdNetwork to fully control what's sent to Apple

📘

Which SDKAdNetwork implementation option is better for you?

To learn more about the advantages of each integration approach, please read this FAQ item.

📘

Server-to-Server and TUNE SDK integrations

Any mobile app that uses a server-to-server integration, uses the TUNE SDK, or uses any other integration solution/kit that doesn't contain the Branch SDK directly must use OPTION 2 or leverage another 3rd party SDK to send events to SKAdNetwork

Prerequisites

Dashboard Setup

1. Authenticate & Integrate with Apple SKAdnetwork

🚧

DEVELOPER MAY BE REQUIRED

Authenticating your app requires access to Apple's developer tool App Store Connect as Branch requires several IDs and a key to complete authentication and sync the correct app to your Branch account.

imageimage

To configure SKAdNetwork functionality:

  1. In the left-hand navigation, under Channel & Links, click on Ads.
  2. In the Ads sub-menu, click on SKAdNetwork.
  3. On the SkAdNetwork page, click on the Configuration tab.
  4. On the Authentication tab, please provide the following App Store Connect information:
    a. Issuer ID
    b. Key ID
    c. Private Key
    - Select either "Admin" or "App Manager" access level
  5. Click Save & Continue.
  1. Once your App Store Connect account is authenticated (denoted by a green checkmark), please verify the correct app has been synced and click Integrate.

📘

App Store Connect Credentials

App Store Connect credentials are used as a one time check to verify app ownership. These credentials may be removed after the App Integration step is complete (green checkmark appears next to "App Integration"). Remove credentials by selecting "Reset App Store Credentials". The SKAdNetwork integration is complete and valid as long as the App Integration step is completed.

2. Opt-in for Branch SDK Support

In the SKAdNetwork Config section of the Branch dashboard, select the YES radio button to have the Branch SDK handle all calls to SKAdNetwork.

Do NOT opt-in if you decide to:

3. Assign Conversion Values to Events

  • In the SKAdNetwork Config section of the Branch dashboard, select all app events you want Branch to send to Apple for attribution.
  • You may optionally select a Customer Event Alias and/or a Revenue Range to further distinguish the conversion value.
  • Assign unique values to each event (Apple accepts any number from 0 to 63) that represent their level of importance to you, where 63 is the highest priority and 0 is the lowest priority. Apple will always use the event with the highest priority, regardless if an event with a lower priority was tracked afterward.

📘

Revenue Range Guidance

  • Revenue range is available for all Commerce Events where revenue is available on the event (Purchase, Add to Cart, Add to Wishlist, View Cart, Initiate Purchase, Add Payment Info, Click Ad, View Ad, Reserve, Spend Credits).
  • Revenue must be entered as USD on the dashboard. Branch will convert revenue with different currencies on events to USD.
  • Revenue ranges must not overlap for the same event (Ex: 1-100, 50-150).
  • Lower Bound Revenue is inclusive, Upper Bound Revenue is exclusive.
  • While not necessary, it is recommended to include both a lower + upper bound on every event.

APP OPTION 1: Use the Branch SDK to manage SKAdNetwork

Supported Platforms

The Branch SDK versions below automatically handle SKAdNetwork in-app functionality. If you do not integrate Branch in the platforms below, please integrate directly with SKAdNetwork instead.

Integration Steps

  • Update the Branch SDK to a version that supports SKAdNetwork
  • Import Apple's StoreKit framework into your iOS build
  • Confirm the Branch SDK initializes when the app opens. If the SDK is not initializing, have your mobile developer complete the basic Branch mobile integration. Behind the scenes, the Branch SDK will call registerAppForAdNetworkAttribution to ensure Apple attributes the install to an ad network supporting SKAdNetwork.
  • Confirm app events are tracked by the Branch SDK. If you want to add new conversion events, you will need to update the app to track those events with the Branch SDK.

📘

Changing Conversion Values

Whenever the Branch SDK tracks an event, it will call updateConversionValue and use the values mapped in the Branch dashboard. If you change the values in the dashboard, the Branch SDK will start using those new values instead.

📘

Changing the time window for SKAdNetwork callouts

By default, Branch limits updateConversionValue() calls to SKAdNetwork to within 24 hours after first install. Every time updateConversionValue() is called with a value greater than previous, this delays Apple's attribution of the original Install event by a rolling 24 hour timer.

You can, however modify this time window by using the following SDK method:
- Branch.getInstance().setSKAdNetworkCalloutMaxTimeSinceInstall(3600.0 * 24.0)

📘

Facebook - Ads delivery optimization requirement

Facebook ads delivery optimization requires that SKAdNetwork window not be delayed by more than 24 hours. Our SDK supports a default window of 24 hours.

📘

Tracking different events between SKAdNetwork and the Branch SDK

Based on your SKAdNetwork strategy, it may not always make sense to have the Branch SDK automate the SKAdNetwork in-app integration. Because of Apple's restrictions on conversion values (64 total values, no metadata, etc.), using the existing events you track with the Branch SDK may not be as effective as tracking custom values by integrating directly with SKAdNetwork. For example, if revenue is your most important metric, you can use conversion values to represent differences in revenue "basket size".

APP OPTION 2: Integrate directly with SKAdNetwork

Use this approach if you want to manage SKAdNetwork directly, rather than through the Branch SDK.

Integration Steps

  • Opt-out from having the Branch SDK manage SKAdNetwork in the dashboard setup, and complete the remainder of the dashboard setup
  • Import Apple's StoreKit framework into your iOS build

📘

registerAppForAdNetworkAttribution() only needs to be called once

Subsequent calls to this method have no effect.

Reporting conversions

  • Call updateConversionValue() from SKAdNetwork for every app event you want to send to Apple, and use the same values for each event in the Branch dashboard.
  • 24 hours after INSTALL, stop calling updateConversionValue() to align with Branch's tracking methodology. Every time updateConversionValue() is called with a value greater than previous, this delays Apple's attribution of the original Install event by a rolling 24 hour timer.

📘

Updating values in updateConversionValue()

If you change the conversion value for an event, there will be a transition period where users on the latest version of the app will report conversions with the new value, while users on older app versions will continue to report conversions with the older value (until they update their app).

Please also remember to update the values mapped in the Branch dashboard, to ensure reporting is aligned in Branch.

📘

Apple does not have a server-side API to report conversions

SKAdNetwork prevents the ability to connect users to conversions, so integrations that track events server-side must still tell the app to report the conversion to SKAdNetwork. Because the first conversion must occur within 24 hours of install, there will be a chance the event is tracked server-side but the user does not re-open the app within the 24 hour window for it to be reported to Apple.

To mitigate this risk, always track a series of events in-app that typically lead up to the server-side event (i.e., an "add-to-cart" is an event that typically occurs before a "purchase"). These don't replace your server-side event, but can serve as an effective proxy when evaluating ad campaign performance; and can also delay Apple's 24 hour timer to increase the chance of the user reopening the app in time after your server-side event is tracked.

Troubleshooting FAQs

Updated about a month ago



SKAdNetwork Mobile Integration


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


Filters