Subscriptions

The Privacy Interaction SDK supports real-time subscriptions that notify your application when resources change.

Rather than polling for updates, you can subscribe to events and react as scanning progresses, data holders are discovered, and analysis results are updated.

Virtual Presence Subscriptions

Subscribe to virtual presence state changes (e.g., transitions to SCANNING or NEEDS_REAUTH). Provide a unique subscription id to safely manage the subscription lifecycle.

Subscribe

Typescript

await privacyInteractionClient.subscribeToVirtualPresence(
  'my-subscription-id',
  {
    virtualPresenceUpdated(virtualPresence) {
      console.log('Virtual presence updated:', virtualPresence.id, virtualPresence.state)
    },
    connectionStatusChanged(state) {
      console.log('Connection state:', state)
      if (state === ConnectionState.Disconnected) {
        // Handle disconnection: consider re-subscribing
      }
    },
  },
)

The subscriber receives a full VirtualPresence object on each update.

Unsubscribe

Typescript

privacyInteractionClient.unsubscribeFromVirtualPresence('my-subscription-id')

Data Holder Subscriptions

Subscribe to data holder updates. Provide a unique subscription id to safely manage the subscription lifecycle.

Notifications are emitted as data holders are discovered or updated during scanning. Updates are delivered in batches.

Subscribe

Typescript

await privacyInteractionClient.subscribeToDataHolders(
  'my-subscription-id',
  {
    dataHoldersUpdated(dataHolders) {
      console.log(`${dataHolders.length} data holders updated`)
      for (const dh of dataHolders) {
        console.log(dh.name, dh.protectionState)
      }
    },
    connectionStatusChanged(state) {
      console.log('Connection state:', state)
    },
  },
)

The subscriber receives an array of DataHolder objects on each update batch.

Unsubscribe

Typescript

privacyInteractionClient.unsubscribeFromDataHolders('my-subscription-id')

Analysis Result Subscriptions

Subscribe to analysis result changes. Provide a unique subscription id to safely manage the subscription lifecycle.

Notifications are emitted when a new analysis result is created, or when an analysis result changes status (e.g., from PENDING to COMPLETE) or is updated with new data.

Subscribe

Typescript

await privacyInteractionClient.subscribeToAnalysisResult(
  'my-subscription-id',
  {
    analysisResultUpdated(update) {
      console.log('Analysis result updated:', update.id, update.status)
      if (update.status === 'COMPLETE') {
        // Fetch the full analysis result to get the data payload
        const full = await privacyInteractionClient.getAnalysisResult(update.id)
      }
    },
    connectionStatusChanged(state) {
      console.log('Connection state:', state)
    },
  },
)

The subscriber receives an AnalysisResultUpdate object; a lightweight notification containing the analysis result's metadata and status but not the full data payload. To retrieve the complete analysis data, call getAnalysisResult with the update's id.

Unsubscribe

Typescript

privacyInteractionClient.unsubscribeFromAnalysisResult('my-subscription-id')

Action Subscriptions

Subscribing to Action Updates

To receive real-time notifications each time an action's status changes, subscribe with a unique subscription identifier and an ActionSubscriber implementation. Your subscriber is notified whenever an action is updated — for example, when it transitions from IN_PROGRESS to COMPLETED_UNVERIFIED, or into REQUIRES_USER_INPUT.

Typescript

const subscriptionId = 'my-action-subscription'

await privacyInteractionClient.subscribeToActions(subscriptionId, {
  actionUpdated(action) {
    // An action's status has changed.
    // Inspect `action.status` to react to the update.
  },
  connectionStatusChanged(state) {
    if (state === ConnectionState.Disconnected) {
      // The subscription has disconnected; no further updates will be received
      // until it reconnects.
    }
  },
})

Unsubscribe

When you no longer need updates, unsubscribe using the same subscription identifier.

Typescript

privacyInteractionClient.unsubscribeFromActions('my-action-subscription')

Connection State

All subscription interfaces include a connectionStatusChanged callback that notifies you when the subscription connection state changes. Your subscriber will not receive resource update events until the connection state is CONNECTED, and will stop receiving them when it transitions to DISCONNECTED.

State	Description
CONNECTED	The subscription is actively connected and receiving updates.
DISCONNECTED	The subscription is not connected.

Subscription Best Practices

• Use unique subscription IDs. If you call a subscribe method with the same ID twice, the second call will replace the first subscription.

• Handle disconnections. Monitor the connectionStatusChanged callback and re-subscribe if the connection is lost unexpectedly.

• Unsubscribe when done. Always unsubscribe when your component unmounts or the user navigates away to avoid memory leaks and unnecessary network activity.

• Keep callbacks lightweight. Subscription callbacks are invoked on the main thread. Perform heavy processing asynchronously to avoid blocking the UI.

• Fetch full data on update. For analysis results, the subscription notification is lightweight. Fetch the full resource via getAnalysisResult when you need the complete data payload.