@zerohash-sdk/capacitor

Capacitor plugin for embedding zerohash's Fund (deposit) flow into your iOS and Android app. It wraps the native zerohash iOS and Android SDKs and presents their Fund UI over your app.

Install

npm install @zerohash-sdk/capacitor
npx cap sync

Requirements

• iOS 15+
• Android minSdkVersion 24+

Setup

Android

The plugin's Android side pulls in the native zerohash Android SDK (com.github.zerohash-ext:zerohash-android), which is hosted on JitPack. Add JitPack to your app's Gradle repositories so it can be resolved:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

On newer Gradle setups that use dependencyResolutionManagement, add the same maven { ... } line to that block in settings.gradle instead.

iOS

No extra steps — npx cap sync wires the native SDK in automatically via Swift Package Manager.

Usage

import { Zerohash } from '@zerohash-sdk/capacitor';

// Register listeners before presenting.
await Zerohash.addListener('fundCompleted', (event) => {
  console.log('Deposit complete', event);
});
await Zerohash.addListener('close', () => console.log('Flow closed'));
await Zerohash.addListener('error', (e) => console.error(e.code, e.message));

// Present the Fund flow. The JWT is a short-lived Fund session token your
// backend mints from the zerohash API.
await Zerohash.presentFund({
  jwt: '<fund-session-jwt>',
  environment: 'production', // or 'sandbox'
  theme: 'system', // 'light' | 'dark' | 'system'
});

Use Zerohash.cancel() to dismiss the flow programmatically, Zerohash.isActive() to check whether it's currently presented, and Zerohash.removeAllListeners() when tearing down.

API

• presentFund(...)
• cancel()
• isActive()
• addListener('close', ...)
• addListener('error', ...)
• addListener('event', ...)
• addListener('fundCompleted', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

presentFund(...)

presentFund(options: PresentFundOptions) => Promise<void>

Present the Fund (deposit) flow. Rejects if a session is already active.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | PresentFundOptions |

cancel()

cancel() => Promise<void>

Dismiss the active Fund session, if any.

isActive()

isActive() => Promise<{ isActive: boolean; }>

Whether a Fund session is currently presented.

Returns: Promise<{ isActive: boolean; }>

addListener('close', ...)

addListener(eventName: 'close', listenerFunc: () => void) => Promise<PluginListenerHandle>

The user closed the Fund flow.

| Param | Type | | ------------------ | -------------------------- | | eventName | 'close' | | listenerFunc | () => void |

Returns: Promise<PluginListenerHandle>

addListener('error', ...)

addListener(eventName: 'error', listenerFunc: (event: ZerohashErrorEvent) => void) => Promise<PluginListenerHandle>

The Fund flow reported an error.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------- | | eventName | 'error' | | listenerFunc | (event: ZerohashErrorEvent) => void |

Returns: Promise<PluginListenerHandle>

addListener('event', ...)

addListener(eventName: 'event', listenerFunc: (event: GenericEvent) => void) => Promise<PluginListenerHandle>

A low-level event was forwarded from the Fund flow.

| Param | Type | | ------------------ | ------------------------------------------------------------------------- | | eventName | 'event' | | listenerFunc | (event: GenericEvent) => void |

Returns: Promise<PluginListenerHandle>

addListener('fundCompleted', ...)

addListener(eventName: 'fundCompleted', listenerFunc: (event: FundCompletedEvent) => void) => Promise<PluginListenerHandle>

A deposit completed successfully.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------- | | eventName | 'fundCompleted' | | listenerFunc | (event: FundCompletedEvent) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners registered by this plugin.

Interfaces

PresentFundOptions

| Prop | Type | Description | | ----------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | jwt | string | Short-lived Fund session JWT, minted by your backend from the zerohash API. | | environment | ZerohashEnvironment | Defaults to production. | | theme | ZerohashTheme | Defaults to system. | | allowList | string[] | Restrict the hosts the embedded WebView may load. Android only — passing it on iOS rejects the call. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

ZerohashErrorEvent

Payload of the error event.

| Prop | Type | | ------------- | ------------------- | | code | string | | message | string |

GenericEvent

Payload of the low-level event events forwarded from the Fund flow.

| Prop | Type | | ---------- | ---------------------------------------- | | type | string | | data | { [key: string]: unknown; } |

FundCompletedEvent

Payload of the fundCompleted event, emitted when a deposit completes. Any field the flow does not provide is null.

| Prop | Type | | -------------------- | --------------------------- | | depositAddress | string | null | | network | string | null | | assetSymbol | string | null | | amount | string | null | | transactionId | string | null | | fundId | string | null | | notionalAmount | string | null |

Type Aliases

ZerohashEnvironment

Which zerohash environment the Fund session runs against.

'sandbox' | 'production'

ZerohashTheme

Colour scheme for the Fund UI. system follows the device setting.

'light' | 'dark' | 'system'