Link Embedded Institution Search

With Embedded Institution Search (beta), you can provide a more seamless transition to the account connectivity experience. For payment experiences in particular, embedding institution search can help guide users to choosing their bank account as a payment method.

Embedded Institution Search is currently in beta. To request access to the beta, contact your account manager.

The user will be able to select from a set of institution logos. You can customize which logos will be displayed via the Plaid Dashboard. If a user selects an institution, they will be taken to Link to connect their account.

If the user's institution is not one of the featured institutions, they can select "View more", which will take them to Link to search for their institution and then connect their account.

Embedded institution search is available for all supported integration modes except webviews.

Before integrating, make sure you are using a version of the SDK that supports Embedded Institution Search.

1. Create an embedded view If you are using iOS, call createEmbeddedView, which will return a Result containing a UIView. Once you have the UIView, add it to your ViewController's view.
   If you are using the web SDK, call Plaid.createEmbedded instead of Plaid.create to open Link. For other platforms, you will create the view as normal.
2. Update your integration to replace current Link with embedded institution search, then lay out the view Plaid returns from their configuration.

1private func setupEmbeddedSearchView(token: String) {
2
3        // Create a configuration like normal.
4        var configuration = LinkTokenConfiguration(
5            token: token,
6            onSuccess: { success in
7                print("success: \(success)")
8            }
9        )
10
11        configuration.onEvent = { event in
12            print("Event: \(event)")
13        }
14
15        configuration.onExit = { exit in
16            print("Exit: \(exit)")
17        }
18
19        // Create a handler with your configuration like normal.
20        let handlerResult = Plaid.create(configuration)
21        switch handlerResult {
22        case .success(let handler):
23
24            // Save a reference to your handler.
25            self.handler = handler
26
27            // Create an embedded view.
28            let viewResult = handler.createEmbeddedView(presentUsing: .viewController(self))
29
30            switch viewResult {
31            case .success(let embeddedSearchView):
32
33                // Layout this view
34                embeddedSearchView.translatesAutoresizingMaskIntoConstraints = false
35                view.addSubview(embeddedSearchView)
36
37                NSLayoutConstraint.activate([
38                    embeddedSearchView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 8),
39                    embeddedSearchView.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 25),
40                    embeddedSearchView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -25),
41                    embeddedSearchView.heightAnchor.constraint(equalToConstant: 360),
42                ])
43
44            case .failure(let error):
45                // You will only receive an error here if you're using public key authentication.
46                fatalError("\(error)")
47            }
48
49        case .failure(let error):
50            // Error creating handler. Handle like normal.
51            fatalError("\(error)")
52        }
53    }

1// Register a callback for an Activity Result like normal (must be done from an Activity)
2 private val linkAccountToPlaid =
3   registerForActivityResult(OpenPlaidLink()) { result ->
4      when (result) {
5        is LinkSuccess -> /* handle LinkSuccess */
6        is LinkExit -> /* handle LinkExit (from LinkActivity) */
7      }
8    }
9
10// Create a linkTokenConfiguration like normal 
11val linkTokenConfiguration = LinkTokenConfiguration.Builder().token(token).build()
12
13// Create the view with a trailing lambda for handling LinkExits from the Embedded View
14val embeddedView = Plaid.createLinkEmbeddedView(
15this /*Activity context*/,
16linkTokenConfiguration,
17linkAccountToPlaid) {
18exit: LinkExit -> /* handle LinkExit (from Embedded View) */
19  }
20)
21
22// Add this embeddedView to a view in your layout
23binding.embeddedViewContainer.addView(embeddedView)

1<div id="plaid-embedded-link-container"></div>

1// The container at `#plaid-embedded-link-container` will need to be sized in order to 
2// control the size of the embedded Plaid module
3const embeddedLinkOpenTarget = document.querySelector('#plaid-embedded-link-container');
4
5Plaid.createEmbedded(
6    {
7      token: 'GENERATED_LINK_TOKEN',
8      onSuccess: (public_token, metadata) => {},
9      onLoad: () => {},
10      onExit: (err, metadata) => {},
11      onEvent: (eventName, metadata) => {},
12    },
13    embeddedLinkOpenTarget,
14);

