fidel-react-native

Fidel React Native bridge SDK

This SDK is a bridge between React Native and Fidel's native iOS and Android SDKs. It helps you to add card linking technology to your React Native apps in minutes. It captures credit/debit card numbers securely and links them to your programs.

Getting started

$ npm install fidel-react-native --save

(Almost) Automatic linking (for RN >= 0.60)

$ react-native link fidel-react-native

iOS

1. Go to the ios folder. Please check that in your Podfile you have the following line:

pod 'fidel-react-native', :path => '../node_modules/fidel-react-native'

2. Please make sure that the minimum platform is set to 9.1 in your Podfile: platform :ios, '9.1'.

3. Run pod install.

Android

1. Append Jitpack to android/build.gradle:

allprojects {
  repositories {
    ...
    maven { url "https://jitpack.io" }
  }
}

2. Make sure that the minSdkVersion is the same or higher than the minSdkVersion of our native Android SDK:

buildscript {
  ext {
    ...
    minSdkVersion = 19
    ...
  }
}

Manual linking

iOS manual linking

Step 1: Add the Fidel React Native iOS project as a dependency

1. In XCode, in the project navigator, right click Libraries ➜ Add Files to [your project's name]

2. Go to node_modules ➜ fidel-react-native and add Fidel.xcodeproj

3. In XCode, in the project navigator, select your project. Add libFidel.a to your project's Build Phases ➜ Link Binary With Libraries

4. Under your target's Build Settings, make sure to set YES for Always Embed Swift Standard Libraries. That's because, by default, your project might not need it. It needs to be YES because otherwise the project will not find the Swift libraries to be able to run our native iOS SDK.

Step 2: Add the Native iOS SDK as a dependency

You can use Cocoapods or install the library as a dynamic library.

5. Add a Podfile in your ios/ folder of your React Native project. It should include the following dependency:

use_frameworks!
pod 'Fidel'

Here is the simplest Podfile you need to link with our native iOS SDK:

platform :ios, '9.1'

workspace 'example'

target 'example' do
    use_frameworks!
    pod 'Fidel'
end

6. If you use an older Swift version, you should install a different Fidel pod version. If your project uses Swift 4.2.1, for example, your Podfile should include pod Fidel, '~>1.4', not pod 'Fidel' (which installs the latest version of the latest Swift supported version). Please check our iOS SDK README (step 1). You'll find a suitable version you should set for our Fidel iOS SDK.

7. Run pod install in your terminal.

8. Make sure to use the new .xcworkspace created by Cocoapods when you run your iOS app. React Native should use it by default.

9. In order to allow scanning cards with the camera, make sure to add the key NSCameraUsageDescription to your iOS app Info.plist and set the value to a string describing why your app needs to use the camera (e.g. "To scan credit cards."). This string will be displayed when the app initially requests permission to access the camera.

Android manual linking

1. Append the following lines to android/settings.gradle:

include ':fidel-react-native'
project(':fidel-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/fidel-react-native/android')

2. Insert the following lines inside the dependencies block in android/app/build.gradle:

implementation project(':fidel-react-native')

3. Append Jitpack to android/build.gradle:

allprojects {
  repositories {
    ...
    maven { url "https://jitpack.io" }
  }
}

4. Make sure that the minSdkVersion is the same or higher than the minSdkVersion of our native Android SDK:

buildscript {
  ext {
    ...
    minSdkVersion = 19
    ...
  }
}

5. Only for projects initialized with RN <= 0.59: Open up android/app/src/main/java/[...]/MainApplication.java

• Add import com.fidelreactlibrary.FidelPackage; to the imports at the top of the file
• Add new FidelPackage() to the list returned by the getPackages() method:

protected List <ReactPackage> getPackages() {
  return Arrays.<ReactPackage>asList(
          new MainReactPackage(),
          new FidelPackage(),
          //you might have other Packages here as well.
      );
}

6. Ensure that you have Google Play Services installed.

For a physical device you need to search on Google for Google Play Services. There will be a link that takes you to the Play Store and from there you will see a button to update it (do not search within the Play Store).

How to use Fidel's React Native SDK

Import Fidel in your RN project:

import Fidel from 'fidel-react-native';

Set up Fidel with your API key and your program ID. Without them you can't open the Fidel card linking UI:

Fidel.setup({
  apiKey:'your api key',
  programId: 'your program id'
})

Set the options that create the experience of linking a card with Fidel:

const myImage = require('./images/fdl_test_banner.png');
const resolveAssetSource = require('react-native/Libraries/Image/resolveAssetSource');
const resolvedImage = resolveAssetSource(myImage);

//this is the default value for supported card schemes,
//but you can remove the support for some of the card schemes if you want to
const cardSchemes = new Set([
  Fidel.CardScheme.visa,
  Fidel.CardScheme.mastercard,
  Fidel.CardScheme.americanExpress
]);

Fidel.setOptions({
  bannerImage: resolvedImage,
  country: Fidel.Country.sweden,
  supportedCardSchemes: Array.from(cardSchemes),
  autoScan: false,
  metaData: {'meta-data-1': 'value1'}, // additional data to pass with the card
  companyName: 'My RN Company', // the company name displayed in the checkbox text
  deleteInstructions: 'Your custom delete instructions!',
  privacyUrl: 'https://fidel.uk',
  termsConditionsURL: 'https://fidel.uk/privacy', // mandatory when you set the default country to USA/Canada or when the user can select USA/Canada
  programName: 'My program name', // optional, is used when you set the default country to USA/Canada or when the user can select USA/Canada
});

Open the card linking view by calling:

Fidel.openForm((error, result) => {
  if (error) {
    console.error(error);
  } else {
    console.info(result);
  }
});

Both result and error are objects that look like in the following examples:

Result

{
  accountId: "the-account-id"
  countryCode: "GBR" // the country selected by the user, in the Fidel SDK form
  created: "2019-04-22T05:26:45.611Z"
  expDate: "2023-12-31T23:59:59.999Z" // the card expiration date
  expMonth: 12 // for your convenience, this is the card expiration month
  expYear: 2023 // for your convenience, this is the card expiration year
  id: "card-id" // the card ID as registered on the Fidel platform
  lastNumbers: "4001" //last numbers of the card
  live: false
  mapped: false
  metaData: {meta-data-1: "value1"} //the meta data that you specified for the Fidel SDK
  programId: "your program ID, as specified for the Fidel SDK"
  scheme: "visa"
  type: "visa"
  updated: "2019-04-22T05:26:45.611Z"
}

Error

{
  code: "item-save" // the code of the error
  date: "2019-04-22T05:34:04.621Z" // the date of the card link request
  message: "Item already exists" // the message of the error
}

Options documentation

bannerImage

Use this option to customize the topmost banner image with the Fidel UI. Your custom asset needs to be resolved in order to be passed to our native module:

const myImage = require('./images/fdl_test_banner.png');
const resolveAssetSource = require('react-native/Libraries/Image/resolveAssetSource');
const resolvedImage = resolveAssetSource(myImage);
Fidel.setOptions({
  bannerImage: resolvedImage
}

country

Set a default country the SDK should use with:

Fidel.setOptions({
  country: Fidel.Country.unitedKingdom
});

When you set a default country, the card linking screen will not show the country picker UI. The other options, for now, are: .unitedStates, .ireland, .sweden, .japan, .canada.

supportedCardSchemes

We currently support Visa, Mastercard and AmericanExpress, but you can choose to support only one, two or all three. By default the SDK is configured to support all three.

If you set this option to an empty array or to null, of course, you will not be able to open the Fidel UI. You must support at least one our supported card schemes.

Please check the example below:

//this is the default value for supported card schemes,
//but you can remove the support for some of the card schemes if you want to
const cardSchemes = new Set([
  Fidel.CardScheme.visa,
  Fidel.CardScheme.mastercard,
  Fidel.CardScheme.americanExpress
]);
Fidel.setOptions({
  supportedCardSchemes: Array.from(cardSchemes)
});

autoScan

Set this property to true, if you want to open the card scanning UI immediately after executing Fidel.openForm. The default value is false.

Fidel.setOptions({
  autoScan: true
});

metaData

Use this option to pass any other data with the card data:

Fidel.setOptions({
  metaData: {'meta-data-key-1': 'value1'}
});

companyName

Set your company name as it will appear in our consent checkbox text. Please set it to a maximum of 60 characters.

Fidel.setOptions({
  companyName: 'Your Company Name'
});

programName

Set your program name as it will appear in the consent text. Note that this parameter is used when you set United States or Canada as the default country or don't set a default country (meaning that the user is free to select United States or Canada as their country). Please set it to a maximum of 60 characters.

Fidel.setOptions({
  programName: 'Your Program Name'
});

deleteInstructions

Write your custom opt-out instructions for your users. They will be displayed in the consent checkbox text as well.

Fidel.setOptions({
  deleteInstructions: 'Your custom card delete instructions!'
});

privacyUrl

This is the privacy policy URL that you can set for the consent checkbox text.

Fidel.setOptions({
  privacyUrl: 'https://fidel.uk',
});

termsConditionsUrl

This is the terms & conditions URL that you can set for the consent text. Note that this parameter mandatory when you set United States or Canada as the default country or don't set a default country (meaning that the user is free to select United States or Canada as their country).

Fidel.setOptions({
  termsConditionsUrl: 'https://fidel.uk',
});

Consent text for United States and Canada

When you set United States or Canada as the default country or don't set a default country (meaning that the user is free to select United States or Canada as their country), a different consent text will be applied. You can set the following parameters in this consent text:

Fidel.setOptions({
  termsConditionsUrl: 'https://fidel.uk',
  programName: 'Your Program Name',
});

The default placeholder value for programName is our (in English). The termsConditionsURL is mandatory in this case. If you don't set a privacy policy URL (which is different than the terms & conditions URL), the corresponding wording will not be displayed.

For USA & Canada, the following would be an example Terms & Conditions text, for Cashback Inc (an example company):

By submitting your card information and checking this box, you authorize Visa to monitor and share transaction data with Fidel (our service provider) to participate in program. You also acknowledge and agree that Fidel may share certain details of your qualifying transactions with Cashback Inc to enable your participation in program and for other purposes in accordance with the Cashback Inc Terms and Conditions, Cashback Inc privacy policy and Fidel’s Privacy Policy. You may opt-out of transaction monitoring on the linked card at any time by contacting support.

For the rest of the world:

I authorise Visa to monitor my payment card to identify transactions that qualify for a reward and for Visa to share such information with Cashback Inc, to enable my card linked offers and target offers that may be of interest to me. For information about Cashback Inc privacy practices, please see the privacy policy. You may opt-out of transaction monitoring on the payment card you entered at any time by contacting support.

Localisation

The SDK's default language is English, but it's also localised for French and Swedish languages. When the device has either Français (Canada) or Svenska (Sverige) as its language, the appropriate texts will be displayed. Please note that developer error messages are in English only and they will not be displayed to the user.

Please make sure that your project also supports localisation for the languages that you want to support.

Documentation

In the test environment please use our VISA, Mastercard or American Express test card numbers. You must use a test API Key for them to work.

VISA: 4444000000004*** (the last 3 numbers can be anything)

Mastercard: 5555000000005*** (the last 3 numbers can be anything)

American Express: 3400000000003** or 3700000000003** (the last 2 numbers can be anything)

Feedback

The Fidel SDK is in active development, we welcome your feedback!

Get in touch:

GitHub Issues - For SDK issues and feedback Fidel Developers Forum - https://community.fidel.uk - for personal support at any phase of integration