https://github.com/animo/expo-ausweis-sdk
ausweis-sdk
https://github.com/animo/expo-ausweis-sdk
Last synced: 11 months ago
JSON representation
ausweis-sdk
- Host: GitHub
- URL: https://github.com/animo/expo-ausweis-sdk
- Owner: animo
- License: eupl-1.2
- Created: 2024-07-02T14:23:21.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-13T18:16:39.000Z (over 1 year ago)
- Last Synced: 2025-06-11T03:12:35.660Z (about 1 year ago)
- Language: TypeScript
- Size: 257 KB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
![Animo Logo]()
Expo - Ausweis SDK
Powered by
![Animo Logo]()
Getting started
|
Contributing
|
License
---
An [Expo Module](https://docs.expo.dev/modules/overview/) and [Expo Config Plugin](https://docs.expo.dev/guides/config-plugins/) to automatically set up and configure the [Ausweis App SDK](https://www.ausweisapp.bund.de/sdk/intro.html) for iOS & Android in Expo apps.
## Getting Started
Install the plugin and `expo-build-properties` using the following command. We need `expo-build-properties` to set the `minSdkVersion` for Android to at least 26, and enable `useLegacyPackaging` (see [App Bundle](https://www.ausweisapp.bund.de/sdk/android.html#app-bundle) in Ausweis SDK documentation).
```sh
# yarn
yarn add @animo-id/expo-ausweis-sdk expo-build-properties
# npm
npm install @animo-id/expo-ausweis-sdk expo-build-properties
# npm
pnpm install @animo-id/expo-ausweis-sdk expo-build-properties
```
Then add the plugin to your Expo app config (`app.json`, `app.config.json` or `app.config.js`) `plugins` array:
```json
{
"expo": {
"plugins": [
"@animo-id/expo-ausweis-sdk",
[
"expo-build-properties",
{
"android": {
"minSdkVersion": 26,
"useLegacyPackaging": true
}
}
]
]
}
}
```
> NOTE: the `expo` top level key is only needed in `app.json`. In `app.config.json`, `app.config.js` and `app.config.ts` the top level expo key is not present anymore.
And lastly, prebuild the application so the Ausweis SDK and Expo Module wrapper can be added as native dependency (If you aren't making any manual modification to the iOS and Android directories you can add them to the gitignore of your project and generate them on demand):
```sh
# yarn
yarn expo prebuild
# npm
npx expo prebuild
```
That's it, you now have Ausweis App SDK configured for your iOS and Android project.
## Usage
You can now import `@animo-id/expo-ausweis-sdk` in your application and use the methods from the SDK.
You can see the available [commands](https://www.ausweisapp.bund.de/sdk/commands.html#) and [messages](https://www.ausweisapp.bund.de/sdk/messages.html), which are typed in the `sendCommand` and `addMessageListener` methods.
```tsx
import { useEffect, useState } from 'react'
import { initializeSdk, sendCommand, addMessageListener } from '@animo-id/expo-ausweis-sdk'
export function App() {
const [isSdkInitialized, setIsSdkInitialized] = useState(false)
// Setup listener
useEffect(
addMessageListener((message) => {
console.log('received message', JSON.stringify(message, null, 2))
}).remove,
[]
)
// Initialize SDK
useEffect(() => {
initializeSdk()
.then(() => setIsSdkInitialized(true))
.catch((e) => {
console.log('error setting up', e)
})
}, [])
// Send command once SDK is initialized
useEffect(() => {
if (!isSdkInitialized) return
sendCommand({ cmd: 'GET_INFO' })
}, [isSdkInitialized])
return null
}
```
### Auth Flow
The package also exports an `AusweisAuthFlow` class that wraps the required logic for a general auth flow. An example of how to use the class can be found below.
To use the `AusweisAuthFlow` you need to configure it with the correct callbacks, and then call the `start()` method with the `tcTokenUrl`.
To cancel the flow, you can call the `cancel()` flow on the `AusweisAuthFlow` instance.
The Ausweis SDK only allows one flow to be active concurrently. It is important that you do not create multiple instances of the `AusweisAuthFlow`, as they will both receive the same events and messages, and will cause conflicts.
Note that this class is optimized for a simple auth flow and thus it may not fit all use cases. For example, the `SET_CAN` and `SET_PUK` commands are not supported (in case of too many failed PIN attempts). Attached simulator cards are also not supported. For more advanced use cases you can use the lower level commands and message listeners methods.
```tsx
import { AusweisAuthFlow } from '@animo-id/expo-ausweis-sdk'
import { useState } from 'react'
import { Button, StyleSheet, Text, View } from 'react-native'
export default function App() {
const [message, setMessage] = useState()
const [flow, setFlow] = useState()
const [cardAttachRequested, setCardAttachRequested] = useState(false)
const [isCardAttached, setIsCardAttached] = useState(false)
const [progress, setProgress] = useState(0)
const [requestedAccessRights, setRequestedAccessRights] = useState()
const [onAcceptAccessRights, setOnAcceptAccessRights] = useState<(accept: boolean) => void>()
const cancelFlow = () =>
flow
?.cancel()
.then(() => setFlow(undefined))
.catch((error) => setMessage(`Error canceling flow. ${error.message}`))
const runAuthFlow = async () => {
setMessage(undefined)
setFlow(
new AusweisAuthFlow({
debug: true,
// Can set to true to allow simulator cards. In this case `onEnterPin` and `onAttachCard` won't be called
allowSimulatorCard: false,
onEnterPin: ({ attemptsRemaining }) => {
// Mock incorrect pin entry
return attemptsRemaining === 1 ? '123456' : '123123'
},
onError: ({ message, reason }) => {
setFlow(undefined)
setCardAttachRequested(false)
setProgress(0)
setMessage(`${reason}: ${message}`)
},
onSuccess: () => {
setFlow(undefined)
setProgress(100)
setCardAttachRequested(false)
setMessage('Successfully ran auth flow')
},
onAttachCard: () => {
// iOS will already show the NFC scanner modal, but on Android we need
// use this callback to show the NFC scanner modal.
setCardAttachRequested(true)
},
onCardAttachedChanged: ({ isCardAttached }) => setIsCardAttached(isCardAttached),
onStatusProgress: ({ progress }) => setProgress(progress),
onRequestAccessRights: ({ effective }) =>
new Promise((resolve) => {
setRequestedAccessRights(effective)
setOnAcceptAccessRights(() => {
return (accept: boolean) => {
resolve({ acceptAccessRights: accept })
setOnAcceptAccessRights(undefined)
setRequestedAccessRights(undefined)
}
})
}),
}).start({
tcTokenUrl: 'https://test.governikus-eid.de/AusweisAuskunft/WebServiceRequesterServlet',
})
)
}
return (
{flow && Progress: {progress}%}
{flow && Is card attached: {isCardAttached ? 'Yes' : 'No'}}
{flow && cardAttachRequested && Please present your card to the NFC scanner}
{flow && requestedAccessRights && (
<>
Requested Access Rights:
{'\n -'}
{requestedAccessRights.join('\n- ')}
onAcceptAccessRights?.(true)} />
>
)}
{message && {message}}
)
}
```
## Contributing
Is there something you'd like to fix or add? Great, we love community contributions! To get involved, please follow our [contribution guidelines](./CONTRIBUTING.md).
## License
Expo Ausweis SDK is licensed under the [EUPL Version 1.2](./LICENSE). The AusweisApp SDK used by this Expo Module is also licensed under EUPL Version 1.2