Skip to content

Integration

  1. Create a new Android project.
  2. Import the framework (nfc-scanner.aar) as a module (New... > Module > Import .JAR/.AAR Package) into your app.
  3. Add the following dependency: implementation project (":nfc-scanner") (same name as aar) to the app gradle file.
  4. Implement the Interface named IVDNfcScanner.
  5. Add the following dependencies to the app gradle file:

            implementation 'org.jmrtd:jmrtd:0.7.19'
            implementation 'net.sf.scuba:scuba-sc-android:0.0.22'
            implementation 'com.madgag.spongycastle:prov:1.58.0.0'
            implementation 'edu.ucar:jj2000:5.2'
            implementation 'com.github.bumptech.glide:glide:4.16.0'
    

  6. If the minifyEnabled in your gradle project is true, you can safely add the next dontwarn directives to the proguard file:

      -dontwarn org.junit.**
      -dontwarn junit.**
    

Note

In the UI mode there is an established maximum number of attempts (5 attempts). If the user can't finish the process in 5 attempts the SDK is finished. In the without UI there aren't maximum number of attempts, this decisions must be done by the integrator of the SDK.

Disabling allowBackup

By default the SDK allows the application to participate in the backup infrastructure, this behaviour can be altered by adding android:allowBackup="false" to the application tag in the manifest file from the created application.

When this directive has been overridden tools:replace="android:allowBackup" must be added to the application tag as well, including adding the tools namespace xmlns:tools="http://schemas.android.com/tools" to the manifest tag.

See this page for more details.

Example of usage with UI

import com.dasnano.vdnfcscanner.VDNfcScanner;
import com.dasnano.vdnfcscanner.other.VDNfcEnums;

public class SomeClass implements VDNfcScanner.IVDNfcScanner ...

...

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.your_layout);
    // Start SDK. A delegate to receive delegated methods (this) and a Context to debug or use files (getApplicationContext() or this in a activity) are needed.
    if (!VDNfcScanner.isStarted()) {
       Map<String, String> configuration = new HashMap<>();
       configuration.put("closebutton", "YES");
       VDNfcScanner.start(this, getApplicationContext(), VDNfcEnums.VDNfcDocumentType.VDNFC_SPAIN_DNI_30, configuration);
    }
}

...

// In another place you can stop the process.
private boolean someMethod() {
    // Stop it whenever you want.
    VDNfcScanner.stop(someContext);
}

// In other place when the SDK is almost started you have to set the NFC pins and keys.
// The pins are the password of the document to read the information. This step is necessary in the mode with UI.
private void someMethod() {
   List<String> NfcKeys = VDNfcScanner.getNfcKeys();
   // The NFC keys which are wanted to be read are introduced. If null passed, all the information is retrieved.
   //Deprecated -->
   VDNfcScanner.setNfcKeysAndPins(cardID, dateOfBirth, dateOfExpiry, NfcKeys);
   //New method -->
   NfcPins nfcPins = new NfcPins(cardID, dateOfBirth, dateOfExpiry, CAN , true);
   VDNfcScanner.setNfcKeysAndPins(nfcPins, NfcKeys);
}

...

// Interface methods

@Override
public void VDNfcDataCaptured(Map<String, String> map) {
    // Do as needed with the Map<String, String> of the NFC information.
}

@Override
public void VDNfcValidationDataCaptured(Map<String, String> nfcData, ArrayList<DGHashInfo> hashesInfo) {
    // Do as needed with the Map<String, String> of the NFC validation data and ArrayList<DGHashInfo> of hashes info.
}

@Override
public void VDDocumentSigningCertificateCaptured(VDDocumentSigningCertificate certificate) {
    // Do as needed with the VDDocumentSigningCertificate of the document's DSC.
}

@Override
public void VDNfcScannerFinished(boolean b) {    
  // NFC capture finished. If processFinished is true, it means that all the required information has been read. If it is false, it means that the user has closed the SDK
  // or the user can't finish successful the process in the established number of attempts.
}

