Custom Integration

Overview

Custom integration refers to using the TradeItSDK.linkedBrokerManager object as a programmatic workflow upon which you can build your own workflow and screens or use the user's raw balance/positions data in your app. The linkedBrokerManager can be used to link/relink/unlink a user's broker logins. It holds the list of linked brokers in TradeItSDK.linkedBrokerManager.linkedBrokers. Each of these TradeItLinkedBroker objects can be used to authenticate an active session with the broker. Once this has been done, the list of trading accounts associated with the linked broker are stored in linkedBroker.accounts. Each of these TradeItLinkedBrokerAccount objects can be used to trade and retrieve balances and positions. See below for further details and explicit code examples.

Error handling

Any methods which have an error/failure callback will return a TradeItErrorResult object that has an error code errorCode enum property. These codes, and how to handle them, are detailed here: https://www.trade.it/documentation/api#ErrorHandling

Linking a user's broker

Brokers are linked using an OAuth flow to ensure security and privacy. Linked brokers are persisted by the SDK between app launches so should only need to be linked once unless the OAuth token expires or becomes invalidated or the user reinstalls the app. To use a linked broker for TradeIt functionality the linked broker must be authenticated to obtain a valid session.

Getting the list of available brokers

The list of brokers available for use in your app is determined by your API key, and can also change due to intermittent service interruptions so it is important to retrieve a fresh list of available brokers when presenting the choice to users.

