React Native Integration Guide

Importing DyScan

After getting the access token for Dyneti's NPM repo access, go to your RN project root directory and set it up with the following terminal commands.

If you are using ~/.zshrc:

echo "export DYSCAN_NPM_TOKEN=accessTokenHere" >> ~/.zshrc
source ~/.zshrc
echo "@dyneti:registry=https://registry.npmjs.org/" >> .npmrc
echo "//registry.npmjs.org/:_authToken=\${DYSCAN_NPM_TOKEN}" >> .npmrc

If you are using ~/.bash_profile:

echo "export DYSCAN_NPM_TOKEN=accessTokenHere" >> ~/.bash_profile
source ~/.bash_profile
echo "@dyneti:registry=https://registry.npmjs.org/" >> .npmrc
echo "//registry.npmjs.org/:_authToken=\${DYSCAN_NPM_TOKEN}" >> .npmrc

Verify if the terminal can see the value of DYSCAN_NPM_TOKEN

echo $DYSCAN_NPM_TOKEN

Install DyScan with the following terminal commands

npm install @dyneti/react-native-dyscan --save 
react-native link 
react-native link @dyneti/react-native-dyscan 

Linking for Android

For version 1.1.15 and up: In the android-directory-level build.gradle add the Dyneti Maven repository (credentials provided during integration):

allprojects {
    repositories {
        // Other repositories are here
        maven {
            credentials  {
                username = "nexusUsername"
                password = "nexusPassword"
            }
            url "https://nexus.dyneti.com/repository/maven-releases/"
            authentication {
                basic(BasicAuthentication)
            }
        }
    }
}

At this point, if you are using a React Native version that is 0.63 or higher Android should be usable.

DyScan is only supported for API 21+. If your minSDK is lower, you may get a build error. This can be changed by editing the build.gradle file in the android directory.

We currently support React Native versions up to 0.73.x . Starting with version 1.2.12 we also support the New Architecture (TurboModules/Fabric)

For lower versions, or if other dependencies are manually linked, you may need to manually link the dependencies. Change MainActivity.java at android/app/src/main/java/com/ProjectName/ to match the following.

package com.reactnavigation.example;

import com.facebook.CallbackManager;
import com.facebook.react.ReactNativeHost;
import com.facebook.react.ReactApplication;
import com.facebook.react.ReactPackage;
import com.dyneti.dyscan.reactnative.RNDyScanPackage;

public class MainApplication extends Application implements ReactApplication {
 
    private static CallbackManager mCallbackManager = CallbackManager.Factory.create();
 
    protected static CallbackManager getCallbackManager() {
        return mCallbackManager;
    }
 
    private final ReactNativeHost mReactNativeHost = new ReactNativeHost(this) {
        @Override
        public boolean getUseDeveloperSupport() {
            return BuildConfig.DEBUG;
        }
 
        @Override
        protected List<ReactPackage> getPackages() {
            return Arrays.<ReactPackage>asList(new RNDyScanPackage());
        }
 
        @Override
        protected String getJSMainModuleName() {
            return "index";
        }
    };
 
    @Override
    public ReactNativeHost getReactNativeHost() {
        return mReactNativeHost;
    }
 
    @Override
    public void onCreate() {
        super.onCreate();
        AppEventsLogger.activateApp(this);
        SoLoader.init(this, /* native exopackage */ false);
    }
}

If you are getting an error during building of the APK like:

Execution failed for task ':@dyneti_react-native-dyscan:bundleDebugAar'.

Direct local .aar file dependencies are not supported when building an AAR. The resulting AAR would be broken because the classes and Android resources from any local .aar file dependencies would not be packaged in the resulting AAR. Previous versions of the Android Gradle Plugin produce broken AARs in this case too (despite not throwing this error)."

Run one of these commands in terminal in the android subdirectory of your React Native project to build an APK:

  • for debug: ./gradlew app:assembleDebug

  • for release: ./gradlew app:assembleRelease

Linking for iOS

Add the following line(s) to the Podfile in the ios directory. If you are unsure what Swift version you are using, use Universal variant and make sure you are using the latest (non-beta) version of Xcode.

If you do not have a Podfile in your ios directory, you will need to generate one. Follow the instructions here to do so. Make sure to remove the use_frameworks! line in the generated Podfile. If the generated Podfile contains two targets for ProjectName-tvOSTests,you should remove the first target.

pod 'DyScan', :podspec => '../node_modules/@dyneti/react-native-dyscan/specs/DyScan.podspec'

If your linking does not work for some reason (most common if you've added React Native to a native project), you may have to add the below line into your Podfile: pod 'RNDyScan', :path => '../node_modules/@dyneti/react-native-dyscan'

In the ios directory, execute in terminal

$ pod install

When asked for a password for user "dyscan", paste the GitHub access token that we provided during integration.

If you have not previously asked for camera permissions in the app, you will need to add the “NSCameraUsageDescription” (Privacy - Camera Usage Description) to your Info.plist file. To do this in Xcode, navigate to Info.plist. When you hover over any of the fields in the file, a small plus icon should show up next to the field. Click on the plus sign and type in “NSCameraUsageDescription” into the new field. You should set the value to be the string a user sees when they are prompted for the camera permission (e.g. To scan credit cards).

If you are getting an error like "DyScan/DyScan.h not found," you will need to remove DyScan as a library dependency. In the Xcode file tree, ctrl+click on RNDyScan.xcodeproj under Libraries to delete it. Xcode should prompt you to delete or remove the reference. Choose to remove the reference.

If the app is compiling but you are getting an error when you try to initialize DyScan that says "undefined is not an object (evaluating 'RNDyScanModule.scanCard')," then you will need to add the DyScan iOS node module directory as a header search path. To do this, click on your project name next to a blue icon in the navigation bar on the top left of Xcode. In the middle of the screen, select "Build Settings" and search for "Header Search Paths" in the search bar. Add $(SRCROOT)/../node_modules/@dyneti/react-native-dyscan/ios to the search paths.

If you are getting an error like "dyld: Library not loaded: @rpath/libswift*.dylib," then you will need to force Xcode to embed Swift libraries. Do this by clicking on your project name next to a blue icon in the navigation bar on the top left of Xcode. Click on "Build Settings" and search for "Always Embed Swift Standard Libraries." Set the value of this field from "No" to "Yes" and the app should now run.

Interfacing DyScan

Initializing DyScan (only for version 1.1.1 and up)

In your App.js add the following line to configure DyScan.

import React from 'react';
import {DyScan} from '@dyneti/react-native-dyscan';

const App: () => React$Node = () => {

  DyScan.init({
    apiKey: 'YOUR_API_KEY',
  });

  // some code here
};

export default App;

Camera features support

The DyScan.isDeviceSupported function can be called to verify if the device is supported before calling DyScan functions to avoid a bad user experience.

DyScan.isDeviceSupported().then((supported) => {
    if (supported) {
        // open DyScan card scan
        DyScanModule.scanCard({
          showDynetiLogo: true
        })
        .then(card => {
          // the scanned card
          // Access the fields cardNumber, expiryMonth, or expiryYear
        })
        .catch(() => {
          // the user cancelled
        })
    } else {
        // alternate flow if device is not supported
    }
})

DyScanModule

The DyScanModule abstracts the DyScanViewController on iOS and the DyScanActivity on Android. It will open a separate screen where the user will scan their card and return a JavaScript Promise.

import React, { Component } from 'react';
import { View, TouchableOpacity, Text, Platform } from 'react-native';
import { DyScanModule } from '@dyneti/react-native-dyscan';

export default class DyScanExample extends Component {

  scanCard() {
    DyScanModule
      .scanCard({
        apiKey:'YOUR_API_KEY' // for version lower than 1.1.1
      })
      .then(card => {
        // the scanned card
        // Access the fields cardNumber, expiryMonth, or expiryYear
      })
      .catch(() => {
        // the user cancelled
      })
  }

  render() {
    return (
      <View style={{ alignItems: 'center', justifyContent: 'center' }}>
        <TouchableOpacity onPress={this.scanCard.bind(this)}>
          <Text>Scan card!</Text>
        </TouchableOpacity>
      </View>
    );
  }
}

If you have been migrating from native Android to using React Native (or otherwise created a custom Activity to contain your react screens), you must be sure that you are passing calls to onActivityResult on to the ReactInstanceManager; otherwise neither callback will be called. For more details on how to do this, see the React Native documentation.

DyScanView

This component allows the scanning view to be placed on a screen with other components. You must be sure that the view gets unmounted when it is no longer needed.

import React, { Component } from 'react';
import { View } from 'react-native';
import { DyScanView } from '@dyneti/react-native-dyscan';

export default class DyScanExample extends Component {

  onCardScanned = (card) => {
    // the scanned card (can be null)
    // Access the fields cardNumber, expiryMonth, or expiryYear
  }

  render() {
    return (
      <View>
        <DyScanView
          onCardScanned={this.onCardScanned}
          apiKey={'YOUR_API_KEY'} // for version lower than 1.1.1
        />
      </View>
    );
  }
}

When you are using the View, we cannot determine for ourselves whether our View is still needed at any given point in time. You should ensure that the View gets unmounted when it is no longer needed since otherwise our code will continue to run in the background, wasting your users' resources. For example, with react-native-navigation, if in onCardScanned you immediately navigate to a results screen, the screen containing our view will be persisted on the stack and so will not be unmounted. In order to ensure it is unmounted, you should make a call to navigation.goBack() prior to making the call to navigation.navigate().

Customization

Both the module and the view support customization. For the module, you pass the parameters into the scanCard function along with the API key; for the view, you supply them as props on the view.

Supported by both

Parameter

Description

Type

showCorners

Whether to show the scan area outline.

boolean

cornerThickness

How thick to make the lines outlining the scan area, indicating to the user where to place their credit card.

number

cornerInactiveColor

The color to use in drawing the outline of the scan region when nothing of interest is detected.

cornerCompletedColor

The color to use in drawing the outline of the scan region when we have successfully scanned a card.

bgColor

The color to use to obscure everything outside the scan region in order to draw the user’s attention to the scan region.

bgOpacity

The opacity to use when obscuring everything outside the scan region, as an integer ranging from 0.0 (transparent) to 1.0 (opaque).

number

lightTorchWhenDark

Whether the phone will turn on the flashlight if multiple frames have appeared to be too dark. If set to false, torch toggle button will appear.

boolean

vibrateOnCompletion

Whether the device will vibrate once it has successfully extracted the credit card data from the images provided by the camera.

boolean

showDynetiLogo

Whether to show the Dyneti logo above the scan region

boolean

showCardOverlay

Whether to show the overlay displaying a sample card number and expiration date hinting at the user to place their card in the scan region.

boolean

enableSidewaysScanning

Whether to allow cards to scan in sideways orientation. If set to true, vertical cards will be able to be scanned when positioned in the horizontal scan window. Note that enableSidewaysScanning and showRotateButton should not simultaneously be set to true when using DyScanModule.

boolean

DyScanModule

Prop

Description

Type

showHelperText

Whether to show the helper text on screen.

boolean

helperTextString

What to text to display to the user to guide them in scanning their card.

string

helperTextColor

The color to use to display the helper text.

helperTextSize

The font size of the helper text.

number

helperTextFontFamily

The font family name of the helper text. The font needs to be placed in assets first.

string

showRotateButton

Whether to show the button which allows the user to rotate the scan region by 90 degrees, facilitating the scanning of vertical cards.

boolean

helperTextPosition

The preset position of the helper text. Available values: top, center, bottom. Default: bottom

string

DyScanView

Prop

Description

Type

onCardScanned

A callback for receiving results from the scanning process. card will be undefined on failure.

(card: CreditCard) => void

Color Representation

Colors are inputted as hex-encoded strings representing the RGB values with a '#' at the front, the so-called 'HTML Color Codes.' For example, #ff0000 is red. The representation must be exactly 7 characters long; otherwise we will ignore it when trying to convert the strings to the native representations.

TypeScript

We also provide TypeScript bindings in our package. If you use TypeScript no additional steps will be required to start using the types we provide.

Last updated