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.
1// Setup using shared configuration,2PLKPlaidLink.setup { (success, error) in /* … */ }34// using shared configuration and item-add token5PLKPlaidLink.setupWithSharedConfiguration(usingItemAddToken:itemAddToken) { (success, error) in /* … */ }67// using custom configuration,8PLKPlaidLink.setup(with: linkConfiguration) { (success, error) in /* … */ }910// using custom configuration and item-add token,11PLKPlaidLink.setupWithConfiguration(with: linkConfiguration, itemAddToken: itemAddToken)12 { (success, error) in /* … */ }1314// using public-token and shared configuration15PLKPlaidLink.setup(withPublicToken:publicToken) { (success, error) in /* … */ }1617// using public-token and custom configuration18PLKPlaidLink.setup(withPublicToken:publicToken, configuration:linkConfiguration) { (success, error) in /* … */ }1920// using public-token, item-add token, and shared configuration21PLKPlaidLink.setup(withPublicToken:publicToken, itemAddToken:itemAddToken) { (success, error) in /* … */ }2223// using public-token, item-add token, and custom configuration24PLKPlaidLink.setup(withPublicToken:publicToken, itemAddToken:itemAddToken, configuration:linkConfiguration)25 { (success, error) in /* … */ }2627// using public-token, link-token, and shared configuration28PLKPlaidLink.setup(withPublicToken:publicToken, linkToken:linkToken) { (success, error) in /* … */ }2930// using public-token, link-token, and custom configuration31PLKPlaidLink.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.
1// For recommended Link Token based configuration use:2let linkTokenConfiguration = LinkTokenConfiguration(token: linkToken)3 { success in /* … */ }45// 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.
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 start6 self.handler = handler7}
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:
1present(linkViewController, animated: true)
Instead call open
on the Handler
you created, specifying your preferred method of presentation:
1// Let the handler present Link using one of the application's view controllers.2handler.open(presentUsing: .viewController(self))34// 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 method | 2.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
receivesLinkSuccess
, which contains thepublicToken
andmetadata
specific toLinkSuccess
OnExitHandler
receivesLinkExit
, which contains an optionalerror
andmetadata
specific toLinkExit
OnEventHandler
receivesLinkEvent
, which contains theeventName
andmetadata
specific toLinkEvent
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 constant | 2.x SuccessMetadata property |
---|---|
kPLKMetadataInstitutionKey | institution |
kPLKMetadataInstitutionIdKey | institution.id |
kPLKMetadataInstitutionNameKey | institution.name |
kPLKMetadataAccountsKey | accounts ; see mapping below |
kPLKMetadataLinkSessionIdKey | linkSessionID |
N/A | metadataJSON |
1.x account key constant | 2.x Account property |
---|---|
kPLKMetadataIdKey | id |
kPLKMetadataNameKey | name |
kPLKMetadataMaskKey | mask |
kPLKMetadataTypeKey | N/A; The account type is now encoded within the subtype |
kPLKMetadataSubtypeKey | subtype |
kPLKMetadataAccountVerificationStatusKey | verificationStatus |
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 constant | 2.x ExitMetadata property |
---|---|
kPLKMetadataErrorCodeKey | error.errorCode ; note that error code and error type are combined in a single Swift enum |
kPLKMetadataErrorTypeKey | see above |
kPLKMetadataErrorMessageKey | error.errorMessage |
N/A | error.displayMessage |
kPLKMetadataStatusKey | exitStatus |
kPLKMetadataLinkSessionIdKey | linkSessionID |
kPLKMetadataInstitutionIdKey | institutionID |
kPLKMetadataInstitutionNameKey | institutionName |
kPLKMetadataInstitutionSearchQueryKey | institutionSearchQuery |
kPLKMetadataLinkSessionIdKey | linkSessionID |
kPLKMetadataMFATypeKey | mfaType |
kPLKMetadataTimestampKey | timestamp |
kPLKMetadataViewNameKey | viewName |
N/A | metadataJSON |
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 constant | 2.x ExitMetadata property |
---|---|
kPLKMetadataInstitutionKey | status |
kPLKMetadataInstitutionIdKey | institution.id |
kPLKMetadataInstitutionNameKey | institution.name |
kPLKMetadataLinkSessionIdKey | linkSessionID |
kPLKMetadataRequestIdKey | requestID |
N/A | metadataJSON |
Every metadata now includes a metadataJSON
property which contains unprocessed metadata from the Plaid API.
1let onSuccessHandler: OnSuccessHandler = { (success) in2 // Send success.publicToken to your server and exchange it for an access token3 // Process any metadata according to your needs, e.g. metadata.institution.name4}5// Pass onSuccessHandler to the onSuccess parameter of the LinkTokenConfiguration or LinkPublicKeyConfiguration initializer
1let onExitHandler: OnExitHandler = { (exit) in2 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.name12}13linkConfiguration.onExit = onExitHandler
1let onEventHandler: OnEventHandler = { (event) in2 // Handle events and metadata according to your app.3 let metadata = event.metadata4 switch event.eventName {5 case .selectInstitution:6 // Process any metadata according to your needs, e.g. metadata.institutionName7 print("Selected institution \(metadata.institutionName ?? "") (\(metadata.institutionID ?? "")")8 default:9 print("Ignored event \(event)")10 }11}12linkConfiguration.onEvent = onEventHandler