Enable SKAdNetwork

Overview

Easily set up SKAdNetwork (SKAN) with Branch through a quick-and-easy Magic Setup or configure granular settings yourself all through the Branch SKAN Conversion Center.

Prerequisites

In order to implement SKAdNetwork via the Branch SDK, you must have completed the following:

1. Created a Branch Dashboard.

2. Enabled Ads for your Branch account.

   • Contact your Branch account manager or visit https://branch.io/pricing

3. 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.

4. Your app is available in the Apple App Store.

   • Admin access to App Store Connect.

5. Your network/publishers support SKAdNetwork and pass attribution data to Branch.

   • Verify your ad network(s) here.

   • Campaign types within that ad network are supported by SKAN.

   • Utilizing Branch Ad Links in SKAN Campaigns.

1. Obtain Authentication Parameters

You will need to obtain several IDs and a key from your Apple App Store Connect:

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 navigate to the SKAN Conversion Center page. 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.

Once your App Store Connect account is authenticated (denoted by a green checkmark), please verify the correct app has been synced.

App Store Connect Credentials

App Store Connect credentials are used as a one-time check to verify app ownership.

DO NOT remove API access as it will disable the ability to map conversion values.

3. Opt-In/Out for SDK Support

By default, your configuration will be set to SDK Opt-In, meaning the Branch SDK will call the two necessary Apple methods for SKAN to enable Postbacks to ad partners on your behalf. You may update this by clicking the options menu on the top right of the SKAN Conversion Center page and selecting Opt-out SKAdNetwork.

We suggest opting out if you have a third-party library or SKAN integration.
You'll still be able to map your conversion value events that will also appear within the Branch Dashboard. Note: Once opted out, the Branch SDK will stop updating SKAN postback conversion values.

Opt-Out

If you are opting out for the Branch SDK to make calls on your behalf, you will need to follow Apple's documentation for calling the updatePostbackConversionValue(_:completionHandler:) method when appropriate as well as define your conversion values.

4. Select Set Up Type

From here, you will be prompted to select a set up type: Magic Set Up or Custom Set Up.

Magic Set Up

Select Target Conversion Event

After selecting Magic Set Up, you will be prompted to select a target conversion event. It is recommended you select a conversion event that is meaningful for your specific app's use case that demonstrates customer value.

Review Recommendations

Once a conversion event is selected, click Run Magic Set Up, and Branch will generate a recommendation for each SKAN window for you.

Click Save Configuration to confirm your SKAN setup.

Custom Set Up

After selecting Custom Set Up, you will be able to set an event to a fine-grained value in each of the three windows available for SKAN postbacks.

Templates

Optionally, you can select a template to preset SKAN for a specific vertical and Branch will help optimize for that. You may choose a template by clicking the Try now or See Templates link.

At any time, you may revert your configuration to a preset template.

Assign Events

Assign an event to a Fine-Grained Value. For each event set to a fine-grained value, assign a Coarse-Grained Value.

Fine & Coarse Conversion Values

A fine value is the fine-grained value of an event that is tied to a value from 0-63 (63 being the highest priority conversion). 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.

SKAN 4.0+

If you already had 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.

Revenue Range

Revenue range is available for all Commerce Events:

• Revenue must be entered as USD.

• Revenue ranges must not overlap for the same event (Ex. 1-100 and 50-150).

• Lower bound is inclusive, Upper bound is exclusive.

Locking Events

For SKAN 4.0+, you are allowed 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.

Click Save Configuration to confirm your settings and view your settings for each window.

5. Verify Integration

SKAN Data Availability & Reporting

SKAN does not attribute conversions in real-time. Postbacks sent/recieved abide by the SKAdNetwork Event Flow.

Additionally, you can view your full guide on all SKAdNetwork-related reporting here.

1. 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.

2. 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 documentation here for instructions.

3. Check the SKAdNetwork Analytics page to verify SKAdNetwork data.

Additionally, you can verify with your Ad Network the data that they are receiving are proper postbacks for the SKAN campaigns.

Advanced

Defining Conversion Values for SDK Opt-Out

If you are opting out of the Branch SDK making your SKAN calls for you, you will need to define what each conversion value means for which events you want SKAdNetwork to be attributed. Branch will report the conversion value as it is received from the ad network.

24 hours after INSTALL, stop calling updatePostbackConversionValue() to align with Branch's tracking methodology.  Every time updatePostbackConversionValue() is called with a value greater than the previous, this delays Apple's attribution of the original Install event by a rolling 24-hour timer.
- Note: 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).

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 installation, 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.

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.

1. Download a proxy tool such as Charles

2. Enable SSL monitoring

   • Using Charles proxy, you need to follow their documentation to enable SSL monitoring

3. 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

{
  "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
}

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)