# React Native Applications source: https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/react-native-sdk/index.md If you are creating cross platform mobile app, we recommend using our React Native SDK. App to app authentication is supported in much the same way as with our native iOS and Android SDKs. ## React Native SDK {#react-native-sdk} The Data Connect React Native SDK provides an easy way for you to integrate Mastercard Open Finance Data Connect into your React Native application. #### Compatibility {#compatibility} The Data Connect React Native SDK supports the following Android and iOS versions: * Android: Android 5.0 (Lollipop) or later, Android SDK level 21 or later. * iOS: iOS 11 or later. Note: The `redirectUrl` property, supporting universal links on iOS, app links on Android, and deeplinks, is available from Data Connect React Native SDK version 2.0.0 onward (we recommend using the most recent available version of the SDK). For more information see our [Github repository](https://github.com/Mastercard/connect-react-native-sdk). ### Install the Data Connect React Native SDK {#install-the-data-connect-react-native-sdk} ### Dependencies {#dependencies} The Data Connect React Native SDK has the following `peerDependencies`: * [react-native-inappbrowser-reborn](https://www.npmjs.com/package/react-native-inappbrowser-reborn) \>= 3.6 * [react-native-webview](https://www.npmjs.com/package/react-native-webview) \>= 11 * [react](https://www.npmjs.com/package/react) \>= 16.13 * [react-native](https://www.npmjs.com/package/react-native) \>= 0.63 ### Step 1: Add repository to your project {#step-1-add-repository-to-your-project} If your application doesn't use `react-native-inappbrowser-reborn` and `react-native-webview` as dependencies, you can install them using the following: * [react-native-inappbrowser-reborn](https://github.com/proyecto26/react-native-inappbrowser) * [react-native-webview](https://github.com/react-native-webview/react-native-webview)
The Data Connect React Native SDK has been tested on `react-native-inappbrowser-reborn` version 3.7.0 and `react-native-webview` version 13.6.4. ### Step 2: Add Data Connect React Native SDK {#step-2-add-data-connect-react-native-sdk} The easiest way to install the SDK is to use npm or yarn: * npm: `npm install connect-react-native-sdk` * yarn: `yarn add connect-react-native-sdk`
On iOS, CocoaPods needs this additional step: `$ cd ios && pod install && cd ..` Tip: You can view the SDK source code on [Github](https://github.com/Mastercard/connect-react-native-sdk). Note: The Data Connect React Native SDK only supports React Native versions above 0.64. Linking the package manually is not required as it uses [Autolinking](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md). ### Step 3: Update Android application settings {#step-3-update-android-application-settings} The Data Connect React Native SDK requires internet access to connect with our servers, so you need to add internet permissions to the `AndroidManifest.xml` file: ```xml ``` ### Usage {#usage} #### Parameters {#parameters} | Parameter | Description | |----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `connectUrl` (required) | The SDK loads the Data Connect URL provided in order to show the Data Connect experience. | | `eventHandlers` (required) | A class implementing the `ConnectEventHandlers` interface. | | `redirectUrl` (optional) | The URL to redirect back to your mobile app after completing an FI's OAuth flow (universal link on iOS, app link on Android). This parameter is only required for App to App. | See the [Generate Data Connect URL](https://developer.mastercard.com/open-finance-us/documentation/connect/generate-2-connect-url-apis/index.md) section for details of how to generate a Data Connect URL for the `connectUrl` parameter. ```javascript import { Connect, ConnectEventHandlers, } from 'connect-react-native-sdk'; const MyConnectComponent = () => { const eventHandlers: ConnectEventHandlers = { onDone: (event: ConnectDoneEvent) => {}, onCancel: (event: ConnectCancelEvent) => {}, onError: (event: ConnectErrorEvent) => {}, onRoute: (event: ConnectRouteEvent) => {}, onUser: (event: any) => {}, onLoad: () => {}, }; return ( ); }; ``` ### Event Handler Interface {#event-handler-interface} Throughout the Data Connect flow, events about the state of the web application are sent as JSON objects to the `eventHandlers` prop. Note: The `onUser` event handler will not return anything unless you are specifically targeting Data Connect, ```javascript export interface ConnectEventHandlers { onDone: (event: ConnectDoneEvent) => void; onCancel: (event: ConnectCancelEvent) => void; onError: (event: ConnectErrorEvent) => void; onRoute?: (event: ConnectRouteEvent) => void; onUser?: (event: any) => void; onLoad?: () => void; } ``` #### Callback Events {#callback-events} See [here](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#callback-events) for details on the events via their callback interface. **Note** : The `onDone`, `onError`, `onRoute`, and `onUser` callback functions will have a **JSONObject** parameter that contains data about the event. ## App To App support {#app-to-app-support} To provide the best app to app authentication experience for your customers, you should send a universal link URL in the `redirectUrl` parameter when using Data Connect. See [App To App Authentication](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#app-to-app-authentication) for more details, including [how to test](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/index.md#how-to-test-app-to-app-authentication). Before installing the Data Connect React Native SDK for use with app to app authentication, complete the following: * Create your domain's `redirectUrl` (iOS universal link, Android app link) * Configuring your `redirectUrl` ### iOS: Create your domain's redirectUrl {#ios-create-your-domains-redirecturl} For information on how to create a [Universal Link](https://developer.apple.com/ios/universal-links/) to be used as the `redirectUrl` in your application, see Apple's [Allowing apps and websites to link to your content](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) documentation. For information on how to configure your server, see [supporting associated domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains) in the Apple developer documentation. Tip: In order to provide the best app to app authentication customer experience, you should use a universal link for `redirectUrl`. We do not recommend using a deep link (custom URL scheme) for `redirectUrl` since deep links lack the security that Apple's Universal Links provide through the two-way association between your app and your website. A deep link will also trigger an alert on iOS devices which can add friction to the customer experience, requesting permission to redirect back to the Partner's app. Any application can register custom URL schemes and there is no further validation from iOS. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete OAuth flows, it is important that your application is opened and not any other application that has registered the same URL scheme. ### Android: Create your domain's redirectUrl {#android-create-your-domains-redirecturl} For information on how to create an [App Link](https://developer.android.com/training/app-links#android-app-links) as `redirectUrl` in your application, see [adding Android App Links](https://developer.android.com/studio/write/app-link-indexing) in the Android developer documentation. Tip: In order to provide the best app to app authentication customer experience, you should use an app link for `redirectUrl`. We do not recommend using a deep link (custom URL scheme) for `redirectUrl` since deep links lack the security that Android App Links provide through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from Android. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete OAuth flows, it is important that your application is opened and not any other application that has registered the same URL scheme. ### Configuring your redirectUrl {#configuring-your-redirecturl} In order to return control back to your application after a customer completes an FI's OAuth flow, you must specify a `redirectUrl` value. This URL is used to redirect back to your mobile app after completing an FI's OAuth flow (this should be a universal link on iOS or an app link on Android). Here is an example of a universal link `redirectUrl` within your code: ```html ``` ### Android: Working without redirectUrl {#android-working-without-redirecturl} If your Android application does not pass `redirectUrl`, additional configuration is required in order to support OAuth redirection and deep linking back to your application. Tip: In order to have the best app to app authentication experience, we recommend specifying a universal or app link as `redirectUrl` for iOS and Android platforms. If however this is not possible, the following additional configuration is required with Android, due to behavior changes introduced in Android 15. This ensures the Connect flow can redirect securely back to your application after authentication. On iOS, the existing URL scheme handling will be used. To enable this, you must ensure you are using version 2.0.5 or later of the Data Connect React Native SDK, then configure an intent filter in your Android app's **AndroidManifest.xml** file. Inside the `` that handles app launches (usually `MainActivity`), add the intent filter as follows: ```xml ``` Warning: Do not change the scheme, host, or path unless explicitly instructed. Ensure this intent filter is added only once. ## Sample React Native App {#sample-react-native-app} We provide a sample project uses the Data Connect React Native SDK on Github: [ConnectReactNativeDemoApp](https://github.com/Mastercard/connect-react-native-sdk/tree/master/ConnectReactNativeDemoApp) Ensure that you have the necessary setup for React Native version 0.72 to successfully run and explore this demo app. ## Data Connect React Native SDK Migration Guide {#data-connect-react-native-sdk-migration-guide} This migration guide provides step by step instructions for migrating from Data Connect React-Native SDK version 1.x to version 2.x. Follow the outlined changes carefully to ensure a smooth transition. ### Step 1: Update your installation {#step-1-update-your-installation} The first step is to make sure you install the new version of the SDK. If you were previously using npm then you will need to update your npm command as shown. You can also use yarn from v2.x onward. **v1.x** npm install @finicity/connect-react-native-sdk **v2.x** * npm: `npm install connect-react-native-sdk` * yarn: `yarn add connect-react-native-sdk`
On iOS, CocoaPods needs this additional step: `$ cd ios && pod install && cd ..` ### Step 2: Update your code {#step-2-update-your-code} You will need to update your code where you import the SDK and use the components as follows. **v1.x** With v1.x, you needed to import `FinicityConnect` and `ConnectEventHandlers` from `@finicity/connect-react-native-sdk`, and your return function could define the `linkingUri` property: ```javascript import { FinicityConnect, ConnectEventHandlers, } from '@finicity/connect-react-native-sdk'; const MyConnectComponent = () => { const eventHandlers: ConnectEventHandlers = { onDone: (event: ConnectDoneEvent) => {}, onCancel: (event: ConnectCancelEvent) => {}, onError: (event: ConnectErrorEvent) => {}, onRoute: (event: ConnectRouteEvent) => {}, onUser: (event: any) => {}, onLoad: () => {}, }; return ( ); }; ``` **v2.x** With v2.x, you need to import `Connect` and `ConnectEventHandlers` from `connect-react-native`, and your return code will need to be updated to use `redirectUrl` instead of `linkingUri`, as shown below: ```javascript import { Connect, ConnectEventHandlers, } from 'connect-react-native-sdk'; const MyConnectComponent = () => { const eventHandlers: ConnectEventHandlers = { onDone: (event: ConnectDoneEvent) => {}, onCancel: (event: ConnectCancelEvent) => {}, onError: (event: ConnectErrorEvent) => {}, onRoute: (event: ConnectRouteEvent) => {}, onUser: (event: any) => {}, onLoad: () => {}, }; return ( ); }; ```