@Override
public void VDNfcError(VDNfcEnums.VDNfcError error) {
  // This method isn't used in the mode with UI.
}
Workflow Workflow with errors
The next diagram represents de current workflow of the framework. Some method's names may be shortened due to legibility issues. When the framework has UI, the different NFC errors are managed by the framework and different interface changes occur when any error happens.
Workflow

Example of usage without UI

import com.dasnano.vdnfcscanner.VDNfcScanner;
import com.dasnano.vdnfcscanner.other.VDNfcEnums;

public class SomeActivity implements VDNfcScanner.IVDNfcScanner ...

...

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.your_layout);
    // Start SDK. A delegate to receive delegated methods (this) and a Context to debug or use files (getApplicationContext() or this in a activity) are needed.
    if (!VDNfcScanner.isStarted()) {
       VDNfcScanner.startWithoutUI(this, getApplicationContext(), VDNfcEnums.VDNfcDocumentType.VDNFC_PASSPORT);
    }
}

...

// In another place you can stop the process.
private boolean someMethod() {
    // Stop it whenever you want.
    VDNfcScanner.stop(someContext);
}

// In other place when the SDK is almost started you have to set the NFC pins and keys.
// The pins are the password of the document for read the information. This step is not necessary in the mode without UI.
// If no values are provided, an error is delegated when the NFC chip is detected.
private void someMethod() {
   List<String> NfcKeys = VDNfcScanner.getNfcKeys();
   // It are passed the NFC keys that are wanted to be retrieved. If is null all information is retrieved.
   //Deprecated -->
   VDNfcScanner.setNfcKeysAndPins(cardID, dateOfBirth, dateOfExpiry, NfcKeys);
   //New method -->
   NfcPins nfcPins = new NfcPins(cardID, dateOfBirth, dateOfExpiry, CAN , true);
   VDNfcScanner.setNfcKeysAndPins(nfcPins, NfcKeys);
}

// Activity methods

// The activity to receive the NFC intent is enabled.
@Override
protected void onResume() {
    super.onResume();
    VDNfcScanner.enableNfcActivity(this);
}

// The activity to receive the NFC intent is disabled.
@Override
protected void onPause() {
    super.onPause();
    VDNfcScanner.disableNfcActivity(this);
}

// If the received intent is a NFC intent and the SDK is started, the reading can be done.
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    if (NfcAdapter.ACTION_TAG_DISCOVERED.equals(intent.getAction()) && VDNfcScanner.isStarted()) {
        VDNfcScanner.setNfcIntentAndStartReading(intent);
    }
}

...

// Interface methods

@Override
public void VDNfcDataCaptured(Map<String, String> map) {
    // Do as needed with the Map<String, String> of the NFC information.
}

@Override
public void VDNfcValidationDataCaptured(Map<String, String> nfcData, ArrayList<DGHashInfo> hashesInfo) {
    // Do as needed with the Map<String, String> of the NFC validation data and ArrayList<DGHashInfo> of hashes info.
}

@Override
public void VDDocumentSigningCertificateCaptured(VDDocumentSigningCertificate certificate) {
    // Do as needed with the VDDocumentSigningCertificate of the document's DSC.
}

@Override
public void VDNfcScannerFinished(boolean b) {    
  // NFC capture finished. If processFinished is true, it means that all the required information has been read. If it is false, it means that the user has closed the SDK.
  // In this mode there aren't maximum number of attempts.
}


@Override
public void VDNfcError(VDNfcEnums.VDNfcError error) {
  // Do as needed with the error.
}
Workflow Workflow with errors
The next diagram represents de current workflow of the framework. Some method's names may be shortened due to legibility issues. The next diagram represents the current workflow of the framework if some error occurred.
Workflow Workflow

Third party libraries

  • jmrtd 0.7.19 (main page). It is an open source Java implementation of the Machine Readable Travel Document (MRTD) standards as specified by the International Civil Aviation Organization (ICAO)
  • scuba 0.0.22 (main page). SCUBA is a Java based framework for programming smart card aware host applications
  • spongycastle 1.58.0 (main page). Spongy Castle is the stock Bouncy Castle libraries with a couple of small changes to make it work on Android
  • jj2000 5.2 (main page). Support of compression in Grib2 files in netCDF-java and TDS
  • Glide: 4.16.0 (main page). Used for image loading.