UserView Logo
UserViewby Upscope

Documentation

Listening for Events

You can listen for SDK events using Upscope.addListener(). Always remove subscriptions on cleanup to avoid memory leaks.

import Upscope from '@upscopeio/react-native-sdk';

Listening for Events

import React, { useEffect } from 'react';
import Upscope from '@upscopeio/react-native-sdk';

function MyComponent() {
  useEffect(() => {
    const subs = [
      Upscope.addListener('connectionStateChanged', ({ state, error }) => {
        switch (state) {
          case 'inactive':
            console.log('Inactive');
            break;
          case 'connecting':
            console.log('Connecting...');
            break;
          case 'connected':
            console.log('Connected');
            break;
          case 'reconnecting':
            console.log('Reconnecting...');
            break;
          case 'error':
            console.log('Error:', error?.message);
            break;
        }
      }),

      Upscope.addListener('sessionStarted', ({ agentName }) => {
        console.log(`Session started with ${agentName ?? 'an agent'}`);
      }),

      Upscope.addListener('sessionEnded', ({ reason, error }) => {
        switch (reason) {
          case 'userStopped':
            console.log('User ended session');
            break;
          case 'agentStopped':
            console.log('Agent ended session');
            break;
          case 'timeout':
            console.log('Session timed out');
            break;
          case 'error':
            console.log('Session error:', error?.message);
            break;
        }
      }),

      Upscope.addListener('customMessageReceived', ({ message, viewerId }) => {
        console.log(`Message from ${viewerId}: ${message}`);
      }),

      Upscope.addListener('error', ({ code, message }) => {
        console.log(`Error: ${code} - ${message}`);
      }),

      Upscope.addListener('viewerJoined', (viewer) => {
        console.log(`Viewer joined: ${viewer.name ?? viewer.id}`);
      }),

      Upscope.addListener('viewerLeft', ({ viewerId }) => {
        console.log(`Viewer left: ${viewerId}`);
      }),

      Upscope.addListener('viewerCountChanged', ({ count }) => {
        console.log(`Viewers: ${count}`);
      }),

      Upscope.addListener('remoteControlStateChanged', ({ state }) => {
        console.log(`Remote control: ${state}`);
      }),

      Upscope.addListener('fullDeviceSharingStateChanged', ({ state }) => {
        console.log(`Full-device sharing: ${state}`);
      }),

      Upscope.addListener('fullDeviceRequest', ({ requestId }) => {
        // Respond before the system permission prompt appears.
        // Pass true to proceed to the prompt, false to stay in in-app mode.
        const userWantsFullDevice = true;
        Upscope.respondToFullDeviceRequest(requestId, userWantsFullDevice);
      }),
    ];

    return () => subs.forEach((sub) => sub.remove());
  }, []);

  return null;
}

Event Reference

EventPayloadDescription
connectionStateChanged{ state, error? }Called when the connection state changes. error is present when state is "error".
sessionStarted{ agentName }A screen sharing session has started. agentName is the agent's display name if available.
sessionEnded{ reason, error? }A session has ended. reason indicates why (userStopped, agentStopped, timeout, or error).
customMessageReceived{ message, viewerId }A custom message was received from a viewer.
error{ code, message }An SDK error occurred.
viewerJoinedViewerA viewer/agent joined the session. The Viewer includes id, name, screen dimensions, and focus state.
viewerLeft{ viewerId }A viewer/agent left the session.
viewerCountChanged{ count }The total number of active viewers changed.
remoteControlStateChanged{ state }Whether an agent currently has remote control of the device (ability to tap and scroll) changed. state is 'inactive' | 'active'. Independent of the session being active.
fullDeviceSharingStateChanged{ state }Whether full-device (entire screen) sharing is currently running changed, as opposed to default in-app screen sharing. state is 'inactive' | 'active'.
fullDeviceRequest{ requestId }An agent requested full-device screen sharing, before the system permission prompt appears. Respond with Upscope.respondToFullDeviceRequest(requestId, accept) to allow (continues to the system prompt) or decline (stays in in-app mode). If you don't subscribe, the SDK proceeds to the system prompt directly.
shortIdChanged{ shortId }The visitor's short ID was assigned or changed.
lookupCodeChanged{ lookupCode }The lookup code was issued or changed.

Using Hooks Instead

For most use cases, the reactive hooks are simpler than manual event subscriptions. See SDK Functions for details on useConnectionState(), useSessionState(), and other hooks.