Enable SKAdNetwork via Branch SDK
Easily integrate SKAdNetwork with Branch through the Branch SDK to easily map and rank SKAdNetwork conversion values.
Overview
It is recommended for most apps to implement SKAdNetwork (SKAN) via the Branch SDK. SKAN is "shared infrastructure" for all your ad network partners, just like Branch. Using the Branch SDK to manage SKAN is the simplest technical option, and you'll also benefit from a number of other conveniences, including easy dashboard-based mapping of SKAN conversion value calls, and automatic conversion value "decoding" for networks that support it (meaning, the network can call a Branch-provided API endpoint to understand which event correlates to a particular conversion value).
For a comparison of the different implementations, view our guide here.
Supported Platforms
The Branch SDK versions below automatically handle SKAdNetwork in-app functionality. If you do not integrate Branch in the platforms below, please Enable SKAdNetwork Natively.
Branch SDK Platform | Required Version for < SKAN 4 | Required Version for > SKAN 4 |
---|---|---|
iOS | v0.35 | v1.45.2 |
React Native | v.5.0.0 | v5.7.0 |
mParticle iOS | v.8.0.0 | v8.1.0 |
Adobe Launch iOS | v.1.3.0 | Not yet supported |
Cordova | v.4.2.0 | Not yet supported |
Capacitor | v.2.0.0 | Not yet supported |
Xamarin | v.7.0.6 | v8.1.2 |
Unity | v.0.6.6 | Not yet supported |
Flutter | v.1.1.0 | v6.5.0 |
How does it work?
- The user installs the app from a SKAN support ad network campaign.
- When the user first opens the app, the Branch SDK initializes and begins the SKAN 24-hour looping timer
- The Branch SDK will call
updateConversionValue(_:)
and use the values mapped in the Branch Dashboard.- By default, the Branch SDK limits
updateConversion(_:)
calls to SKAN to within 24 hours after first install. On every event tracked with a conversion value greater than the previous event (ex. Purchase event's conversion value > Login event's conversion value), the original 24-hour timer is reset.
- By default, the Branch SDK limits
- Once the 24-hour loping timer expires, the App Store Client sends a postback to the ad network after an additional 0-24 hour delay.
- The ad network forwards the device postback to Branch and updates reports in the Branch Dashboard.
Prerequisites
In order to implement SKAdNetwork via the Branch SDK, you must have completed the following:
- Created a Branch Dashboard.
- Enabled Universal Ads for your Branch account.
- Contact your Branch account manager or visit https://branch.io/pricing
- Implemented the latest version of the Branch iOS SDK into your mobile app.
- Apple's StoreKit Framework is implemented into your iOS build.
- Track events
- Your app is available in the Apple App Store
- Admin access to App Store Connect
- Your network/publishers support SKAdNetwork and pass attribution data to Branch
- Verify your ad network(s) here.
Enable SKAdNetwork Using the Branch SDK
1. Obtain Authentication Parameters
You will need to obtain several IDs and a key from your Apple App Store Connect:
ID | Definition | Example |
---|---|---|
Issuer ID | Your issuer ID from the API Keys page in App Store Connect. | 57246542-96fe-1a63-e053-0824d011072a |
Key ID | Your private key ID from App Store Connect. | 2X9R4HXF34 |
Private Key | Your key file that authorizes access to your data in App Store Connect and the Apple Developer website. | P8 Key File |
In the App Store Connect in Users and Access → Keys tab, find your Issuer ID and Key ID. Click Download API key to obtain your Private Key.
Generate API Key
If you have not created an API key, click the + button to generate a new API Key. Full details for creating API Keys for App Store Connect API can be found here.
2. Authenticate App Store Connect
In the Branch Dashboard under Ads > SKAdnetwork, go to the Configuration tab. If you're already logged into the Branch Dashboard, you can also click here to go there directly.
Here, you'll submit your Issuer ID, Key ID, and Private Key that you obtained from Step 1.
Click Save & Continue
Verify Connected App
Once your App Store Connect account is authenticated (denoted by a green checkmark), please verify the correct app has been synced.
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.
3. Opt-In for SDK Support
Navigate to the SDK OPT-IN tab, and mark Yes for allowing Branch SDK to make the SKAdNetwork calls on your behalf.
4. Assign Conversion Values
While on the SDK OPT-IN tab and after you've opted in you will then see a table for which you can assign a fine/coarse conversion value to a specific Branch-tracked event.
SKAN 4.0+
If you already have SKAN set up before the release of SKAN 4, you will not have coarse conversion values set for your configuration. By default, a coarse value of low is set when not initially defined (< SKAN 3). Making changes to the Event and Conversion Value Mapping will require you to select a Coarse value and Lock option for each event before you can save the configuration.
Assign an event to a fine conversion value (SKAN accepts any number from 0 to 63 that represents their level of importance). SKAN will always use the event with the highest priority, regardless if an event with a lower priority was tracked afterward. For each fine conversion value set for an event, you should also sign a coarse conversion value of low, medium, or high.
Fine & Coarse Conversion Values
A fine value is the fine-grained value of an event that is tied to a value from 0-63. In SKAN 4.0, this value is sent in the first postback for Tier 2 and 3 thresholds.
A coarse value indicates a broader signal of the level of priority that that conversion falls under (where the fine value is not eligible for use): low, medium, or high. This is only available for SKAN 4.0+ and is sent in the first postback for the Tier 1 threshold and in the second and third postbacks of Tier 1-3 thresholds.
For additional details on Postbacks and Tier thresholds, please visit Apple's documentation here.
Fine Conversion Value | Details |
---|---|
0 | The lowest priority conversion, reserved by the system to indicate the initial install. Conversion value 0 can’t have a revenue range. |
63 | The highest priority conversion |
Revenue Range
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 Range Tips
- 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.
- It is necessary to include both a lower + upper bound on every event.
Locking Events
For SKAN 4.0+, the conversion value mapper also allows you to indicate which events are "locking" events - which means that when that event is detected, it will trigger the SKAN postback and “end” the current SKAN window.
Anchor Highest Value
For SKAN 4.0+, the conversion value mapper supports the ability to anchor to the highest value which means that Branch will guarantee that the highest value event in your mapping that a user completes will be the event sent to SKAN.
5. Test SKAN Integration
Ad Network
When testing SKAN, you need to confirm that you have completed the following:
- Verified your Ad Network supports SKAN
- Ad Network forwards individual SKAN postbacks to Branch (otherwise Branch will not receive/display SKAN data)
- Campaign types within that ad network are supported by SKAN
- Use of tracking links in SKAN Campaigns.
- SKAN does not require tracking links; however, this will be needed to get engagement data (clicks/impressions) and run Predictive Modeling on those campaigns.
Test Conversion Values
You can verify whether the conversion values you've provided in the Branch Dashboard have been correctly set and the SDK is receiving them.
- Download a proxy tool such as Charles
- Enable SSL monitoring
- Using Charles proxy, you need to follow their documentation to enable SSL monitoring
- Open the application and trigger events tied to conversion values.
- For INSTALLs: Look for
invoke_register_app
- For Other Conversions: (Must be tied to a conversion value) Look for
update_conversion_value
- For INSTALLs: Look for
{
"session_id" : "850166709486919576",
"data" : "{\"+clicked_branch_link\":false,\"+is_first_session\":false}",
"device_fingerprint_id" : "847563926187298061",
"identity_id" : "850166709481620778",
"invoke_register_app" : true,
"link" : "https:\/\/3mnv.app.link?%24identity_id=850166709481620778"
}
{
"branch_view_enabled" : false,
"update_conversion_value" : 42
}
Test Apple Postbacks
You can also verify whether events are properly being attributed through Apple Postbacks.
SKAN 3.0 Data Availability
SKAN does not attribute conversions in real-time. When the app is installed, a 24-hour rolling timer begins, and only when that timer expires, can the install then be attributed after an additional 0-24 hours. Every time an additional conversion is reported with a conversion value greater than the previous value, the 24-hour rolling timer is reset and the install does not get attributed until that 24-hour timer is allowed to expire. Apple offers a developer profile, that can reduce the timers for testing from 24 hours to 5 minutes.
- Set up a test campaign with the participating ad network. Please note that your app will need to be in production and not in Testflight or any other testing platform.
- Download an Apple SKAdNework Testing Profile to decrease the time in which the postback is sent from a test device from 24 hours to 5-10 minutes.
- See Apple docs here for instructions.
- Check the SKAdNetwork Analytics dashboard in Branch to see SKAdNetwork data
- To see data from a particular ad network navigate to the “Ad Networks” tab in the SKAdNetwork dashboard, and filter by the ad partner you were testing with.
Additionally, you can verify with your Ad Network the data that they are receiving proper postbacks for the SKAN campaigns.
Advanced
Changing the Time Window for SKAdNetwork Callouts
You can modify the time window by using the following SDK method:
Branch.getInstance().setSKAdNetworkCalloutMaxTimeSinceInstall(3600.0 * 24.0)
Updated 11 months ago