TradeItSDK.linkedBrokerManager.getAvailableBrokers(
    onSuccess: { availableBrokers in
        if let firstBroker = availableBrokers.first {
            firstBroker.brokerShortName // Use this string to indicate choice of broker to the SDK/API when linking or requesting the OAuth URL
            firstBroker.brokerLongName // Use this string to display in the UI
        }
    }

Launching OAuth

After initializing TradeItSDK, use the linkedBrokerManager instance to get the URL for the OAuth login popup. The oAuthCallbackUrl should be a deep link back into your app and will be used to pass the OAuthVerifier token back into the app. On success, launch the resulting URL in the system browser or a UIWebView/SFSafariViewController and the user will be presented with an OAuth login page.

TradeItSDK.linkedBrokerManager.getOAuthLoginPopupUrl(
    withBroker: "dummy",
    oAuthCallbackUrl: "yourAppScheme://completeOAuth",
    onSuccess: { url in
        // Do this OR load URL in a UIWebView/SFSafariViewController
        UIApplication.shared.openURL(NSURL(string:url) as! URL)
    }, onFailure: { errorResult in
        AlertManager().showError(errorResult,
                                 onViewController: self)
    }
)

If the user needs to relink an already linked broker in order to update the OAuth token (the OAuth token has expired or become invalidated) then use this method instead of the above:

TradeItSDK.linkedBrokerManager.getOAuthLoginPopupForTokenUpdateUrl(
    forLinkedBroker: linkedBroker, // The linked broker that needs to be relinked
    onSuccess: { url in
        // Do this OR load URL in a UIWebView/SFSafariViewController
        UIApplication.shared.openURL(NSURL(string:url) as! URL)
    }, onFailure: { errorResult in
        AlertManager().showError(
            errorResult,
            onViewController: self
        )
    }
)

OAuth Completion

A successful OAuth login results in the browser redirecting to the provided callback with an appended query string including the oAuthVerifier. Example:

tradeItExampleApp://completeOAuth?oAuthVerifier=123-456-789-000

This should be set up to deep link back into your app. If you already have deep linking in your app, make sure to use a unique host/path for the Trade.it OAuth flow. Deep linking is handled in AppDelegate. Intercept the deep link and extract the OAuth verifier token from the deep link URL and pass it in to the SDK to complete linking:

TradeItSDK.linkedBrokerManager.completeOAuth(
    withOAuthVerifier: oAuthVerifier,
    onSuccess: { linkedBroker in
        print("=====> OAuth successful for \(linkedBroker.brokerName)!")
    },
    onFailure: { errorResult in
        print("=====> ERROR: OAuth failed! \(errorResult.errorCode): \(errorResult.shortMessage): \(errorResult.longMessages?.first)")
    }
)

Authenticating a linked broker

Authenticating a linked broker creates a temporary session (~30 minutes) with the broker that allows for all other actions to be taken, such as trading and retrieving portfolio information.

linkedBroker.authenticateIfNeeded(
    onSuccess: {},
    onSecurityQuestion: { securityQuestion, answerSecurityQuestion, cancelQuestion in
        // Manually prompt the user for an answer and then submit it to finish authenticating
        answerSecurityQuestion("answer")

        // OR use the provided alert manager
        self.alertManager.promptUserToAnswerSecurityQuestion(
            securityQuestion,
            onViewController: self,
            onAnswerSecurityQuestion: answerSecurityQuestion,
            onCancelSecurityQuestion: cancelQuestion)
    }, onFailure: { (errorResult) in
        // handle error
})

Authenticating all accounts

This can be used when the app starts up and none of the linked brokers have a valid session yet. NOTE: This method does not have a callback for authentication errors. If a linked broker could not be authenticated, the linkedBroker.error property will be set.

TradeItSDK.linkedBrokerManager.authenticateAll(onSecurityQuestion: { securityQuestion, answerSecurityQuestion in
    // Manually prompt the user for an answer and then submit it to finish authenticating
    answerSecurityQuestion(/* answer from user */)
    
    // OR use the provided alert manager
    self.alertManager.promptUserToAnswerSecurityQuestion(
        securityQuestion,
        onViewController: self,
        onAnswerSecurityQuestion: answerSecurityQuestion,
        onCancelSecurityQuestion: cancelQuestion)
}, onFinished: {
    // Brokers that did not successfully authenticate will have the TradeItErrorResult error property set: linkedBroker.error?
    print("\(TradeItSDK.linkedBrokerManager.linkedBrokers.map { $0.error == nil }.count) brokers authenticated.")
})

Fetching portfolio and account data

// Account balances - given an authenticated broker account
linkedBrokerAccount.getAccountOverview(onSuccess: {
    print(linkedBrokerAccount.balance)
}, onFailure: { errorResult in
    print(errorResult)
})

// Account positions - given an authenticated broker account
linkedBrokerAccount.getPositions(onSuccess: { positions in
    print(positions.map({ position in
        return position.position
    }))
}, onFailure: { errorResult in
    print(errorResult)
})

Trading

// Trading - given an authenticated broker account
let order = TradeItOrder()
order.linkedBrokerAccount = linkedBrokerAccount
order.symbol = "CMG"
order.action = .buy
order.type = .limit
order.expiration = .goodUntilCanceled
quantity = 100.0
limitPrice = 395.65

order.preview(onSuccess: { previewOrder, placeOrderCallback in
    // Display previewOrder contents to user for review
    // When the user confirms, call the placeOrderCallback to place the trade
    placeOrderCallback({ result in
        // Display result contents to the user
    }, { errorResult in
        // Display errorResult contents to user
    })
}, onFailure: { errorResult in
    // Display errorResult contents to user
})

Manual Initialization

The SDK automatically persists linked brokers locally on the device between usages of your app. However, it is also possible to manually initialize linked brokers and the associated accounts if you have persisted the data elsewhere remotely. This can be used to sync a user's linked accounts between instances of the app on other devices/platforms without the user having to relink.

First, capture and persist the necessary data when a new broker is linked:

class MyViewController: UIViewController, TradeItOAuthDelegate {
    override func viewDidLoad() {
        TradeItSDK.linkedBrokerManager.oAuthDelegate = self
    }

    func didLink(linkedBroker: TradeItLinkedBroker, userId: String, userToken: String) {
        linkedBroker.authenticate(
            onSuccess: {
                // Remotely persist the following data:
                //     userId
                //     userToken
                //     linkedBroker.brokerName
                //     linkedBroker.brokerLongName
                //     linkedBroker.accounts.map { return ($0.accountName, $0.accountNumber, $0.baseCurrency, $0.userCanDisableMargin) }
            },
            onSecurityQuestion: { (securityQuestion, answerSecurityQuestion, cancel) in
                // handle security question
            },
            onFailure: { errorResult in
                // handle failure
            }
        )
    }
}

If you want you can also fetch and store account balances and positions after you authenticate.

Then, later when the app is relaunched, you can sync/load from the remotely persisted data. The SDK loads locally persisted linked brokers from the device when it is configured so make sure any manual intervention is done after configuring the SDK via the call to TradeItSDK.configure().

Sync linked brokers/accounts from remotely persisted data:

let remoteBrokersToSync = [
            LinkedBrokerData( 
                userId: "userId", // persisted data
                userToken: "userToken", // persisted data
                broker: "broker", // persisted data
                brokerLongName: "broker long name", // persisted data
                accounts: [
                   LinkedBrokerAccountData(
                     name: "account name",  // persisted data
                     number: "account number",  // persisted data
                     baseCurrency: "USD",  // persisted data
                     userCanDisableMargin: false // persisted data
                   )
                ]
            )
        ]
        TradeItSDK.linkedBrokerManager.syncLocal(
            withRemoteLinkedBrokers: remoteBrokersToSync,
            onFailure: { errorResult in
                print("=====> Failed to sync linked brokers manually: \(String(describing: errorResult.shortMessage)) - \(String(describing: errorResult.longMessages?.first))")
            },
            onFinished: {
                print("=====> MANUALLY SYNC LINKED BROKERS!")
                TradeItSDK.linkedBrokerManager.linkedBrokers.forEach {
                    // do something
                }
                TradeItSDK.linkedBrokerManager.printLinkedBrokers()
            }
        )