Manage Virtual Presences

A virtual presence represents a connected user identity on an external platform (e.g., an email account).

Once connected, the platform service scans the account to discover data holders and perform privacy analyses.

Connecting a Virtual Presence

A virtual presence can be connected using either an OAuth authorization code (from a user-initiated login flow) or a pre-obtained refresh token.

Connect with Authorization Code

Use this method when your application has completed an OAuth flow and received an authorization code from the provider.

Typescript

try {
  const virtualPresence = await privacyInteractionClient.connectVirtualPresenceWithAuthCode(
    authCode,
  )
  // The virtual presence is now connected.
  // `virtualPresence.state` will be `CONNECTED` or `SCANNING`.
} catch (error) {
  // Handle/notify user of errors
}

Connect with Refresh Token

Use this method when your application already holds a valid refresh token for the provider.

First Tab

try {
  const virtualPresence = await privacyInteractionClient.connectVirtualPresenceWithRefreshToken({
    refreshToken: 'refresh-token-value',
    providerIdentity: '[e-mail]',
    scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
    expiresInEpochMs: 1700000000000, // optional
  })
  // The virtual presence is now connected.
} catch (error) {
  // Handle/notify user of errors
}

Input Parameters:

Parameter	Type	Required	Description
refreshToken	string	Yes	The refresh token value.
providerIdentity	string	Yes	The identity associated with the provider (e.g., email address).
scopes	string[]	No	OAuth scopes associated with the token.
expiresInEpochMs	number	No	Token expiration time in milliseconds since epoch.

Disconnecting a Virtual Presence

To disconnect a virtual presence and stop it from being scanned, call disconnectVirtualPresence with the virtual presence's unique identifier.

When a virtual presence is disconnected, its state will transition to INACTIVE. Any existing data holders and analysis results associated with the virtual presence will remain accessible.

First Tab

try {
  const virtualPresence = await privacyInteractionClient.disconnectVirtualPresence(
    virtualPresenceId,
  )
  // The virtual presence is now disconnected.
  // `virtualPresence.state` will be `INACTIVE`.
} catch (error) {
  // Handle/notify user of errors
}

Listing Virtual Presences

To retrieve all virtual presences for the signed-in user, use the listVirtualPresences method. Results are paginated.

A call to listVirtualPresences returns a ListOutput object containing a list of matching items and a nextToken to support pagination. If no results are found, the result will contain empty items. Always check the value of the returned nextToken—there are no more results to retrieve when nextToken is undefined.

Typescript

try {
  const listOutput = await privacyInteractionClient.listVirtualPresences({
    limit: 20,
    nextToken: undefined,
  })
  // `listOutput.items` contains the virtual presences.
  // Page through results if `listOutput.nextToken` is defined.
} catch (error) {
  // Handle/notify user of errors
}

Input Parameters:

Parameter	Type	Required	Description
limit	number	No	Maximum number of items to return. Will be defaulted if omitted.
nextToken	string	No	A pagination token from a previous call.

Virtual Presence States

A virtual presence transitions through the following states:

State	Description
CONNECTED	The virtual presence is active and connected to the provider.
SCANNING	The virtual presence is currently being scanned for data holders.
NEEDS_REAUTH	The virtual presence requires re-authentication with the provider. This will happen automatically when the refresh token expires, or when the user explicitly disconnects the Privacy Interaction application from their provider.
ERROR	The virtual presence encountered an error and is in a failed state.
INACTIVE	The virtual presence has been disconnected and is no longer active.

When a virtual presence enters the NEEDS_REAUTH state, your application should prompt the user to re-authenticate with the provider and call connectVirtualPresenceWithAuthCode or connectVirtualPresenceWithRefreshToken again.

Subscribing to Virtual Presence Updates

To receive real-time notifications when a virtual presence changes state, see Subscriptions.