191 lines
5.2 KiB
Markdown
191 lines
5.2 KiB
Markdown
## WebID Meta Plugin – React Native Proof of Concept
|
||
|
||
> **Disclaimer**
|
||
>
|
||
> This repository contains a proof-of-concept React Native plugin and an example mobile application intended solely for technical evaluation.
|
||
>
|
||
> Only the iOS integration has been verified to work at this time.
|
||
> The Android bridge and Android example setup exist but have not been tested and are expected to require additional adjustments before they can be considered functional.
|
||
>
|
||
> This repository is **experimental**, **not formally approved**, **not officially released**, **not published as an npm package**, and **not endorsed by WebID for
|
||
> production use**.
|
||
>
|
||
> The setup described below includes non-standard workarounds and temporary configuration adjustments that are required due to current
|
||
> tooling and dependency constraints.
|
||
|
||
---
|
||
|
||
# Android
|
||
## Prerequisites
|
||
- React Native version must be compatible with Kotlin 2.1
|
||
(Your host app + Gradle + Kotlin versions must match. If the native module uses Kotlin 2.1, the app must not force an incompatible Kotlin version.)
|
||
- Java 17
|
||
- Android Studio (includes Android SDK + Platform Tools / adb)
|
||
|
||
## Running the example app (Android)
|
||
|
||
### Create and Configure the `.env` File
|
||
|
||
Navigate to the example project and create the environment file:
|
||
|
||
```
|
||
cd example
|
||
cp .env.example .env
|
||
```
|
||
### Example:
|
||
|
||
```
|
||
URL=https://test.webid-solutions.de
|
||
USERNAME=your_username
|
||
API_KEY=your_api_key
|
||
CERT_BASE64=On ANdroid it need to be SHA-PINS
|
||
# SHA_PINS=sha256/AAAA...,sha256/BBBB...
|
||
```
|
||
|
||
Edit the .env file and add your username and API key.
|
||
|
||
### Install Dependencies
|
||
|
||
From the repository root:
|
||
|
||
```
|
||
yarn install
|
||
```
|
||
|
||
### Running the App
|
||
|
||
Then navigate to the iOS example project:
|
||
|
||
```
|
||
cd example/android
|
||
yarn start
|
||
```
|
||
In a second terminal:
|
||
```
|
||
cd example
|
||
yarn android
|
||
```
|
||
|
||
# iOS
|
||
|
||
## Prerequisites
|
||
|
||
- macOS with Xcode installed
|
||
- Node.js + Yarn
|
||
- CocoaPods
|
||
- Xcode Command Line Tools
|
||
|
||
---
|
||
|
||
## Running the example app (iOS)
|
||
|
||
### Create and Configure the `.env` File
|
||
|
||
Navigate to the example project and create the environment file:
|
||
|
||
```
|
||
cd example
|
||
cp .env.example .env
|
||
```
|
||
|
||
Edit the .env file and add your username and API key.
|
||
|
||
ℹ️ The provided CERT_BASE64 value is preconfigured for the test system and is valid until 2026-02-21.
|
||
In most cases, this value does not need to be modified if you intend to test against the test environment.
|
||
|
||
### Install Dependencies
|
||
|
||
From the repository root:
|
||
|
||
```
|
||
yarn install
|
||
```
|
||
|
||
This is required to install JavaScript dependencies and must be run before installing iOS pods or running the example app.
|
||
|
||
### Install Pods
|
||
|
||
|
||
Navigate to the iOS example project:
|
||
|
||
```
|
||
cd example/ios
|
||
pod install
|
||
```
|
||
|
||
### Post-install Notes
|
||
#### Duplicate PrivacyInfo.xcprivacy
|
||
|
||
After running pod install, the Xcode project may contain duplicate PrivacyInfo.xcprivacy files.
|
||
|
||
Steps to resolve:
|
||
|
||
- Open the Xcode workspace
|
||
- Remove the duplicate reference from the project navigator
|
||
|
||
### Special Configuration Notes
|
||
#### WebIdPayOnServer Dependency Handling
|
||
|
||
If the WebIdPayOnServer product is included, some of its transitive dependencies currently require manual configuration to avoid build and runtime issues.
|
||
|
||
iOS Deployment Target Adjustment
|
||
|
||
In the Pods Xcode project, set the iOS Deployment Target to iOS 13.0 for the following targets (Targets -> Select appropriate Target -> Build Settings -> iOS Deployment Target):
|
||
|
||
- KeychainAccess
|
||
|
||
- NVActivityIndicatorView
|
||
|
||
- SwiftyJSON
|
||
|
||
- XS2AiOS
|
||
|
||
⚠️ These targets may default to iOS 13.4 and must be adjusted manually.
|
||
|
||
#### Rationale:
|
||
|
||
The React Native version used by this project requires a minimum iOS version of 13.4
|
||
The libraries listed above are compiled from source during the Xcode build and therefore inherit the 13.4 minimum.
|
||
The WebID SDK, however, is compiled against iOS 13.0 and expects its dependencies to match this deployment target.
|
||
The example project’s Podfile explicitly forces these libraries to be built as dynamic frameworks, as required by the WebID SDK.
|
||
This mismatch otherwise leads to compiler errors or runtime crashes.
|
||
|
||
### Build the Plugin (optional)
|
||
|
||
From the repository root:
|
||
|
||
```
|
||
yarn prepare
|
||
```
|
||
|
||
This step builds the plugin and generates TypeScript definitions.
|
||
|
||
You only need to run this if:
|
||
|
||
- you are developing or modifying the plugin itself, or
|
||
- you encounter missing build artifacts under lib/
|
||
|
||
It is not required to run the example application.
|
||
|
||
### Running the App
|
||
|
||
Then navigate to the iOS example project:
|
||
|
||
```
|
||
cd example/ios
|
||
yarn ios
|
||
```
|
||
|
||
or run `yarn start` from the example dir.
|
||
Note: If you adjust the values in the .env file, you might need to run yarn start --reset-cache in order for these changes to be applied!
|
||
|
||
## Core files to inspect:
|
||
- react-native-web-id-meta-plugin.podspec
|
||
- example/ios/Podfile
|
||
- example/src/App.tsx
|
||
- ios/WebIdMetaPlugin.swift
|
||
|
||
## Additional notes
|
||
|
||
When the example Xcode project was set up initially, all WebID libraries as well as the transitive AhoyKit dependency had to be manually embedded as frameworks under Targets → Frameworks, Libraries and Embedded Content. In a CocoaPods setup, this should usually not be necessary, as it should be handled by the “[CP] Embed Pods Frameworks” build phase. However, in this case, the app always crashed because required dynamic libraries were missing when not adding them manually.
|