@dlthub/react-native-ausweisapp2-wrapper v1.2.1

About this project

This library wraps and asyncifies the AusweisApp2 SDK by Governikus and enables react-native apps to support eID verification of German documents with NFC. The communication with the SDK is done by sending 'Commands' and reacting to 'Messages'. To orchestrate and simplify the API with the SDK through async functions, RxJS is used as a core driver of this library.

Requirements

To use this library, at least the following requirements have to be fulfilled:

• iOS 13.0
• Android 7 and SDK version 24

Getting Started

To add the library to your project, do the following:

1. Add react-native-ausweisapp2-wrapper to your project

$ yarn add react-native-ausweisapp2-wrapper

2. Prepare Cocoapod dependency

$ pod install

Android

1. Add the following to your android/app/build.gradle:

android {
  ...
  defaultConfig {
    ...
    packagingOptions {
        // Fixes build error: 2 files found with path 'lib/arm64-v8a/libc++_shared.so'
        pickFirst "lib/arm64-v8a/libc++_shared.so"
        // Needed for aab (Android App Bundle) creation.
        // The AusweisApp2 SDK will not work correctly without it
        // See also https://www.ausweisapp.bund.de/sdk/android.html#app-bundle
        jniLibs { useLegacyPackaging = true }
    }

See also https://www.ausweisapp.bund.de/sdk/android.html#app-bundle

2. Add those lines to your android/app/src/main/AndroidManifest.xml:

<manifest ... >
  <uses-permission android:name="android.permission.NFC"/>
  <uses-feature android:name="android.hardware.nfc" android:required="false" />
...

See also https://developer.android.com/guide/topics/connectivity/nfc/nfc#manifest

iOS

1. Add the following lines to your ios/cultureapp/Info.plist:

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>E80704007F00070302</string>
</array>

<key>NFCReaderUsageDescription</key>
<string>AusweisApp2 needs NFC to access the ID card.</string>

See also https://www.ausweisapp.bund.de/sdk/ios.html#info-plist

2. Add an entitlement file to your app, with the following content or enable the Near Field Communication Tag Reading capability in Xcode.

<?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>com.apple.developer.nfc.readersession.formats</key>
    <array>
      <string>TAG</string>
    </array>
  </dict>
</plist>

See also https://www.ausweisapp.bund.de/sdk/ios.html#entitlements and https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_nfc_readersession_formats

Usage

There are two main components used for interacting with the SDK. The CommandService, is used for basic functionality, such as starting and stopping the SDK and sending Commands to it. The WorkflowHelper, handles abstractions for the general identification workflow and adds other functionality that is not provided by the SDK (i.e. checking if NFC is enabled on Android).

Start SDK

To start the SDK, CommandService.start has to be called. To initialize the SDK and setup logging in one step, the WorkflowHelper.initializeAA2Sdk function is used.

Example:

WorkflowHelper.initializeAA2Sdk(true, 2)

Stop SDK

Stopping the SDK and NFC capability is done by calling the CommandService.stop method. This is also done when the application is reloaded by metro.

Send a Command to the SDK

With the CommandService Commands can be sent to the SDK. Commands that expect a Message as a response, are async functions that can be awaited.

Example:

async () {
  const info = await CommandService.getInfo()
  return info
}

In this case, we return the Info Message that will be sent as a reply by the AusweisApp2 SDK.

Some Commands need additional data to be sent to the SDK. The data is always provided using parameters.

async () {
  const reader = await CommandService.getReader("NFC")
  return reader
}

Optionally each command supports providing an options object as the last parameter that is used to configure the command. Currently only a milliseconds timeout is supported via msTimeout. This timeout is used for the maximum time that an async function waits for its Message response. If no Message response is provided in that time, a TimeoutError is thrown.

For examples on how to a basic identification flow works, have a look at https://www.ausweisapp.bund.de/sdk/workflow.html

Support, Feedback, Contributing

This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2023 SAP SE or an SAP affiliate company and kulturpass-app contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.