Plaid logo
Docs
ALL DOCS

Link

  • Overview
Libraries
  • Web
  • iOS
  • Android
  • React Native
  • Webview
Core Link flows
  • OAuth guide
  • Update mode
  • Preventing duplicate Items
  • Data Transparency Messaging migration
  • Account Select v2 migration guide
  • Link Token migration guide
  • Legacy public key integrations
Optimizing Link
  • Optimizing Link conversion
  • Measuring Link conversion
  • Pre-Link messaging
  • Customizing Link
  • Choosing when to inititalize products
  • Returning user experience
  • Modular Link (UK/EU only)
Errors and troubleshooting
  • Troubleshooting
  • Handling an invalid Link Token
  • Institution status in Link
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

1.x to 2.x Migration Guide

Reference for migrating the Link iOS SDK from 1.x to 2.x

Summary of changes

Plaid released version 2.0.0 of the SDK on September 24th, 2020. Upgrading to the new 2.x SDK allows you to take advantage of a unified mobile API and support all new features, such as link-token based Payment Initiation. This guide describes how to upgrade a Plaid iOS integration from the 1.x SDK to the 2.x SDK.

Remove the custom "Prepare for distribution" Build Phase

LinkKit 2.x is now an XCFramework bundle type, which no longer requires the custom Build Phase to strip the iOS Simulator part from the framework.

Remove setup

Remove any of the preflight setup methods listed below that your application may make use of. They are no longer part of the API and need to be removed.

Select Language
Copy
1// Setup using shared configuration,
2PLKPlaidLink.setup { (success, error) in /* … */ }
3
4// using shared configuration and item-add token
5PLKPlaidLink.setupWithSharedConfiguration(usingItemAddToken:itemAddToken) { (success, error) in /* … */ }
6
7// using custom configuration,
8PLKPlaidLink.setup(with: linkConfiguration) { (success, error) in /* … */ }
9
10// using custom configuration and item-add token,
11PLKPlaidLink.setupWithConfiguration(with: linkConfiguration, itemAddToken: itemAddToken)
12 { (success, error) in /* … */ }
13
14// using public-token and shared configuration
15PLKPlaidLink.setup(withPublicToken:publicToken) { (success, error) in /* … */ }
16
17// using public-token and custom configuration
18PLKPlaidLink.setup(withPublicToken:publicToken, configuration:linkConfiguration) { (success, error) in /* … */ }
19
20// using public-token, item-add token, and shared configuration
21PLKPlaidLink.setup(withPublicToken:publicToken, itemAddToken:itemAddToken) { (success, error) in /* … */ }
22
23// using public-token, item-add token, and custom configuration
24PLKPlaidLink.setup(withPublicToken:publicToken, itemAddToken:itemAddToken, configuration:linkConfiguration)
25 { (success, error) in /* … */ }
26
27// using public-token, link-token, and shared configuration
28PLKPlaidLink.setup(withPublicToken:publicToken, linkToken:linkToken) { (success, error) in /* … */ }
29
30// using public-token, link-token, and custom configuration
31PLKPlaidLink.setup(withPublicToken:publicToken, linkToken:linkToken, configuration:linkConfiguration)
32 { (success, error) in /* … */ }

Create a configuration

The recommended way to create a configuration for Link is to use LinkTokenConfiguration, which replaces PLKConfiguration. If you still rely on public key based configurations, we recommend you migrate your application to use Link tokens as soon as possible, and use LinkPublicKeyConfiguration until then.

Select Language
Copy
1// For recommended Link Token based configuration use:
2let linkTokenConfiguration = LinkTokenConfiguration(token: linkToken)
3 { success in /* … */ }
4
5// To continue using public key based configuration for the interim use:
6let linkPublicKeyConfiguration = LinkPublicKeyConfiguration(
7 clientName: "Link Demo",
8 environment: .sandbox,
9 products: [.transactions, .auth],
10 language: "en"
11 token: .publicKey("<#YOUR_PUBLIC_KEY#>"),
12 countryCodes: ["US"]) { (success) in /* … */ }

Notice that the PLKPlaidLinkViewDelegate has been replaced by the required onSuccess closure on LinkTokenConfiguration and LinkPublicKeyConfiguration and the optional onExit and onEvent closures.

Handler

A Handler is a one-time use object used to open a Link session. Create it as early as possible in your application lifecycle or account linking setup. If delayed until just before opening Link it can have a perceptible impact on Link startup time.

Select Language
Copy
1switch Plaid.create(linkTokenConfiguration) {
2 case .failure(let error):
3 print("Unable to create Plaid Handler due to: \(error)")
4 case .success(let handler)
5 // Store the handler for later use and call open on it when Link should start
6 self.handler = handler
7}

Open Link

Since Handler is not a UIViewController and replaces the PLKPlaidLinkViewController, it is not possible to present it directly. Remove any calls to present Link:

Select Language
Copy
1present(linkViewController, animated: true)

Instead call open on the Handler you created, specifying your preferred method of presentation:

Select Language
Copy
1// Let the handler present Link using one of the application's view controllers.
2handler.open(presentUsing: .viewController(self))
3
4// or present Link yourself in a custom manner using a closure.
5handler.open(presentUsing: .custom({ (linkViewController) in /* … */ }))

