@capgo/capacitor-disqo

Capacitor bridge for Disqo's Android Pulse SDK.

What it does

• Wraps the Android Pulse SDK behind a Capacitor-friendly TypeScript API.
• Lets the host app initialize the SDK, start or stop tracking, deep-link into Android accessibility settings, and query service state.
• Bridges Pulse token callbacks back to JavaScript so the host app can keep using its own auth stack.

What it does not do

• It does not implement the client-facing onboarding UI or Google Play disclosures for you.
• It does not automate Play Console declarations, privacy policy updates, or the review video requirement.

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ |

Install

bun add @capgo/capacitor-disqo
bunx cap sync android

Android Notes

• The underlying Pulse SDK is Android-only.
• The host app is still responsible for the prominent disclosure screen, onboarding flow, Play Console declarations, privacy policy updates, and review video.
• This plugin ships default resource strings for:
  • accessibility_service_label
  • tracking_service_description
  • tracking_service_summary
• The host app can override those values in its own android/app/src/main/res/values/strings.xml.

Usage

import { Disqo } from '@capgo/capacitor-disqo';

await Disqo.addListener('accessTokenRequested', async ({ requestId }) => {
  const accessToken = await authStore.getPulseToken();
  await Disqo.resolveAccessTokenRequest({
    requestId,
    accessToken,
  });
});

await Disqo.addListener('refreshTokenRequested', async ({ requestId }) => {
  const refreshedSession = await authStore.refreshPulseToken();
  await Disqo.resolveRefreshTokenRequest({
    requestId,
    accessToken: refreshedSession.accessToken,
  });
});

const sdkStatus = await Disqo.getSdkStatus();
if (!sdkStatus.available) {
  throw new Error(sdkStatus.message);
}

await Disqo.initialize({
  apiUrl: 'https://pulse.example.internal',
  accessToken: await authStore.getPulseToken(),
});

await Disqo.start({
  userId: 'member-123',
});

await Disqo.openAccessibilitySettings();

const state = await Disqo.getServiceStateInfo();
console.log(state.enabled, state.state);

Example App

The bundled example-app/ is wired to:

• register the token callback listeners,
• reuse the token entered in the UI,
• initialize the bridge,
• start or stop tracking,
• open Android accessibility settings,
• and inspect the current service state.

API

• getSdkStatus()
• initialize(...)
• start(...)
• stop()
• updateAccessToken(...)
• clearAccessToken()
• getServiceStateInfo()
• isServiceEnabled()
• openAccessibilitySettings()
• refreshConfigs()
• send()
• resolveAccessTokenRequest(...)
• rejectAccessTokenRequest(...)
• resolveRefreshTokenRequest(...)
• rejectRefreshTokenRequest(...)
• getPluginVersion()
• addListener('accessTokenRequested', ...)
• addListener('refreshTokenRequested', ...)
• removeAllListeners()
• Interfaces

Capacitor API for the Disqo Pulse Android SDK.

The host app is still responsible for the onboarding UI, prominent disclosure, Google Play declarations, and privacy policy updates.

getSdkStatus()

getSdkStatus() => Promise<SdkStatusResult>

Check whether the Android Pulse SDK classes are available at runtime.

Returns: Promise<SdkStatusResult>

Since: 8.0.0

initialize(...)

initialize(options: DisqoInitializeOptions) => Promise<void>

Initialize the native bridge and register the token-provider proxy required by Pulse.

| Param | Type | | ------------- | ------------------------------------------------------------------------- | | options | DisqoInitializeOptions |

Since: 8.0.0

start(...)

start(options: DisqoStartOptions) => Promise<void>

Start Pulse tracking for the provided user.

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | DisqoStartOptions |

Since: 8.0.0

stop()

stop() => Promise<void>

Put Pulse into silent mode and clear user state.

Since: 8.0.0

updateAccessToken(...)

updateAccessToken(options: UpdateAccessTokenOptions) => Promise<void>

Replace the cached JWT used by the native provider bridge.

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | UpdateAccessTokenOptions |

Since: 8.0.0

clearAccessToken()

clearAccessToken() => Promise<void>

Clear the cached JWT. The next native lookup will ask JavaScript for a new token.

Since: 8.0.0

getServiceStateInfo()

getServiceStateInfo() => Promise<ServiceStateInfo>

Return a normalized snapshot of the current Pulse service state.

Returns: Promise<ServiceStateInfo>

Since: 8.0.0

isServiceEnabled()

isServiceEnabled() => Promise<ServiceEnabledResult>

Convenience boolean for the current Pulse service state.

Returns: Promise<ServiceEnabledResult>

Since: 8.0.0

openAccessibilitySettings()

openAccessibilitySettings() => Promise<void>

Open Android accessibility settings so the host app can drive the enablement flow.

Since: 8.0.0

refreshConfigs()

refreshConfigs() => Promise<void>

Force the native Pulse SDK to refresh its remote configuration.

Intended for internal debugging.

Since: 8.0.0

send()

send() => Promise<void>

Force the native Pulse SDK to send its queued events immediately.

Intended for internal debugging.

Since: 8.0.0

resolveAccessTokenRequest(...)

resolveAccessTokenRequest(options: ResolveAccessTokenRequestOptions) => Promise<void>

Resolve a pending accessTokenRequested callback with a fresh JWT.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------------- | | options | ResolveAccessTokenRequestOptions |

Since: 8.0.0

rejectAccessTokenRequest(...)

rejectAccessTokenRequest(options: RejectAccessTokenRequestOptions) => Promise<void>

Reject a pending accessTokenRequested callback.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------- | | options | RejectAccessTokenRequestOptions |

Since: 8.0.0

resolveRefreshTokenRequest(...)

