macOS Basic Integration
SDK Stats
Open Source Github Repo: https://github.com/BranchMetrics/mac-branch-deep-linking
PREREQUISITE
Before you implement the SDK, please ensure you have Configured Link Behaviors for Redirects and Link Domains.
1. Install Branch SDK
Please choose one of the following integration methods to install the Branch Framework in your app.
Swift Package Manager is supported by Branch macOS SDK 1.3.0+
To add the Branch macOS SDK GitHub repo as a Swift Package dependency:
- With the project name selected in the project navigator and the project editor, click on the Swift Packages tab.
- Click on the + button to add a package.
- Use the package URL for the Branch macOS SDK, "https://github.com/BranchMetrics/mac-branch-deep-linking", and continue.
- Make sure the Branch Swift Package is being added to the correct target and click Finish.
- If you have any other targets that need to use the Branch Swift Package, select the target and add it under Frameworks, Libraries, and Embedded Content in the General tab.
The Swift Package tab for your project should now look like the following:
CocoaPods is supported by Branch macOS SDK 1.3.0+
- If you don’t have a pod file in your project directory already, go ahead and initialize one by running pod
init. - You should now have a file named
Podfilein your project directory. - Your
Podfileshould look like this: - Now that you have your dependencies listed in your
Podfile, go ahead and install your dependencies by runningpod install. If you don’t have a workspace already CocoaPods will create one that includes the dependencies you just installed. The CocoaPods generated framework should already be added to the target you specified in yourPodfile.
platform :osx, '10.14'
target 'Example' do
use_frameworks!
pod 'BranchMacOS'
end
Manual Team Signing Required
- Clone the Branch macOS SDK:
git clone https://github.com/BranchMetrics/mac-branch-deep-linking. - In the lower right hand corner of Project Navigator in Xcode click on the + button and select the option to add files to your workspace.>
- Select the
Branch.xcodeprojfile which is located in the Branch macOS SDK directory you cloned in step 1. You should now see the Branch project in the Project Navigator on the left. - For your main project, go to the targets that will require the Branch macOS SDK as a dependency and click on the + button under Frameworks, Libraries, and Embedded Content to add it.
2. Configure Info.plist
In this step you will add a URL Scheme to your app so macOS knows what schemes to associate with the app.
- First off start off by adding the URL types property inside your target’s Info.plist. Open the Info.plist file, click on the “+” button that shows up when you hover over “Information Property List” and add the “URL types” if it doesn’t exist.
- After you fully expand “URL types” add a “URL Schemes” property under “Item 0”.
- Provide a value for “Item 0” under “URL Schemes”. This will be the scheme your app will handle.
NOTE
If you want to edit the Info.plist as a XML document, right click on your Info.plist and open it as source code.
You can paste this snippet before the final </dict> tag. Remember to change YOUR-APP-SCHEME-HERE to the app scheme for your app.
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLSchemes</key>
<array>
<string>YOUR-APP-SCHEME-HERE</string>
</array>
</dict>
</array>
If you wish to use Universal Links with a custom link domain, add branch_universal_link_domains with your live key domain. This is only necessary if you do not use the default app.link domain.
Here's a sample xml with the custom domain.
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLSchemes</key>
<array>
<string>YOUR-APP-SCHEME-HERE</string>
</array>
<key>branch_universal_link_domains</key>
<array>
<string>YOUR-CUSTOM-APP-LINK-DOMAIN</string>
</array>
</dict>
</array>
First Scheme Defined
Your app's URI scheme must be the first scheme defined (item 0) in the list.
The Branch SDK will use the first URI Scheme from your list that does not start with fb, db, twitterkit-, pin, or com.googleusercontent.apps. These schemes are ignored by Branch since they are commonly used by other app kits for oauth and other uses.
3. Configure macOS Universal Links
macOS Universal Links are not supported on Chrome or Firefox.
When opening a Branch link on these browsers, we will redirect to an URI to open the native app.
Universal Links are available on macOS Catalina or newer. When configured, Branch links clicked from Safari or a WebKit web view can open the native app without a URI redirect.
a. Configure Associated Domains
- Add your link domains from your Branch Dashboard.
- If you don't already have an Associated Domains section in the Signing & Capabilities tab for your target, go ahead and add it by clicking on the + sign.
- Add the associated domains from your Branch Dashboard.
NOTE
-alternateis needed to ensure proper functioning of Universal Links & Deep Views for users that do not have your app installed.test-is needed if you need to use a test key.
If you use a custom link domain, you will need to include your old link domain, your
-alternatelink domain, and your new link domain
b. Check Entitlements
- Confirm entitlements are within target (This file is configured automatically when completing the steps above in Capabilities tab of Xcode)
c. Configure AppDelegate to handle Universal Links
func application(_ application: NSApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([NSUserActivityRestoring]) -> Void) -> Bool {
Branch.sharedInstance.continue(userActivity)
return true
}
- (BOOL)application:(NSApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<NSUserActivityRestoring>> * _Nonnull))restorationHandler {
[[Branch sharedInstance] continueUserActivity:userActivity];
return YES;
}
4. Initialize Branch
The Branch SDK requires Outgoing Connections from your macOS application. Make sure your application has permissions to do so by going to the targets that your application uses and enable Outgoing Connections (Client) in the Signing & Capabilities tab.
Start Branch when your app first starts up. In your app delegate, make sure to first import the Branch SDK. Then, start Branch in your applicationDidFinishLaunching: method:
func applicationDidFinishLaunching(_ aNotification: Notification) {
// Register for Branch URL notifications
NotificationCenter.default.addObserver(self, selector: #selector(branchWillStartSession), name: .BranchWillStartSession, object: nil)
NotificationCenter.default.addObserver(self, selector: #selector(branchDidStartSession), name: .BranchDidStartSession, object: nil)
NotificationCenter.default.addObserver(self, selector: #selector(branchOpenedURLNotification), name: .BranchDidOpenURLWithSession, object: nil)
// Create a Branch configuration object with your key:
let configuration = BranchConfiguration(key: "YOUR_KEY_HERE")
// Start Branch:
Branch.sharedInstance.start(with: configuration)
}
#import <Branch/Branch.h>
// In your app delegate class file add this method to start the Branch SDK:
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
// Insert code here to initialize your application
// Register for Branch URL notifications:
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(branchWillStartSession:) name:BranchWillStartSessionNotification object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(branchDidStartSession:) name:BranchDidStartSessionNotification object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(branchOpenedURLNotification:) name:BranchDidOpenURLWithSessionNotification object:nil];
// Create a Branch configuration object with your key:
BranchConfiguration *configuration = [[BranchConfiguration alloc] initWithKey:@"key_live_joQf7gfRz1vebNOoHPFGJhnhFCarsZg0"];
// Start Branch:
[[Branch sharedInstance] startWithConfiguration:configuration];
}
Next up add the notification handlers which are used by the observers in the applicationDidFinishLaunching: method:
@objc private func branchWillStartSession(_ notification: Notification?) {
guard let notification = notification else { return }
let url = notification.userInfo?[BranchURLKey] ?? "N/A"
print("branchWillStartSession: \(notification.name) URL: \(url)")
}
@objc private func branchDidStartSession(_ notification: Notification?) {
guard let notification = notification else { return }
let url = notification.userInfo?[BranchURLKey] ?? "N/A"
let session = notification.userInfo?[BranchSessionKey] as? BranchSession
let data = (session != nil && session?.data != nil) ? session?.data?.description ?? "" : ""
print("branchDidStartSession: \(notification.name) URL: \(url) Data: \(data)")
}
@objc private func branchOpenedURLNotification(_ notification: Notification?) {
guard let notification = notification else { return }
let url = notification.userInfo?[BranchURLKey] ?? "N/A"
print("branchOpenedURLNotification: \(notification.name) URL: \(url)")
let session = notification.userInfo?[BranchSessionKey] as? BranchSession
let linkContent = session?.linkContent
displayLinkContent(linkContent)
}
private func displayLinkContent(_ linkContent: BranchUniversalObject?) {
guard let linkContent = linkContent,
let viewController = NSApplication.shared.keyWindow?.contentViewController as? ViewController
else {
return
}
viewController.updateContent(title: linkContent.title, contentDescription: linkContent.contentDescription, imageURLString: linkContent.imageUrl)
}
- (void) branchWillStartSession:(NSNotification*)notification {
NSLog(@"branchWillStartSession: %@", notification.name);
NSString *url = notification.userInfo[BranchURLKey] ?: @"";
NSLog(@"URL: %@", url);
}
- (void) branchDidStartSession:(NSNotification*)notification {
NSLog(@"branchDidStartSession: %@", notification.name);
NSString *url = notification.userInfo[BranchURLKey] ?: @"";
NSLog(@"URL: %@", url);
BranchSession *session = notification.userInfo[BranchSessionKey];
NSString *data = (session && session.data) ? session.data.description : @"";
}
- (void) branchOpenedURLNotification:(NSNotification*)notification {
NSLog(@"branchOpenedURLNotification: %@", notification.name);
NSString *url = notification.userInfo[BranchURLKey] ?: @"";
NSLog(@"URL: %@", url);
BranchSession *session = notification.userInfo[BranchSessionKey];
// Do something with the link!
// In this contrived example we'll load a view controller that plays the song that was in the link:
SongViewController *viewController = [SongViewController loadController];
viewController.songTitle = branchSession.linkContent.title;
[viewController.window makeKeyAndOrderFront:self];
[viewController playSong];
}
Updated over 1 year ago