1import React, { useCallback } from 'react';
2import { PlaidEmbeddedLink } from 'react-plaid-link';
3
4const App = props => {
5  const onSuccess = useCallback(
6    (token, metadata) => console.log('onSuccess', token, metadata),
7    []
8  );
9
10  const onEvent = useCallback(
11    (eventName, metadata) => console.log('onEvent', eventName, metadata),
12    []
13  );
14
15  const onExit = useCallback(
16    (err, metadata) => console.log('onExit', err, metadata),
17    []
18  );
19
20  const config = {
21    token: "plaid-token-123",
22    onSuccess,
23    onEvent,
24    onExit,
25  };
26
27  return (
28    <PlaidEmbeddedLink
29      {...config}
30      style={{
31        height: '350px',
32        width: '350px',
33      }}
34    />
35  );
36};
37
38export default App;

You can customize the Embedded Institution Search user experience to match your application's needs.

The embedded Link module will responsively scale to display between six and fifteen institutions, depending on the height and width of the module.

Embedded Institution Search offers an optional, minimal layout that hides the "View More" button from the embedded module and only renders the institution tiles. In this layout, you should provide your own "View More" button below Plaid’s embedded Link module. To set up your own "View More" button, create a button to initialize Plaid Link normally, and place it below the embedded Link module.

To be activated for the optional tile-only minimal layout, contact your Account Manager.

The institutions displayed in Link Embedded Search are based on your Institution Select settings, which you can optionally customize in the Dashboard. For most customers, it is recommended to use the default settings.

Embedded Institution Search is compatible with the Institution Select Shortcut: If you already know which institution the user wants to connect to before initializing Link, you can pass routing_number into the institution_data request field in the /link/token/create endpoint. The matched institution will be listed first (top left position) in the embedded institution grid.

Initialize Link when you load the pane that Link is embedded in, where you typically place the "Link your bank" button to initialize Link, and remove this button. Create your embedded search view before it will be displayed in your app. This will reduce the latency for the embedded search view loading. You’ll create a view and place it on the screen instead of calling Open; Plaid will track when this view is requested and activate the Embedded Search UI.

On the web, the embedded Plaid module will attempt to use 100% of the height and width of its container. To modify the size of the Plaid module, or to render the Plaid module responsively, you should set the size of the container. We recommend 344 height and width 340 (min width 240).

If you participate in the beta, Plaid will ask you to provide feedback about your experience. In addition to qualitative feedback about ease of integration and usability, as well as any conversion metrics that may be specific to your user experience, we will ask you to collect certain client-side conversion metrics and share these with Plaid. The minimum set of metrics you will need to collect are:

• Start → onSuccess conversion percentage, where "Start" is defined as the user viewing the Embedded Institution Search UI
• Embedded Institution Search total impressions

As well as the following link events, along with the associated link_session_id:

• OPEN
• SELECT_INSTITUTION
• OAUTH_PANE
• CREDENTIAL_PANE
• ERROR_PANE
• HANDOFF

For details on how to capture Link events, see the onEvent documentation for your specific client platform: web, iOS, Android, or React Native.

If you’re activating an experiment with treatment and control conditions, pass in a link_customization_name in /link/token/create, Use link_customization_name: 'embedded_search_treatment' and link_customization_name: 'embedded_search_control' if you’d like Plaid to compare these two conditions for you. Plaid will otherwise compare metrics of all Embedded Institution Search sessions against all other non-embedded Link sessions.

If the user selects the View more button

• onEvent: OPEN – view_name: "SELECT_INSTITUTION"
• onEvent: TRANSITION_VIEW – view_name: "SELECT_INSTITUTION"
• onEvent: SELECT_INSTITUTION - user selects an institution
• onEvent: TRANSITION_VIEW – view_name: "CONSENT"

If the user chooses an institution directly from embedded search

• onEvent: OPEN – view_name: "CONSENT"
• onEvent: SELECT_INSTITUTION
• onEvent: TRANSITION_VIEW – view_name: "CONSENT"
• onEvent: TRANSITION_VIEW – view_name: "CREDENTIAL" or "OAUTH" - user selects Continue on the ConsentPane