Branch

@interface Branch : NSObject

The Branch class is the main class for interacting with Branch services.

  • Returns a pointer to the shared Branch instance.

    Declaration

    Objective-C

    @property (readonly, strong, atomic, class) Branch *_Nonnull sharedInstance;

    Swift

    class var sharedInstance: Branch { get }
    Show on GitHub

  • Returns the bundle identifier of the Branch framework.

    Declaration

    Objective-C

    @property (readonly, strong, atomic, class) NSString *_Nonnull bundleIdentifier;

    Swift

    class var bundleIdentifier: String { get }
    Show on GitHub

  • Returns the display version number of the Branch framework.

    Declaration

    Objective-C

    @property (readonly, strong, atomic, class) NSString *_Nonnull kitDisplayVersion;

    Swift

    class var kitDisplayVersion: String { get }
    Show on GitHub

  • Declaration

    Objective-C

    - (nonnull Branch *)startWithConfiguration:
    (nonnull BranchConfiguration *)configuration;

    Swift

    func start(with configuration: BranchConfiguration) -> Branch

    Parameters

    configuration

    Pass the configuration parameters for your app.

    Return Value

    Returns a pointer to the receiver.

    Show on GitHub

  • Returns true if the Branch SDK has been started.

    Declaration

    Objective-C

    @property (readonly, assign, atomic) BOOL isStarted;

    Swift

    var isStarted: Bool { get }
    Show on GitHub

  • Returns true if the passed URL is a URL that will be handled by Branch.

    Declaration

    Objective-C

    - (BOOL)isBranchURL:(NSURL *_Nullable)url;

    Swift

    func isBranch(_ url: URL?) -> Bool
    Show on GitHub

  • Open a URL with Branch. This will start a new Branch session.

    Declaration

    Objective-C

    - (BOOL)openURL:(NSURL *_Nullable)url;

    Swift

    func open(_ url: URL?) -> Bool

    Parameters

    url

    The URL to open.

    Return Value

    Returns true if it is a Branch link and an attempt will be made to open the link.

    Show on GitHub

  • Open a URL with Branch.

    This should be called from an iOS or tvOS application delegate method - (BOOL) openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options;.

    Declaration

    Objective-C

    - (BOOL)openURL:(nonnull NSURL *)url
        options:(nonnull NSDictionary<NSString *, id> *)options;

    Swift

    func open(_ url: URL, options: [String : Any] = [:]) -> Bool

    Parameters

    url

    The URL passed by the OS.
    options

    The options passed by the OS.

    Return Value

    Returns true if Branch can handle this URL, false otherwise.

    Show on GitHub

  • Opens a URL that was passed in an app continuation.

    This should be called from your application’s delegate method

    - (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
  restorationHandler:(void (^)(NSArray *))restorationHandler

    so that Branch can handle the passed URL.

    Declaration

    Objective-C

    - (BOOL)continueUserActivity:(nonnull NSUserActivity *)userActivity;

    Swift

    func `continue`(_ userActivity: NSUserActivity) -> Bool

    Parameters

    userActivity

    The NSUserActivity that was passed to your application.

    Return Value

    Returns true if Branch can handle the passed URL, false otherwise.

    Show on GitHub

  • Set the user’s identity to an ID used by your system, so that it is identifiable by you elsewhere. Receive a completion callback, notifying you whether it succeeded or failed.

    Warning

    If you use the same ID between users on different sessions / devices, their actions will be merged.

    Warning

    This request is not removed from the queue upon failure – it will be retried until it succeeds. The callback will only ever be called once, though.

    Warning

    You should call logout before calling setIdentity: a second time.

    Declaration

    Objective-C

    - (void)setUserIdentity:(nonnull NSString *)userId
             completion:(void (^_Nullable)(BranchSession *_Nullable,
                                           NSError *_Nullable))completion;

    Swift

    func setUserIdentity(_ userId: String, completion: ((BranchSession?, Error?) -> Void)? = nil)

    Parameters

    userId

    The ID Branch should use to identify this user.
    completion

    The callback to be called once the request has completed (success or failure).
    Show on GitHub

  • Indicates whether or not this user has a custom identity specified for them. Note that this is independent of installs. If you call setIdentity, this device will have that identity associated with this user until logoutWithCompletion is called. This includes persisting through uninstalls, as we track device id.

    Declaration

    Objective-C

    @property (readonly, assign, atomic) BOOL userIdentityIsSet;

    Swift

    var userIdentityIsSet: Bool { get }
    Show on GitHub

  • Clear all of the current user’s session items.

    Warning

    If the request to logout fails, the session items will not be cleared.

    Declaration

    Objective-C

    - (void)logoutWithCompletion:(void (^_Nullable)(NSError *_Nullable))completion;

    Swift

    func logout(completion: ((Error?) -> Void)? = nil)

    Parameters

    completion

    An optional completion block that is called by Branch with the success or failure of the logout.
    Show on GitHub

  • Generates a Branch short URL that describes the content described in the Branch Universal Object and has the passed link properties.

    A short link will not be able to be generated if networking is not available. In that case create a long link, which is guaranteed to succeed, but can be very long.

    Declaration

    Objective-C

    - (void)
branchShortLinkWithContent:(nonnull BranchUniversalObject *)content
            linkProperties:(nonnull BranchLinkProperties *)linkProperties
                completion:(nonnull void (^)(NSURL *_Nullable,
                                             NSError *_Nullable))completion;

    Swift

    func branchShortLink(withContent content: BranchUniversalObject, linkProperties: BranchLinkProperties, completion: @escaping (URL?, Error?) -> Void)

    Parameters

    content

    The BranchUniversalObject that describes the URL content.
    linkProperties

    The link properties for the short link.
    completion

    The completion block that receives the short URL or an NSError if the operation fails.
    Show on GitHub

  • Generates a Branch long URL. This method is guaranteed to succeed and is synchronous.

    Declaration

    Objective-C

    - (nonnull NSURL *)
branchLongLinkWithContent:(nonnull BranchUniversalObject *)content
           linkProperties:(nonnull BranchLinkProperties *)linkProperties;

    Swift

    func branchLongLink(withContent content: BranchUniversalObject, linkProperties: BranchLinkProperties) -> URL

    Parameters

    content

    The BranchUniversalObject that describes the URL content.
    linkProperties

    The link properties for the short link.

    Return Value

    Returns a Branch URL that has the given properties.

    Show on GitHub

  • Key-value pairs to be included in the metadata on every request.

    Declaration

    Objective-C

    @property (readwrite, strong, atomic, null_resettable)
    NSMutableDictionary<NSString *, NSString *> *requestMetadataDictionary;

    Swift

    var requestMetadataDictionary: NSMutableDictionary! { get set }
    Show on GitHub

  • Disables the Branch SDK from tracking the user. This is useful for GDPR privacy compliance.

    When tracking is disabled, the Branch SDK will clear the Branch defaults of user identifying information and prevent Branch from making any Branch network calls that will track the user.

    Note that:

    • Opening Branch deep links with an explicit URL will work.
    • Deferred deep linking will not work.
    • Generating short links will not work and will return long links instead.
    • Sending user tracking events such as userCompletedAction, BranchCommerceEvents, and BranchEvents will fail.
    • User rewards and credits will not work.
    • Setting a user identity and logging a user identity out will not work.

    Declaration

    Objective-C

    @property (getter=userTrackingIsDisabled, assign, readwrite, atomic)
    BOOL userTrackingDisabled;

    Swift

    var userTrackingIsDisabled: Bool { get set }
    Show on GitHub

  • Enables logging to the console for debugging. Should be set to NO for production apps.

    Declaration

    Objective-C

    @property (getter=loggingIsEnabled, assign, readwrite, atomic, class)
    BOOL loggingEnabled;

    Swift

    class var loggingIsEnabled: Bool { get set }
    Show on GitHub

  • If you are tracking users through Facebook installs and events well as with Branch, setting this property to true limits the amount of user data that is synchronized with Facebook for this user.

    Declaration

    Objective-C

    @property (assign, readwrite, atomic) BOOL limitFacebookTracking;

    Swift

    var limitFacebookTracking: Bool { get set }
    Show on GitHub

  • Sets the BranchDelegate object if you want to track Branch events with delegate methods.

    See

    Declaration

    Objective-C

    @property (readwrite, atomic) id<BranchDelegate> _Nullable delegate;

    Swift

    weak var delegate: BranchDelegate? { get set }
    Show on GitHub

  • Set the sessionStartedBlock with a call back block if you want to be notified of start of Branch sessions though a block call back.

    Declaration

    Objective-C

    @property (readwrite, copy, atomic) void (^_Nullable)
    (BranchSession *_Nullable, NSError *_Nullable) sessionStartedBlock;

    Swift

    var sessionStartedBlock: ((BranchSession?, Error?) -> Void)? { get set }
    Show on GitHub

BranchEvent