resolveRefreshTokenRequest(options: ResolveRefreshTokenRequestOptions) => Promise<void>

Resolve a pending refreshTokenRequested callback.

Optionally includes a fresh JWT to cache immediately.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------------------- | | options | ResolveRefreshTokenRequestOptions |

Since: 8.0.0

rejectRefreshTokenRequest(...)

rejectRefreshTokenRequest(options: RejectRefreshTokenRequestOptions) => Promise<void>

Reject a pending refreshTokenRequested callback.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------------- | | options | RejectRefreshTokenRequestOptions |

Since: 8.0.0

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Get the native Capacitor plugin version.

Returns: Promise<PluginVersionResult>

Since: 8.0.0

addListener('accessTokenRequested', ...)

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

Listen for native access-token lookups.

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

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

addListener('refreshTokenRequested', ...)

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

Listen for native token-refresh requests.

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

Returns: Promise<PluginListenerHandle>

Since: 8.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove every active listener registered through the plugin.

Since: 8.0.0

Interfaces

SdkStatusResult

Result of checking whether the Disqo Pulse SDK is available on Android.

| Prop | Type | Description | Since | | -------------------- | --------------------- | ------------------------------------------------------------------------ | ----- | | available | boolean | Whether the required Android Pulse classes were found at runtime. | 8.0.0 | | missingClasses | string[] | Fully qualified class names that were missing when the status check ran. | 8.0.0 | | message | string | Human-readable guidance that explains how to fix an unavailable SDK. | 8.0.0 |

DisqoInitializeOptions

Initialization options for the Pulse bridge.

| Prop | Type | Description | Since | | ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- | ----- | | apiUrl | string | Base URL used by the Pulse SDK. | 8.0.0 | | accessToken | string | Optional cached JWT that can satisfy the SDK's first token lookup without a round-trip to JavaScript listeners. | 8.0.0 |

DisqoStartOptions

Start options for a Pulse session.

| Prop | Type | Description | Since | | ----------------- | ------------------- | --------------------------------------------------------------------- | ----- | | userId | string | User identifier forwarded to sdk.start(userId = ...). | 8.0.0 | | accessToken | string | Optional access token override to cache immediately before start(). | 8.0.0 |

UpdateAccessTokenOptions

Update the cached JWT used by the native token provider bridge.

| Prop | Type | Description | Since | | ----------------- | ------------------- | ------------------------------------------------ | ----- | | accessToken | string | Latest JWT returned by the host app auth system. | 8.0.0 |

ServiceStateInfo

Lightweight view of the current Pulse service state.

The SDK can enrich this state in future versions, so the plugin exposes both a normalized enabled boolean and a raw string snapshot from the underlying Android object.

| Prop | Type | Description | Since | | ------------- | -------------------- | --------------------------------------------------------------------------- | ----- | | enabled | boolean | Whether the accessibility-backed Pulse service is currently enabled. | 8.0.0 | | state | string | Best-effort normalized state name derived from the underlying Pulse object. | 8.0.0 | | raw | string | Raw string representation returned by the native Pulse state object. | 8.0.0 |

ServiceEnabledResult

Boolean wrapper for isServiceEnabled().

| Prop | Type | Description | Since | | ------------- | -------------------- | ------------------------------------------------ | ----- | | enabled | boolean | Whether the underlying Pulse service is enabled. | 8.0.0 |

ResolveAccessTokenRequestOptions

Successful response payload for resolveAccessTokenRequest().

| Prop | Type | Description | Since | | ----------------- | ------------------- | ------------------------------------------------------- | ----- | | requestId | string | Correlation id received in the original callback event. | 8.0.0 | | accessToken | string | Fresh JWT returned by the host app auth system. | 8.0.0 |

RejectAccessTokenRequestOptions

Error response payload for rejectAccessTokenRequest().

| Prop | Type | Description | Since | | --------------- | ------------------- | ------------------------------------------------------- | ----- | | requestId | string | Correlation id received in the original callback event. | 8.0.0 | | message | string | Optional reason returned to the native bridge. | 8.0.0 |

ResolveRefreshTokenRequestOptions

Successful response payload for resolveRefreshTokenRequest().

| Prop | Type | Description | Since | | ----------------- | ------------------- | ------------------------------------------------------------------------------------- | ----- | | requestId | string | Correlation id received in the original callback event. | 8.0.0 | | accessToken | string | Optional fresh JWT to cache before the native bridge retries its access-token lookup. | 8.0.0 |

RejectRefreshTokenRequestOptions

Error response payload for rejectRefreshTokenRequest().

| Prop | Type | Description | Since | | --------------- | ------------------- | ------------------------------------------------------- | ----- | | requestId | string | Correlation id received in the original callback event. | 8.0.0 | | message | string | Optional reason returned to the native bridge. | 8.0.0 |

PluginVersionResult

Plugin version payload.

| Prop | Type | Description | Since | | ------------- | ------------------- | ----------------------------------------------------------- | ----- | | version | string | Version identifier returned by the platform implementation. | 8.0.0 |

PluginListenerHandle

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

AccessTokenRequestedEvent

Access-token callback event emitted when the native Pulse provider needs a JWT.

| Prop | Type | Description | Since | | --------------- | ------------------- | --------------------------------------------------------------------------------------------------------- | ----- | | requestId | string | Correlation id that must be echoed back to resolveAccessTokenRequest() or rejectAccessTokenRequest(). | 8.0.0 |

RefreshTokenRequestedEvent

Refresh-token callback event emitted when the native Pulse provider asks the host app to refresh auth.

| Prop | Type | Description | Since | | --------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- | ----- | | requestId | string | Correlation id that must be echoed back to resolveRefreshTokenRequest() or rejectRefreshTokenRequest(). | 8.0.0 |