Skip to main content
Version: Next

Getting Started with React Native

The One Core SDK provides the core functionality of the Procivis One Wallet App. It is available as a React Native package, with native builds for iOS and Android.

This guide walks you through installing the SDK, writing the initialization code in TypeScript, and building for your target platform.

Prerequisites​

Before starting, ensure you have the following installed:

For iOS builds:

  • Xcode
  • CocoaPods, installed via Homebrew:
brew install cocoapods

For Android builds:

  • Android Studio

Install​

Add the SDK to your project dependencies:

yarn add @procivis/react-native-one-core

or

npm install @procivis/react-native-one-core

iOS​

After installing, run CocoaPods to wire up the native iOS dependencies:

cd ios
pod install

Configure​

The Core requires encryption keys to be provided at initialization. These are required for all issuance protocols, even those you do not intend to use, and for internal key storage.

The following is the minimum required configuration:

const config = {
  keyStorage: {
    INTERNAL: {
      params: {
        private: {
          encryption: "YOUR_ENCRYPTION_KEY",
        },
      },
    },
  },
  issuanceProtocol: {
    OPENID4VCI_FINAL1: {
      params: {
        private: {
          encryption: "YOUR_ENCRYPTION_KEY",
        },
      },
    },
    OPENID4VCI_FINAL1_HAIP: {
      params: {
        private: {
          encryption: "YOUR_ENCRYPTION_KEY",
        },
      },
    },
    OPENID4VCI_FINAL1_SWIYU: {
      params: {
        private: {
          encryption: "YOUR_ENCRYPTION_KEY",
        },
      },
    },
  },
};

Replace YOUR_ENCRYPTION_KEY with a 32-byte hex string. For development and testing, you can use the following value:

93d9182795f0d1bec61329fc2d18c4b4c1b7e65e69e20ec30a2101a9875fff7e
warning

This key is publicly known and must not be used in production. See Required Encryption Keys for guidance on generating production keys.

Initialize​

Before any SDK functions can be used, the Core must be initialized. Initialization is asynchronous and should be called once when the app mounts. Only one instance can be initialized; repeated calls will fail.

import { initializeCore, ONECore } from '@procivis/react-native-one-core';
import { useState, useEffect } from 'react';
import { Text, View } from 'react-native';

function App() {
  const [core, setCore] = useState<ONECore | null>(null);

  useEffect(() => {
    initializeCore(config)
      .then(setCore)
      .catch((e) => console.error('Initialization error', e.message, e));
  }, []);

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Text>{core ? 'Core initialized' : 'Initializing...'}</Text>
    </View>
  );
}

The core object returned by initializeCore is the binding through which all SDK functions are accessed. Pass it to any component or context that needs to call SDK methods.

Build and run​

iOS​

yarn ios

Or start the Metro bundler and build separately:

yarn start
yarn ios

Retrieve the compiled configuration​

The Core compiles your configuration together with its built-in defaults at initialization. To inspect the resulting configuration:

core.getConfig().then((config) => console.log(JSON.stringify(config, undefined, 2)));

This is useful for verifying your configuration and for understanding what options are available. Many SDK operations reference configuration values by key, and getConfig is the authoritative source for what is present in your running instance.

Troubleshooting​

"Already initialized" error after a file change

When you save a file, Metro hot-reloads the JavaScript bundle but the native Core persists in memory. The second call to initializeCore fails because the Core is already running. Config changes require a full restart — stop the Metro bundler and run yarn ios again rather than using the hot reload.

Generic "Initialization error" with no detail

If initialization fails with a generic error message, open React Native DevTools for the full error. In the Metro terminal, press j to open DevTools in your browser. The underlying error from the Core will appear in the console and will specify which configuration field is missing or invalid.

Build fails after adding the SDK

If the iOS build fails after installing the package, ensure CocoaPods is installed via Homebrew rather than via Ruby gems, and run:

cd ios
pod deintegrate
pod install

Then rebuild with yarn ios.