iOS

Migrate your iOS app from Branch.io to Grovs for deep linking, universal link handling, event tracking, and more.

Overview

This guide will help you migrate from Branch.io to Grovs for deep linking, universal link handling, event tracking, and more.

Prerequisites

You already have a Grovs account and have integrated the Grovs SDK into your project.
- If not, refer to the iOS SDK integration guide for instructions on adding the SDK using Swift Package Manager or CocoaPods.
Your app previously used Branch.io, and you are now transitioning to Grovs.

Key Steps in Migration

To ensure full functionality, you'll need to replace Branch.io methods with their Grovs equivalents in both the App Delegate and Scene Delegate. Below are the detailed steps.

1. Initialization

Branch.io

Branch.io initialization typically occurs in the AppDelegate:

Swift

Branch.getInstance().initSession(launchOptions: launchOptions) { params, error in
    // Handle params (deep link data) here
}

Grovs

Grovs SDK initialization is done via the Grovs.configure() method:

Swift

import Grovs
 
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Grovs.configure(APIKey: "your-api-key", useTestEnvironment: false, delegate: yourDelegate)
 
    // Optionally, set debug level and user attributes
    Grovs.setDebug(level: .info)
 
    return true
}

2. Universal Links and URL Handling

AppDelegate Approach

If your app does not use a Scene Delegate, you need to handle universal links and URLs in the AppDelegate:

Branch.io:

Swift

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    return Branch.getInstance().continue(userActivity)
}
 
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    return Branch.getInstance().handleDeepLink(url)
}

Grovs:

Replace Branch.io methods with the following Grovs equivalents:

Swift

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    return Grovs.handleAppDelegate(continue: userActivity, restorationHandler: restorationHandler)
}
 
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    return Grovs.handleAppDelegate(open: url, options: options)
}

SceneDelegate Approach

If your app uses a Scene Delegate (iOS 13+), you need to forward universal links and URLs to Grovs in the SceneDelegate:

Session Initialization with Connection Options

Branch.io:

Swift

@available(iOS 13.0, *)
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    if let userActivity = connectionOptions.userActivities.first {
        Branch.getInstance().continue(userActivity)
    } else if let urlContext = connectionOptions.urlContexts.first {
        Branch.getInstance().handleDeepLink(urlContext.url)
    }
}

Grovs simplifies this with a single method for handling scene connection options:

Swift

@available(iOS 13.0, *)
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
    Grovs.handleSceneDelegate(options: connectionOptions)
}

Handling Universal Links

Branch.io:

Swift

@available(iOS 13.0, *)
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    Branch.getInstance().continue(userActivity)
}

Grovs:

Swift

@available(iOS 13.0, *)
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    Grovs.handleSceneDelegate(continue: userActivity)
}

Handling URL Contexts

Although Branch.io doesn't explicitly provide a SceneDelegate method for handling URLContexts, it relies on AppDelegate or conditional handling within willConnectTo:

Swift

if let urlContext = connectionOptions.urlContexts.first {
    Branch.getInstance().handleDeepLink(urlContext.url)
}

In Grovs, you explicitly handle URL contexts in the SceneDelegate:

Swift

@available(iOS 13.0, *)
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    Grovs.handleSceneDelegate(openURLContexts: URLContexts)
}

3. Generating Links

Branch.io

Branch.io uses BranchUniversalObject to generate links:

Swift

let branchUniversalObject = BranchUniversalObject(canonicalIdentifier: "content/12345")
branchUniversalObject.title = "My Content Title"
branchUniversalObject.contentDescription = "Link Subtitle"
branchUniversalObject.imageUrl = "imageURL"
branchUniversalObject.generateShortUrl { url, error in
    if let url = url {
        print("Generated URL: \(url)")
    }
}

Grovs

Grovs simplifies this with a direct method:

Swift

Grovs.generateLink(
    title: "My Content Title",
    subtitle: "Link Subtitle",
    imageURL: "imageURL",
    data: ["key": "value"],
    tags: nil
) { url in
    if let url = url {
        print("Generated URL: \(url)")
    }
}

4. Retrieving Referrals or Attribution Data

Branch.io

Branch.io retrieves user referrals or attribution data via:

Swift

Branch.getInstance().getLatestReferringParams()

Grovs

Grovs does the exact same thing using the following method:

Swift

Grovs.allReceivedPayloadsSinceStartup() { payloads in
    // Do something with them
}

5. User Identification and Attributes

In Branch.io, user identification and attributes are handled through methods such as setIdentity() and setRequestMetadata(). In Grovs, you can achieve similar functionality using the userIdentifier and userAttributes properties.

Branch.io

To identify a user and associate metadata with their events:

Swift

Branch.getInstance().setIdentity("user_identifier_from_your_app")
Branch.getInstance().setRequestMetadataKey("name", value: "Donald Duck")
Branch.getInstance().setRequestMetadataKey("age", value: "77")

Grovs

In Grovs, user identification and attributes are set directly via properties:

Swift

Grovs.userIdentifier = "user_identifier_from_your_app"
Grovs.userAttributes = ["name": "Donald Duck", "age": 77]

Replacement Summary Table

Feature	Branch.io Method	Grovs Equivalent
Initialization	`initSession`	`configure`
Debugging	-	`setDebug`
Universal Links (App Delegate)	`continue`	`handleAppDelegate`
	`handleDeepLink`	`handleAppDelegate`
Universal Links (Scene Delegate)	`continue`	`handleSceneDelegate`
	-	`handleSceneDelegate`
	-	`handleSceneDelegate`
Generating Links	`generateShortUrl`	`generateLink`
Retrieving Referrals/Attribution	`getLatestReferringParams`	`allReceivedPayloadsSinceStartup`
User Identification	`setIdentity`	`userIdentifier`
User Attributes	`setRequestMetadataKey`	`userAttributes`

Notes for Migration

Initialization: Ensure that the SDK is properly configured with your API key using Grovs.configure() instead of Branch.getInstance().initSession().
Debugging: Grovs offers a method setDebug() for logging, which Branch.io doesn't have explicitly.
Universal Links Handling: Depending on whether your app uses the AppDelegate or SceneDelegate, make sure to use the appropriate Grovs method (handleAppDelegate or handleSceneDelegate) in place of Branch.io's methods for handling universal links and deep links.
Generating Links: When generating links, replace BranchUniversalObject with Grovs.generateLink().
Referrals and Attribution: Use Grovs.allReceivedPayloadsSinceStartup() for retrieving referrals or attribution data.
User Identification and Attributes: Instead of setIdentity() and setRequestMetadataKey() in Branch.io, set userIdentifier and userAttributes directly in Grovs.