Handling results

The PLKPlaidLinkViewDelegate methods have been replaced with closures passed to either LinkTokenConfiguration or LinkPublicKeyConfiguration. While OnExitHandler and OnEventHandler are optional, the OnSuccessHandler must be provided.

1.x PLKPlaidLinkViewDelegate method2.x Handler
linkViewController:didSucceedWithPublicToken:metadata:OnSuccessHandler
linkViewController:didExitWithError:metadata:OnExitHandler
linkViewController:didHandleEvent:metadata:OnEventHandler

Each 2.x Handler closure receives one specific parameter, containing the two equivalent variables for the parameters that the corresponding PLKPlaidLinkViewDelegate method received.

  • OnSuccessHandler receives LinkSuccess, which contains the publicToken and metadata specific to LinkSuccess
  • OnExitHandler receives LinkExit, which contains an optional error and metadata specific to LinkExit
  • OnEventHandler receives LinkEvent, which contains the eventName and metadata specific to LinkEvent
SuccessMetadata

Link SDK 1.x returned an untyped NSDictionary and provided constants for key names, e.g. kPLKMetadataInstitutionKey. The untyped dictionary has been replaced with the SuccessMetadata type containing success metadata specific properties.

1.x metadata key constant2.x SuccessMetadata property
kPLKMetadataInstitutionKeyinstitution
kPLKMetadataInstitutionIdKeyinstitution.id
kPLKMetadataInstitutionNameKeyinstitution.name
kPLKMetadataAccountsKeyaccounts; see mapping below
kPLKMetadataLinkSessionIdKeylinkSessionID
N/AmetadataJSON
1.x account key constant2.x Account property
kPLKMetadataIdKeyid
kPLKMetadataNameKeyname
kPLKMetadataMaskKeymask
kPLKMetadataTypeKeyN/A; The account type is now encoded within the subtype
kPLKMetadataSubtypeKeysubtype
kPLKMetadataAccountVerificationStatusKeyverificationStatus
ExitMetadata

Link SDK 1.x returned a untyped NSDictionary and provided constants for key names, e.g. kPLKMetadataRequestIdKey The untyped dictionary has been replaced with the ExitMetadata type containing exit metadata specific properties.

1.x key constant2.x ExitMetadata property
kPLKMetadataErrorCodeKeyerror.errorCode; note that error code and error type are combined in a single Swift enum
kPLKMetadataErrorTypeKeysee above
kPLKMetadataErrorMessageKeyerror.errorMessage
N/Aerror.displayMessage
kPLKMetadataStatusKeyexitStatus
kPLKMetadataLinkSessionIdKeylinkSessionID
kPLKMetadataInstitutionIdKeyinstitutionID
kPLKMetadataInstitutionNameKeyinstitutionName
kPLKMetadataInstitutionSearchQueryKeyinstitutionSearchQuery
kPLKMetadataLinkSessionIdKeylinkSessionID
kPLKMetadataMFATypeKeymfaType
kPLKMetadataTimestampKeytimestamp
kPLKMetadataViewNameKeyviewName
N/AmetadataJSON
EventMetadata

Link SDK 1.x returned a untyped NSDictionary and provided constants for key names, e.g. kPLKMetadataRequestIdKey The untyped dictionary has been replaced with the ExitMetadata type containing exit metadata specific properties.

1.x key constant2.x ExitMetadata property
kPLKMetadataInstitutionKeystatus
kPLKMetadataInstitutionIdKeyinstitution.id
kPLKMetadataInstitutionNameKeyinstitution.name
kPLKMetadataLinkSessionIdKeylinkSessionID
kPLKMetadataRequestIdKeyrequestID
N/AmetadataJSON

Every metadata now includes a metadataJSON property which contains unprocessed metadata from the Plaid API.

Select Language
Copy
1let onSuccessHandler: OnSuccessHandler = { (success) in
2 // Send success.publicToken to your server and exchange it for an access token
3 // Process any metadata according to your needs, e.g. metadata.institution.name
4}
5// Pass onSuccessHandler to the onSuccess parameter of the LinkTokenConfiguration or LinkPublicKeyConfiguration initializer
Select Language
Copy
1let onExitHandler: OnExitHandler = { (exit) in
2 if let error = exit.error {
3 // Handle errors according to your app.
4 switch error.errorCode {
5 case .rateLimitExceeded(let code):
6 print("Encountered rate limit \(code)")
7 default:
8 print("Unhandled error \(error.errorCode)")
9 }
10 }
11 // Process any metadata depending on your needs, e.g. exit.metadata.institution.name
12}
13linkConfiguration.onExit = onExitHandler
Select Language
Copy
1let onEventHandler: OnEventHandler = { (event) in
2 // Handle events and metadata according to your app.
3 let metadata = event.metadata
4 switch event.eventName {
5 case .selectInstitution:
6 // Process any metadata according to your needs, e.g. metadata.institutionName
7 print("Selected institution \(metadata.institutionName ?? "") (\(metadata.institutionID ?? "")")
8 default:
9 print("Ignored event \(event)")
10 }
11}
12linkConfiguration.onEvent = onEventHandler
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord