Capacitor set up

Prerequisites

Before starting, make sure iOS and Android have been added to your Capacitor project.

npm i @capacitor/ios @capacitor/android
npx cap add android
npx cap add ios
npx cap sync

Adding the plugin

After getting your access token, install the plugin with

 npm install https://dyscan@github.com/Dyneti/dyscan-capacitor-plugin.git

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

Configuring build files

Several build files must be adjusted to download the native code.

iOS

In your Podfile (located under ios/App with Capacitor's default settings), add

source 'https://dyscan@github.com/dyneti/dyscan-podspec.git'

Then, inside the target for the application, add 'DyScan'. For example

target 'App' do
  capacitor_pods
  # Add your Pods here
  pod 'DyScan'
end

Next, modify Info.plist to include camera permissions if you haven't already done so. For example

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>NSCameraUsageDescription</key>
	<string>Used for card scans</string>
  <!-- other keys -->
</dict>
</plist>

Android

In the project-level build.gradle file (located at the root of the android directory), add Dyneti's Nexus repository with the 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)
            }
        }
    }
}

Next, in the app-level build.gradle (located at android/app/build.gradle), add the dependency

dependencies {
    // Other dependencies are here
    implementation 'com.dyneti.android.dyscan:dyscan:1.7.18'
}

Interfacing DyScan

Registering the plugin

import type { DyScanCapacitorPlugin } from "dyscan-capacitor-plugin";

import { registerPlugin } from "@capacitor/core";

const DyScanCapacitor = registerPlugin<DyScanCapacitorPlugin>("DyScanCapacitor");

Scanning cards

Before scanning cards, you must initialize DyScan with your API key.

await DyScanCapacitor.initDyScan({apiKey: "YOUR_API_KEY"});

You can now scan cards

const results = await DyScanCapacitor.scanCard({
  showCorners: false,
  showRotateButton: true,
  bgColor: "#ff0000", // red
  // other options
});

See below below for a complete set of options.

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

const supported = await DyScanCapacitor.isDeviceSupported();
if (supported) {
  // open DyScan card scan
  try {
    const results = await DyScanCapacitor.scanCard({
      showDynetiLogo: true,
    });
    // use the results
  } catch (err) {
    // the user cancelled
  }
} else {
  // alternate flow if device is not supported
}

API reference

These are also available as TypeScript types under src/definitions.ts.

Scan configuration

DyScanCapacitor.scanCard() takes an object with the following options. All parameters are optional.

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.	color*
`cornerCompletedColor`	The color to use in drawing the outline of the scan region when we have successfully scanned a card.	color*
`bgColor`	The color to use to obscure everything outside the scan region in order to draw the user’s attention to the scan region.	color*
`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`
`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.	color*
`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`
`iosHelperTextPosition`	The preset position of the helper text. Available values: top, center, bottom. Default: bottom	`string`

Scan results

DyScanCapacitor.scanCard() returns a promise that resolves to a results object with the following properties.

Parameter	Description	Type
`cardNumber`	The credit card number scanned.	`string`
`scanId`	A UUID identifying the scan.	`string`
`expiryMonth`	The expiration month scanned. The month is returned as a 1-2 character string, for example, "8" for August. If the expiration date was not found or is invalid, "0" is returned.	`string`
`expiryYear`	The expiration year scanned. The year is returned as a 0 or 4 character string, for example, "2027". If the expiration date was not found or is invalid, "0" is returned.	`string`

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.

Prerequisites​

Adding the plugin​

Configuring build files​

iOS​

Android​

Interfacing DyScan​

Registering the plugin​

Scanning cards​

API reference​

Scan configuration​

Scan results​

Color Representation​