macOS Advanced Features

Turning on Logging

To help debugging your app, you can turn on Branch logging, which logs to the console. Remember to turn it off in your production app.

Property

Branch.loggingIsEnabled

Branch.loggingEnabled

Setting User Identities

Often, you might have your own user IDs, or want referral and event data to persist across platforms or uninstall/reinstall. It's helpful if you know your users access your service from different devices. This where we introduce the concept of an 'user identity'.

Method

private func login(userIdentity: String?) {
        guard let userIdentity = userIdentity else { return }

        Branch.sharedInstance.setUserIdentity(userIdentity,
                                              completion: { (branchSession, error) in
                                                // Do stuff with login
                                              })
    }

[Branch setUserIdentity:completion:]

See setUserIdentity:completion:

Get User Identity

Use the getUserIdentity method to retrieve the user ID set via setUserIdentity.

Method

var userIdentity = Branch.sharedInstance().getUserIdentity()

NSString *userIdentity = [Branch sharedInstance].getUserIdentity();

See getUserIdentity

Logout

If you provide a logout function in your app, be sure to clear the user when the logout completes. This will ensure that all the stored parameters get cleared and all events are properly attributed to the right identity.

🚧

Warning

This call will clear attribution on the device.

Method

private func logout() {
        Branch.sharedInstance.logout(completion: { (error) in
          // Do stuff on logout
        })
    }

[Branch logoutWithCompletion:]

See logoutWithCompletion:

Enable or Disable User Tracking

If you need to comply with a user's request to not be tracked for GDPR purposes, or otherwise determine that a user should not be tracked, utilize this field to prevent Branch from sending network requests. This setting can also be enabled across all users for a particular link, or across your Branch links.

Branch.sharedInstance().trackingDisabled = true

[Branch sharedInstance].trackingDisabled = YES;

You can choose to call this throughout the lifecycle of the app. Once called, network requests will not be sent from the SDKs. Link generation will continue to work, but will not contain identifying information about the user. In addition, deep linking will continue to work, but will not track analytics for the user.

Set Initialization Metadata

🚧

Data Integration Only

If you are using a 3rd Party Data Integration Partner that requires setting certain identifiers before initializing the Branch SDK, you should add this code snippet:

let dict = NSMutableDictionary()
        dict.setObject("your metadata" as NSString, forKey: "sample_key" as NSString)
        Branch.sharedInstance.requestMetadataDictionary = dict

NSMutableDictionary<NSString *, NSString *> *metadata = [NSMutableDictionary<NSString *, NSString *> new];
    [metadata setObject:@"your metadata" forKey:@"sample_key"];
    [[Branch sharedInstance] setRequestMetadataDictionary:metadata];

Branch Universal Objects

The Branch iOS SDK uses the concept of a Branch Universal Object (BUO) to represent the thing you want to share. A BranchUniversalObject instance encapsulates a unique piece of content, such as an article, video, or item for sale.

The BranchUniversalObject.contentMetadata properties further describe your content. These properties are trackable in the Branch dashboard and will be automatically exported to your connected third-party app intelligence partners like Adjust or Mixpanel.

Learn more about creating BUOs so that you can utilize deep linking, sharing content, content analytics, event tracking, and content indexing on Spotlight.

Track User Actions and Events

The BranchEvent class is used to make a Branch Event out of an event or action that has taken place in your app. Examples include tracking when a user adds an item to an online shopping cart or searches for a keyword.

You can associate a BUO with a Branch Event by adding the BUO instance to the Branch Event's contentItems field. You can also view analytics for your Branch Events on the Branch dashboard.

Learn more about the different classes of Branch Events, including the Custom class for tracking events that aren't predefined.

Shortened Links

Once you've created your Branch Universal Object, which is the reference to the content you're interested in, you can then get a link back to it with the mechanisms described below.

📘

Encoding Note

One quick note about encoding. Since NSJSONSerialization supports a limited set of classes, we do some custom encoding to allow additional types. Current supported types include NSDictionary, NSArray, NSURL, NSString, NSNumber, NSNull, and NSDate (encoded as an ISO8601 string with timezone). If a parameter is of an unknown type, it will be ignored.

Methods

let linkProperties: BranchLinkProperties = BranchLinkProperties()
linkProperties.feature = "sharing"
linkProperties.channel = "facebook"
linkProperties.addControlParam("$desktop_url", withValue: "http://example.com/home")
linkProperties.addControlParam("$ios_url", withValue: "http://example.com/ios")

branchUniversalObject.getShortUrl(with: linkProperties) { (url, error) in
    if error == nil {
        NSLog("got my Branch link to share: %@", url)
    }
}

#import "BranchLinkProperties.h"
  
BranchLinkProperties *linkProperties = [[BranchLinkProperties alloc] init];
linkProperties.feature = @"sharing";
linkProperties.channel = @"facebook";
[linkProperties addControlParam:@"$desktop_url" withValue:@"http://example.com/home"];
[linkProperties addControlParam:@"$ios_url" withValue:@"http://example.com/ios"];

[branchUniversalObject getShortUrlWithLinkProperties:linkProperties andCallback:^(NSString *url, NSError *error) {
    if (!error) {
        NSLog(@"success getting url! %@", url);
    }
}];

Link Properties Parameters

You can do custom redirection by inserting the following optional keys in the dictionary:

You have the ability to control the direct deep linking of each link by inserting the following optional keys in the dictionary:

Get Short Url Parameters

Create QR Code

• Create a BranchUniversalObject and BranchLinkProperties
• Create a BranchQRCode object and set the properties
• Use getQRCodeAsImage() or getQRCodeAsData() to create a QR code

BranchLinkProperties *linkProperties = [BranchLinkProperties new];
    BranchUniversalObject *buo = [BranchUniversalObject new];
    
    BranchQRCode *qrCode = [BranchQRCode new];
    qrCode.codeColor = [NSColor colorWithCalibratedRed:0.1 green:0.8392 blue:1.0 alpha:1.0f];
    qrCode.backgroundColor = NSColor.whiteColor;
    qrCode.width = @500;
    qrCode.margin = @1;
    qrCode.centerLogo = @"https://cdn.branch.io/branch-assets/1598575682753-og_image.png";
    qrCode.imageFormat = BranchQRCodeImageFormatPNG;
    
    [qrCode getQRCodeAsImage:buo linkProperties:linkProperties completion:^(CIImage * _Nullable qrCodeImage, NSError * _Nullable error) {
        //Use the QR code image here...
    }];