Seamlessly Migrate From TUNE to Branch Before September 4, 2023

In case you haven’t heard, Branch will end support for all TUNE services on September 4, 2023. The TUNE SDK will no longer function after this date and could significantly impact your app experience. If your team is still using the TUNE SDK, you have just a few months left to migrate over to the Branch SDK. Don’t worry — your friends at Branch have you covered!

To begin migrating to the latest version of the Branch SDK, follow the steps outlined in this blog post to ensure that your users’ in-app experiences are not negatively impacted, they can access the latest features, and you continue to receive campaign data support after the September 4 cutoff date.

Where do I start?

To begin the migration process you’ll need the following:

• Branch Dashboard
• List of the deep link destinations currently in your app
• List of the events you are currently tracking via the TUNE SDK

As an existing Branch customer using the TUNE SDK, you already have a Branch Dashboard. Oftentimes customers ask whether they should switch to a new Branch Dashboard for the migration. The answer to that is no, we strongly suggest using your existing Dashboard. Otherwise, you would need to redo a lot of your team’s work, like re-enabling every ad partner and re-creating every deep link.

Next, inventory all the existing deep link destinations in your app. Each of the TUNE links you create for deep linking will have an encoded URI scheme and path for the invoke_url query parameter. Work with your mobile team to understand and list each of the places users can be taken in the app. You’ll need this list when you build Branch links after the migration.

Similarly, list all the events you are currently tracking via the TUNE SDK. To ensure your analytics and reporting run seamlessly, track each of the same events through the Branch SDK. While there are some differences in the events and properties that the SDKs support, this list will give your team a starting point to spot-check key analytics before the app goes live.

Key differences between TUNE and Branch

While the TUNE and Branch SDKs have many similarities, you should be aware of some key differences when migrating from TUNE to Branch:

1. App Credentials: Initializing the TUNE SDK requires two values — Advertiser ID and Conversion Key. With the Branch SDK, you only need one value — the Branch Key.
2. Link Domain: TUNE links use the tlnk.io domain (e.g., branchster.tlnk.io),whereas Branch links use the app.link domain (e.g., branchster.app.link).
3. Opening the App: TUNE opens the app exclusively by URI Schemes. The Branch SDK supports App Links for Android and Universal Links for iOS, and it will fall back to URI Schemes only in edge cases where these first attempts don’t work.
4. Deep Link Data: The TUNE SDK allows you to retrieve the referrerUrl, which is the link that was clicked to open the app. From it, you can extract the URI scheme and the path to the deep link destination. With the Branch SDK, you will receive a JSON payload in the app of the link data for the Branch link that was clicked.
5. Deferred Deep Linking: TUNE provided two different endpoints — one for regular deep linking and the other for deferred deep linking. With Branch, deferred deep linking is handled automatically, and no additional work is required to support it.

Parts and roles of a TUNE link

A TUNE link looks like this:

https://branchster.tlnk.io/serve?action=click&site_id=1505569806&invoke_url%3Dbranchster%3A%2F%2Fxyz%2F123&url_android%3Dhttps%3A%2F%2Fhelp.branch.io%2Fdevelopers-hub%2Fdocs%2Fandroid-sdk-overview&url_ios%3Dhttps%3A%2F%2Fhelp.branch.io%2Fdevelopers-hub%2Fdocs%2Fios-sdk-overview&url_web%3Dhttps%3A%2F%2Fwww.branch.io%2F

Highlighted are the most important parts of the link that play a crucial role in its functionality:

https://branchster.tlnk.io/serve?action=click&site_id=1505569806&invoke_url%3Dbranchster%3A%2F%2Fxyz%2F123&url_android%3Dhttps%3A%2F%2Fhelp.branch.io%2Fdevelopers-hub%2Fdocs%2Fandroid-sdk-overview&url_ios%3Dhttps%3A%2F%2Fhelp.branch.io%2Fdevelopers-hub%2Fdocs%2Fios-sdk-overview&url_web%3Dhttps%3A%2F%2Fwww.branch.io%2F

Let’s break down the key parts and respective roles of this link:

Branch equivalents to TUNE query parameters

In order to create a Branch link that functions the same way as this TUNE link, we need to understand the Branch equivalents for the query parameters. The mapping of TUNE to Branch query parameters is as follows:

How to migrate your deep link routing logic

To migrate your deep link routing logic, there are two key processes to understand:

1. Creating a Branch link
2. Implementing the deep link routing logic

Create a Branch link

To begin, create a Quick Link on the Branch Dashboard, which will provide a link like this:

https://branchster.app.link/example

Next, use the path from invoke_url as the value for the $deeplink_path parameter. Note that you can leave off the URI scheme since that is specified on the Branch Dashboard and will be automatically prepended to the $deeplink_path value when the app is opened. The value of $deeplink_path also doesn’t need to be encoded.

https://branchster.app.link/example?$deeplink_path=/xyz/123

Then, map the other fields to their Branch equivalents, like this:

https://branchster.app.link/example?$deeplink_path=/xyz/123&$url_android=https%3A%2F%2Fhelp.branch.io%2Fdevelopers-hub%2Fdocs%2Fandroid-sdk-overview&$url_ios=https%3A%2F%2Fhelp.branch.io%2Fdevelopers-hub%2Fdocs%2Fios-sdk-overview&$desktop_url=https%3A%2F%2Fwww.branch.io%2F

That completes the creation of a Branch link with the equivalent parameters of the TUNE link we started with.

Implement deep link routing logic

For deep link routing logic, add code that will deep link the user using the Branch link data to ensure that any Branch links you use will take the user to their content of interest when the app opens. You’ll also want to ensure that your existing routing logic for TUNE links continues to work, in case a user clicks a TUNE link in the wild.

To do this, you can use the +non_branch_link property inside the Branch callback. If the property is storing the value of a TUNE link, then use their existing TUNE logic to handle that scenario. Be sure to move the TUNE deep link logic from wherever it is now into the Branch callback. For reference, the logic would now look something like this:

if the user has clicked a Branch link:

     Deep link using the Branch link data

Else:

     If +non_branch_link is holding a tlnk.io link:

          Use existing TUNE deep link logic

It is also important to note that TUNE had a different endpoint for deferred deep linking. However, since Branch handles this automatically, no additional work is needed.

Transition to Branch event tracking

When transitioning to the Branch SDK, take the following steps to ensure a smooth analytics transition:

• Understand the additional events that Branch enables you to track
• Convert your TUNE event tracking code to Branch code to continue tracking the same events you currently do
• Understand the mapping of metadata fields and update your reporting systems accordingly

Both the TUNE and the Branch SDK support some out-of-the-box (OOTB) and Standard Events. The OOTB events tracked automatically by the TUNE SDK are: session, install, open, close, and update.

The TUNE SDK supports the following standard events: registration, login, add to wishlist, add to card, added payment info, reservation, checkout initiated, purchase, search, content view, tutorial complete, level achieved, achievement unlocked, spent credits, invite, rated, and share.

For a full list of the Standard Events Branch supports, be sure to check out our Event Ontology.

In terms of properties or metadata attached to TUNE events, some of them do not have Branch equivalents and are combined 2-in-1 or 3-in-1 in a Branch field. The full mapping can be found here. Below are some key fields to be aware of and their Branch equivalents:

Next steps

Please utilize our TUNE Migration Guide as a structural checklist to migrate over to the Branch platform. Ensure you migrate to the Branch SDK by September 4, 2023 to avoid disruption to your app experience. Branch is here to support you during this transition — just reach out to your Account Manager or [email protected] with any questions.