WebIdMetaPluginReactNative/README.md

## 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.