Link iOS SDK

Overview

The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid from within your iOS app. LinkKit is a drop-in framework that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc.) without passing sensitive information to your server.

To get started with Plaid Link for iOS, clone the GitHub repository and try out the example application, which provides a reference implementation in both Swift and Objective-C. Youʼll want to sign up for free API keys through the Plaid Dashboard to get started.

Initial iOS setup

Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project.

1. Sign in to the Plaid Dashboard and go to the Team Settings -> API page.
2. Next to Allowed redirect URIs click Configure then Add New URI.
3. Enter your redirect URI, which you must also set up as a Universal Link for your application, for example: https://app.example.com/plaid/.
4. Click Save Changes.

These redirect URIs must be set up as Universal Links in your application. For details, see Apple's documentation on Allowing Apps and Websites to Link to Your Content.

In order for Plaid to return control back to your application after a user completes a bank's OAuth flow, you must specify a redirect URI, which will be the URI from which Link will be re-launched to complete the OAuth flow. The redirect URI must be a Universal Link. An example of a typical redirect URI is: https://app.example.com/plaid.

Universal Links consist of the following parts:

• An applinks entitlement for the Associated Domains capability in your app. For details, see Apple’s documentation on the Associated Domains Entitlement and the entitlements example in the LinkDemo-Swift example app.
• An apple-app-site-association file on your website. For details, see Apple’s documentation on Supporting Associated Domains and see our minimal example below.

There are a few requirements for apple-app-site-association files:

• Must be a static JSON file
• Must be hosted using a https:// scheme with a valid certificate and no redirects
• Must be hosted at https://<my-fully-qualified-domain>/.well-known/apple-app-site-association

Below is an example for https://my-app.com (https://my-app.com/.well-known/apple-app-site-association)

{
  "applinks": {
    "details": [
      {
        "appIDs": ["<My Application Identifier Prefix>.<My Bundle ID>"],
        "components": [
          {
            "/": "/plaid/*",
            "comment": "Matches any URL path whose path starts with /plaid/"
          }
        ]
      }
    ]
  }
}

Once you have enabled Universal Links, your iOS app is now set up and ready to start integrating with the Plaid SDK.

Installation

Plaid Link for iOS is an embeddable framework that is bundled and distributed with your application. There are several ways to obtain the necessary files and keep them up-to-date; we recommend using Swift Package Manager or CocoaPods. Regardless of what you choose, submitting a new version of your application with the updated LinkKit.xcframework to the App Store is required.

Manual

Get the latest version of the LinkKit.xcframework and embed it into your application, for example by dragging and dropping the XCFramework bundle onto the Embed Frameworks build phase of your application target in Xcode as shown below.

New versions of LinkKit.xcframework are released frequently. Major releases occur annually. The Link SDK uses Semantic Versioning, ensuring that all non-major releases are non-breaking, backwards-compatible updates. We recommend you update regularly (at least once a quarter, and ideally once a month) to ensure the best Plaid Link experience in your application.

SDK versions are supported for two years; with each major SDK release, Plaid will stop officially supporting any previous SDK versions that are more than two years old. While these older versions are expected to continue to work without disruption, Plaid will not provide assistance with unsupported SDK versions.

For details on each release see the GitHub releases and version release notes.

Before you can open Link, you need to first create a link_token. A link_token can be configured for different Link flows and is used to control much of Link’s behavior. To learn how to create a new link_token, see the API Reference entry for /link/token/create.

var linkConfiguration = LinkTokenConfiguration(
    token: "<#LINK_TOKEN_FROM_SERVER#>",
    onSuccess: { linkSuccess in
        // Send the linkSuccess.publicToken to your app server.
    }
)

// Optional: Configure additional Link presentation options. 

// If true, skips the default Link loading animation.
// Use this if you're displaying your own custom loading UI.
linkConfiguration.noLoadingState = true

// Optional: Configure additional Link presentation options -
// Available in SDK v6.2.0 and above:

// If false, displays a solid background instead of the default
// transparent gradient.
linkConfiguration.showGradientBackground = false

A Handler is a one-time use object used to open a Link session. The Handler must be retained for the duration of the Plaid SDK flow. It will also be needed to respond to OAuth Universal Link redirects. For more details, see the OAuth guide.

You can optionally provide an onLoad (available in SDK v6.2.0 and above) callback to know when Link has finished preloading and is ready to be presented. This is useful if you want to delay presenting Link until it’s fully loaded, or enable related UI elements.

let result = Plaid.create(configuration, onLoad: { [weak self] in
    // Optional callback that is invoked once Plaid Link has
    // finished loading and is ready to be presented.
    // You could use your own loading UI and automatically
    // launch Link when this callback fires.
    //
    // Ex:
    //    guard let self = self else { return }
    //    self.handler?.open(presentUsing: .viewController(self))
    //

    // Ex: Enable a button once Link has loaded
    //    self?.openButton.isEnabled = true
})

switch result {
case .failure(let error):
    logger.error("Unable to create Plaid handler due to: \(error)")
case .success(let handler):
    self.handler = handler
}

Finally, open Link by calling open on the Handler object. This will usually be done in a button’s target action.

let method: PresentationMethod = .viewController(self)
handler.open(presentUsing: method)

onSuccess: { linkSuccess in
  // Send the linkSuccess.publicToken to your app server.
}

linkConfiguration.onExit = { linkExit in
  // Optionally handle linkExit data according to your application's needs
}

linkConfiguration.onEvent = { linkEvent in
  // Optionally handle linkEvent data according to your application's needs
}

// Create a model that conforms to the SubmissionData interface
struct PlaidSubmitData: SubmissionData {
    var phoneNumber: String?
}

let data = PlaidSubmitData(phoneNumber: "14155550015")

self.handler.submit(data)

Once you've gotten Link working, see Link best practices for recommendations on further improving the Link flow.