Link Webview SDK  ================= #### Reference for integrating with the Link Webview JavaScript SDK  Using webviews to present Link is deprecated. If you're currently integrating this way, we recommend migrating to [Hosted Link](https://plaid.com/docs/link/hosted-link/index.html.md) or one of Plaid's official SDKs for [Android](https://plaid.com/docs/link/android/index.html.md) , [iOS](https://plaid.com/docs/link/ios/index.html.md) , and [React Native](https://plaid.com/docs/link/react-native/index.html.md) . All Webview-based integrations need to extend the Webview handler for redirects in order to support connections to Chase. This can be accomplished with code samples for [iOS](https://github.com/plaid/plaid-link-examples/blob/master/webviews/wkwebview/wkwebview/LinkViewController.swift#L56-L72) and [Android](https://github.com/plaid/plaid-link-examples/blob/master/webviews/android/LinkWebview/app/src/main/java/com/example/linkwebview/MainActivity.kt#L89-L156) . For more details, see [Extending webview instances to support certain institutions](https://plaid.com/docs/link/oauth/index.html.md#extending-webview-instances-to-support-certain-institutions) in the OAuth Guide and the [in-process Webview deprecation notice](https://plaid.docsend.com/view/h3qdupjusiwyjvv5) . Webview-based integrations that do not extend the Webview handler are not supported by Chase and may be blocked by Chase in the future. If your integration does not connect to Chase (for example, because you use only Identity Verification, Document Income, or Payroll Income, or you do not support end users in the US) you may ignore this warning. #### Overview  To integrate and use Plaid Link inside a Webview, we recommend starting with one of our sample Webview apps: * [iOS WKWebView](https://github.com/plaid/plaid-link-examples/tree/master/webviews/wkwebview) * [Android Webview](https://github.com/plaid/plaid-link-examples/tree/master/webviews/android) Each example app is runnable (on both simulators and devices) and includes code to initialize Link and process events sent from Link to your app via HTTP redirects. #### Installation  Link is optimized to work within Webviews, including on iOS and Android. The Link initialization URL to use for Webviews is: Link Webview initialization URL ```html https://cdn.plaid.com/link/v2/stable/link.html ``` The Link configuration options for a Webview integration are passed via querystring rather than via a client-side JavaScript call. See the [create](https://plaid.com/docs/link/webview/index.html.md#create) section below for details on the available initialization parameters. ##### Communication between Link and your app  Communication between the Webview and your app is handled by HTTP redirects rather than client-side JavaScript callbacks. These redirects should be intercepted by your app. The [example apps](https://github.com/plaid/plaid-link-examples) include sample code to do this. All redirect URLs have the scheme `plaidlink`. The event type is communicated via the URL host and data is passed via the querystring. HTTP redirect scheme ```html plaidlink:// ``` There are three supported events, [connected](https://plaid.com/docs/link/webview/index.html.md#connected) , [exit](https://plaid.com/docs/link/webview/index.html.md#exit) , and [event](https://plaid.com/docs/link/webview/index.html.md#event) , which are documented below. \=\*=\*=\*= #### create()  **Properties** boolean Set to `true`, to trigger the Webview integration. string Specify a `link_token` to authenticate your app with Link. This is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a `link_token` can be configured to launch Link in [update mode](https://plaid.com/docs/link/update-mode/index.html.md) . See the `/link/token/create` endpoint for a full list of configurations. string A `receivedRedirectUri` is required to support OAuth authentication flows when re-launching Link on a mobile device. Note that any unsafe ASCII characters in the `receivedRedirectUri` in the webview query string must be URL-encoded. deprecated, string The `public_key` is no longer used for new implementations of Link. If your integration is still using a `public_key`, please contact Plaid support or your account manager. Create example ```xml https://cdn.plaid.com/link/v2/stable/link.html ?isWebview=true &token="GENERATED_LINK_TOKEN" &receivedRedirectUri= ``` \=\*=\*=\*= #### connected  The `connected` event is analogous to the `onSuccess` callback in [Link Web](https://plaid.com/docs/link/web/index.html.md) and is sent when a user successfully completes Link. The following information is available from the querystring event: **Properties** string Displayed once a user has successfully completed Link. If using Identity Verification or Beacon, this field will be `null`. If using Document Income or Payroll Income, the `public_token` will be returned, but is not used. string The full institution name, such as `'Wells Fargo'` string The Plaid institution identifier object A JSON-stringified representation of the account(s) attached to the connected Item. If Account Select is enabled via the developer dashboard, `accounts` will only include selected accounts. string The Plaid `account_id` object The account metadata string The official account name nullable, string The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user. string The account type. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values string The account subtype. See the [Account schema](https://plaid.com/docs/api/accounts/index.html.md#account-type-schema) for a full list of possible values string When all Auth features are enabled by initializing Link with the user object, the accounts object includes an Item's `verification_status`. See Auth accounts for a full list of possible values. deprecated, nullable, string If micro-deposit verification was being used, indicates the user's selection when asked if the account being verified is a `business` or `personal` account. This field is deprecated as Plaid no longer collects this information during the micro-deposit flow. nullable, string The status of a transfer. Returned only when [Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md) is implemented. * `COMPLETE` – The transfer was completed. * `INCOMPLETE` – The transfer could not be completed. For help, see [Troubleshooting Transfer UI](https://plaid.com/docs/transfer/using-transfer-ui/index.html.md#troubleshooting-transfer-ui) . Possible values: `COMPLETE`, `INCOMPLETE` string A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. Connected event example ```xml plaidlink://connected ?public_token=public-sandbox-fb7cca4a-82e6-4707 &institution_id=ins_3 &institution_name=Chase &accounts='[{"_id":"QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK", "meta": {"name":"Plaid Savings", "number": "0000"}, "subtype": "checking", "type": "depository" }]' &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a ``` accounts schema example ```json "accounts": [ { "_id": "ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy", "meta": { "name": "Plaid Checking", "number": "0000" }, "type": "depository", "subtype": "checking", "verification_status": null }, { "_id": "9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4", "meta": { "name": "Plaid Saving", "number": "1111" }, "type": "depository", "subtype": "savings" } ... ] ``` \=\*=\*=\*= #### exit()  The `exit` event is analogous to the `onExit` callback and is sent when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. Note that on Android devices, an `exit` event will not be sent if the user exits Link through a system action, such as hitting the browser back button. The following information is available from the querystring: **Properties** string The point at which the user exited the Link flow. One of the following values. User prompted to answer security questions User prompted to answer multiple choice question(s) User prompted to provide a one-time passcode User prompted to select a device on which to receive a one-time passcode User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution User prompted to select one or more financial accounts to share User prompted to enter an OAuth flow User exited the Link flow on the institution selection pane. Typically this occurs after the user unsuccessfully (no results returned) searched for a financial institution. Note that this status does not necessarily indicate that the user was unable to find their institution, as it is used for all user exits that occur from the institution selection pane, regardless of other user behavior. User exited the Link flow after discovering their selected institution is no longer supported by Plaid String A broad categorization of the error. String The particular error code. Each `error_type` has a specific set of `error_codes`. String A developer-friendly representation of the error code. nullable, String A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. string The full institution name, such as `Wells Fargo` string The Plaid institution identifier string A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround. string The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. onExit example ```xml plaidlink://exit ?status=requires_credentials &error_type=ITEM_ERROR &error_code=ITEM_LOGIN_REQUIRED &error_display_message=The%20credentials%20were%20not%20correct.%20Please%20try%20again. &error_message=the%20credentials%20were%20not%20correct &institution_id=ins_3 &institution_name=Chase &link_session_id=79e772be-547d-4c9c-8b76-4ac4ed4c441a &request_id=m8MDnv9okwxFNBV ``` \=\*=\*=\*= #### event  The `event` message is analogous to the Link Web [onEvent callback](https://plaid.com/docs/link/web/index.html.md#onevent) and is called as the user moves through the Link flow. The querystring will always contain all possible keys, though not all keys will have values. The `event_name` will dictate which keys are populated. **Properties** string A string representing the event that has just occurred in the Link flow. The user was automatically sent an OTP code without a UI prompt. This event can only occur if the user's phone number was provided to Link via the `/link/token/create` call and the user has previously consented to receive OTP codes from Plaid. The user has completed the Assets and Bank Income Insights flow. The user closed the third-party website or mobile app without completing the OAuth flow. The user has chosen to link a new institution instead of linking a saved institution. This event is only emitted in the Link Returning User Experience flow. A recoverable error occurred in the Link flow, see the `error_code` metadata. The user has exited without completing the Link flow and the [exit](https://plaid.com#exit) callback is fired. The user encountered an error while completing the third-party's OAuth login flow. The user has exited Link after successfully linking an Item. An Identity Match check configured via the Account Verification Dashboard failed the Identity Match rules and did not detect a match. An Identity Match check configured via the Account Verification Dashboard passed the Identity Match rules and detected a match. The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account. The user selected an institution that was presented as a matched institution. This event can be emitted if [Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/index.html.md) is being used, if the institution was surfaced as a matched institution likely to have been linked to Plaid by a returning user, or if the institution's `routing_number` was provided when calling `/link/token/create`. For details on which scenario is triggering the event, see `metadata.matchReason`. The user has opened Link. The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow. The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account. The user has searched for an institution. The user selected a brand, e.g. Bank of America. The `SELECT_BRAND` event is only emitted for large financial institutions with multiple online banking portals. The user selected an institution with a `DEGRADED` health status and was shown a corresponding message. The user selected an institution with a `DOWN` health status and was shown a corresponding message. The user selected an institution Plaid does not support all requested products for and was shown a corresponding message. The user selected an institution. The user has opted to not provide their phone number to Plaid. This event is only emitted in the Link Returning User Experience flow. The user has submitted an account number. This event emits the `account_number_mask` metadata to indicate the mask of the account number the user provided. The user has submitted credentials. The user is being prompted to submit documents for an Income verification flow. The user encountered an error when submitting documents for an Income verification flow. The user has successfully submitted documents for an Income verification flow. The user has submitted MFA. The user has submitted an OTP code during the phone number verification flow. This event is only emitted in the Link Returning User Experience (Remember Me) flow or Layer flow. This event will not be emitted if the phone number is verified via SNA. The user has submitted their phone number. This event is only emitted in the Link Returning User Experience (Remember Me) flow. The user has submitted a routing number. This event emits the `routing_number` metadata to indicate user's routing number. The `TRANSITION_VIEW` event indicates that the user has moved from one view to the next. The user has successfully verified their phone number via either OTP or SNA. This event is only emitted in the Link Returning User Experience (Remember Me) flow or the Layer flow. The user has viewed data types on the data transparency consent pane. nullable, string The error type that the user encountered. Emitted by: `ERROR`, `EXIT`. nullable, string The error code that the user encountered. Emitted by `ERROR`, `EXIT`. nullable, string The error message that the user encountered. Emitted by: `ERROR`, `EXIT`. nullable, string The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT` nullable, string The ID of the selected institution. Emitted by: _all events_. nullable, string The name of the selected institution. Emitted by: _all events_. nullable, string The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`. nullable, string Indicates if the current Link session is an update mode session. Emitted by: `OPEN`. nullable, string The reason this institution was matched. This will be either `returning_user` or `routing_number` if emitted by: `MATCHED_SELECT_INSTITUTION`. Otherwise, this will be `SAVED_INSTITUTION` or `AUTO_SELECT_SAVED_INSTITUTION` if emitted by: `SELECT_INSTITUTION`. nullable, string If set, the user has encountered one of the following MFA types: `code`, `device`, `questions`, `selections`. Emitted by: `SUBMIT_MFA` and `TRANSITION_VIEW` when `view_name` is `MFA` nullable, string The name of the view that is being transitioned to. Emitted by: `TRANSITION_VIEW`. The view showing Terms of Service in the identity verification flow. The user has connected their account. We ask the user to consent to the privacy policy. Asking the user for their account credentials. The view requesting Documentary Verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor). An error has occurred. Confirming if the user wishes to close Link. The user has authorized an instant micro-deposit to be sent to their account over the RTP or FedNow network with a 3-letter code to verify their account. The view representing the "know your customer" step in the identity verification flow. Link is making a request to our servers. The user is asked by the institution for additional MFA authentication. The user is asked to insert their account and routing numbers. The user is informed they will authenticate with the financial institution via OAuth. The user was presented with a Google reCAPTCHA to verify they are human. The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor). The user has authorized a same day micro-deposit to be sent to their account over the ACH network with a 3-letter code to verify their account. The watchlist screening step in the identity verification flow. We ask the user to choose an account. The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals. We ask the user to choose their institution. The user is asked to select their saved accounts and/or new accounts for linking in the Link Returning User Experience (Remember Me) flow. The user is asked to pick a saved institution or link a new one in the Link Returning User Experience (Remember Me) flow. The view in the identity verification flow which uses the camera to confirm there is a real user present that matches their ID documents. The user is asked for their phone number in the Link Returning User Experience (Remember Me) flow. The user is asked to verify their phone in the Link Returning User Experience (Remember Me) flow or the Layer flow. This screen will appear even if a non-OTP verification method is used. The SMS verification step in the identity verification flow. string The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: _all events_. string The `link_session_id` is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: _all events_. string An ISO 8601 representation of when the event occurred. For example `2017-09-14T14:42:19.350Z`. Emitted by: _all events_. nullable, string The Auth Type Select flow type selected by the user. Possible values are `flow_type_manual` or `flow_type_instant`. Emitted by: `SELECT_AUTH_TYPE`. event example ```xml plaidlink://event ?event_name=SELECT_INSTITUTION &error_type=ITEM_ERROR &error_code=ITEM_LOGIN_REQUIRED &error_message=the%20credentials%20were%20not%20correct &exit_status &institution_id=ins_55 &institution_name=HSBC &institution_search_query=h &mfa_type &view_name=ERROR &request_id &link_session_id=821f45a8-854a-4dbb-8e5f-73f75350e7e7 ×tamp=2018-10-05T15%3A22%3A50.542Z ``` #### OAuth  Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the [OAuth Guide](https://plaid.com/docs/link/oauth/index.html.md) . #### Supported platforms  Plaid officially supports WKWebView on iOS 10 or later and Chrome WebView on Android 4.4 or later.