agora-appbuilder-core 4.1.19-beta.4 → 4.1.20

package/template/src/subComponents/screenshare/ScreenshareConfigure.tsx

@@ -11,7 +11,7 @@
 */
 import React, {useContext, useEffect, useRef, useState} from 'react';
 import {DispatchContext, PropsContext, UidType} from '../../../agora-rn-uikit';
-import {ScreenshareContext} from './useScreenshare';
+import {ScreenshareContext, ScreenshareStopOrigin} from './useScreenshare';
 import {
   getGridLayoutName,
   getPinnedLayoutName,
@@ -38,6 +38,15 @@ import {
   videoRoomScreenShareErrorToastSubHeading,
 } from '../../language/default-labels/videoCallScreenLabels';
 import {LogSource, logger} from '../../logger/AppBuilderLogger';
+import getUniqueID from '../../utils/getUniqueID';
+import {
+  getScreenshareSessionId,
+  getScreenshareError,
+  isUserCancelOrPermissionDenied,
+  SCREENSHARE_JOURNEY,
+} from './screenshareJourney';
+
+type ScreenshareAction = 'start' | 'stop';
 
 export const ScreenshareContextConsumer = ScreenshareContext.Consumer;
 
@@ -48,6 +57,13 @@ export const ScreenshareConfigure = (props: {
   const toastHeading = useString(videoRoomScreenShareErrorToastHeading)();
   const toastSubHeading = useString(videoRoomScreenShareErrorToastSubHeading)();
   const [isScreenshareActive, setScreenshareActive] = useState(false);
+  const activeScreenshareSessionIdRef = useRef<string | null>(null);
+  const stopScreenshareRef = useRef<
+    (
+      origin?: ScreenshareStopOrigin,
+      stopActorUid?: UidType,
+    ) => Promise<void> | void
+  >(() => {});
   const {dispatch} = useContext(DispatchContext);
   const rtc = useRtc();
   const {defaultContent, activeUids, pinnedUid, secondaryPinnedUid} =
@@ -157,10 +173,9 @@ export const ScreenshareConfigure = (props: {
   useEffect(() => {
     const unsubKickScreenshare = events.on(
       controlMessageEnum.kickScreenshare,
-      () => {
+      data => {
         //if screenscreen already active. then below method will stop the screen share
-        // @ts-ignore
-        rtc.RtcEngineUnsafe.startScreenshare();
+        stopScreenshareRef.current('remote_host_removal', data?.sender);
       },
     );
     const unsubScreenshareAttribute = events.on(
@@ -232,9 +247,47 @@ export const ScreenshareConfigure = (props: {
     };
   }, []);
 
-  const ScreenshareStoppedCallback = () => {
+  const ScreenshareStoppedCallback = (
+    stopOrigin: ScreenshareStopOrigin = 'unknown',
+    screenshareAttemptId = getUniqueID(),
+    screenshareSessionId = activeScreenshareSessionIdRef.current ||
+      'unknown-session',
+    stopActorUid?: UidType,
+  ) => {
+    const callbackStartedAt = Date.now();
+    logger.log(
+      LogSource.Internals,
+      'SCREENSHARE',
+      `${SCREENSHARE_JOURNEY} screen share stop callback received from RTC engine`,
+      {
+        action: 'stop',
+        stage: 'stop_callback',
+        outcome: 'started',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
+        screenShareUid,
+        stopOrigin,
+        stopActorUid,
+      },
+    );
     setScreenshareActive(false);
-    logger.debug(LogSource.Internals, 'SCREENSHARE', 'screenshare stopped.');
+    logger.log(
+      LogSource.Internals,
+      'SCREENSHARE',
+      `${SCREENSHARE_JOURNEY} screen share stop local active state set to inactive`,
+      {
+        action: 'stop',
+        stage: 'local_active_state',
+        outcome: 'success',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
+        screenShareUid,
+        stopOrigin,
+        stopActorUid,
+      },
+    );
     events.send(
       EventNames.SCREENSHARE_ATTRIBUTE,
       JSON.stringify({
@@ -243,6 +296,22 @@ export const ScreenshareConfigure = (props: {
       }),
       PersistanceLevel.Sender,
     );
+    logger.log(
+      LogSource.Internals,
+      'SCREENSHARE',
+      `${SCREENSHARE_JOURNEY} screen share stop RTM event sent to remote users`,
+      {
+        action: 'stop',
+        stage: 'rtm_event',
+        outcome: 'success',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
+        screenShareUid,
+        stopOrigin,
+        stopActorUid,
+      },
+    );
     setScreenShareData(prevState => {
       return {
         ...prevState,
@@ -253,6 +322,22 @@ export const ScreenshareConfigure = (props: {
         },
       };
     });
+    logger.log(
+      LogSource.Internals,
+      'SCREENSHARE',
+      `${SCREENSHARE_JOURNEY} screen share stop local context set to inactive`,
+      {
+        action: 'stop',
+        stage: 'screenshare_context',
+        outcome: 'success',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
+        screenShareUid,
+        stopOrigin,
+        stopActorUid,
+      },
+    );
     //if local user stopped the screenshare then change layout to grid
     //if user pinned somebody then don't triggerlayout change
     if (!pinnedUidRef.current.pinnedUid) {
@@ -265,6 +350,40 @@ export const ScreenshareConfigure = (props: {
         value: [0],
       });
     }
+    logger.log(
+      LogSource.Internals,
+      'SCREENSHARE',
+      `${SCREENSHARE_JOURNEY} screen share stop layout update completed when applicable`,
+      {
+        action: 'stop',
+        stage: 'layout_update',
+        outcome: 'success',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
+        screenShareUid,
+        stopOrigin,
+        stopActorUid,
+      },
+    );
+    logger.log(
+      LogSource.Internals,
+      'SCREENSHARE',
+      `${SCREENSHARE_JOURNEY} screen share stop callback handling completed`,
+      {
+        action: 'stop',
+        stage: 'complete',
+        outcome: 'success',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
+        screenShareUid,
+        stopOrigin,
+        stopActorUid,
+        elapsedMs: Date.now() - callbackStartedAt,
+      },
+    );
+    activeScreenshareSessionIdRef.current = null;
   };
 
   useEffect(() => {
@@ -275,54 +394,267 @@ export const ScreenshareConfigure = (props: {
     );
   }, []);
 
-  const executeRecordingQuery = (isScreenActive: boolean) => {
+  const executeRecordingQuery = async (
+    isScreenActive: boolean,
+    screenshareAttemptId: string,
+    screenshareSessionId: string,
+    stopOrigin: ScreenshareStopOrigin,
+    stopActorUid?: UidType,
+  ) => {
+    const action: ScreenshareAction = isScreenActive ? 'start' : 'stop';
     if (isScreenActive) {
       // If recording is going on, set the presenter query
       logger.log(
         LogSource.Internals,
         'SCREENSHARE',
-        'Recording is going on set presenter query',
+        `${SCREENSHARE_JOURNEY} screen share start recording presenter layout query started`,
+        {
+          action,
+          stage: 'recording_layout',
+          outcome: 'started',
+          screenshareAttemptId,
+          screenshareSessionId,
+          recordingActive: props.isRecordingActive,
+          screenShareUid,
+          stopOrigin,
+          stopActorUid,
+        },
       );
-      executePresenterQuery(screenShareUid);
+      await executePresenterQuery(screenShareUid);
     } else {
       logger.log(
         LogSource.Internals,
         'SCREENSHARE',
-        'Recording is NOT going on set normal query',
+        `${SCREENSHARE_JOURNEY} screen share stop recording normal layout query started`,
+        {
+          action,
+          stage: 'recording_layout',
+          outcome: 'started',
+          screenshareAttemptId,
+          screenshareSessionId,
+          recordingActive: props.isRecordingActive,
+          screenShareUid,
+          stopOrigin,
+          stopActorUid,
+        },
       );
       // If no recording is going on, set the normal query
-      executeNormalQuery();
+      await executeNormalQuery();
     }
+    logger.log(
+      LogSource.Internals,
+      'SCREENSHARE',
+      `${SCREENSHARE_JOURNEY} screen share ${action} recording layout query completed successfully`,
+      {
+        action,
+        stage: 'recording_layout',
+        outcome: 'success',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
+        screenShareUid,
+        stopOrigin,
+        stopActorUid,
+      },
+    );
   };
 
-  const stopScreenshare = () => {
+  const stopScreenshare = async (
+    stopOrigin: ScreenshareStopOrigin = 'unknown',
+    stopActorUid?: UidType,
+  ) => {
+    const screenshareAttemptId = getUniqueID();
+    const screenshareSessionId = getScreenshareSessionId(
+      'stop',
+      activeScreenshareSessionIdRef.current,
+      getUniqueID,
+    );
+    logger.log(
+      LogSource.Internals,
+      'SCREENSHARE',
+      `${SCREENSHARE_JOURNEY} screen share stop requested from ${stopOrigin}`,
+      {
+        action: 'stop',
+        stage: 'ui_request',
+        outcome: 'started',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
+        screenShareUid,
+        stopOrigin,
+        stopActorUid,
+      },
+    );
     if (!isScreenshareActive) {
+      logger.log(
+        LogSource.Internals,
+        'SCREENSHARE',
+        `${SCREENSHARE_JOURNEY} screen share stop skipped because screen share is already inactive`,
+        {
+          action: 'stop',
+          stage: 'precondition',
+          outcome: 'skipped',
+          screenshareAttemptId,
+          screenshareSessionId,
+          recordingActive: props.isRecordingActive,
+          screenShareUid,
+          stopOrigin,
+          stopActorUid,
+        },
+      );
       return;
     }
-    userScreenshare(false);
+    await userScreenshare(
+      false,
+      screenshareAttemptId,
+      screenshareSessionId,
+      stopOrigin,
+      stopActorUid,
+    );
   };
-  const startScreenshare = () => {
+  const startScreenshare = async () => {
+    const screenshareAttemptId = getUniqueID();
+    const screenshareSessionId = getScreenshareSessionId(
+      'start',
+      activeScreenshareSessionIdRef.current,
+      getUniqueID,
+    );
+    logger.log(
+      LogSource.Internals,
+      'SCREENSHARE',
+      `${SCREENSHARE_JOURNEY} screen share start requested from UI`,
+      {
+        action: 'start',
+        stage: 'ui_request',
+        outcome: 'started',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
+        screenShareUid,
+        stopOrigin: 'unknown',
+      },
+    );
     if (isScreenshareActive) {
+      logger.log(
+        LogSource.Internals,
+        'SCREENSHARE',
+        `${SCREENSHARE_JOURNEY} screen share start skipped because screen share is already active`,
+        {
+          action: 'start',
+          stage: 'precondition',
+          outcome: 'skipped',
+          screenshareAttemptId,
+          screenshareSessionId,
+          recordingActive: props.isRecordingActive,
+          screenShareUid,
+          stopOrigin: 'unknown',
+        },
+      );
       return;
     }
-    userScreenshare(true);
+    await userScreenshare(
+      true,
+      screenshareAttemptId,
+      screenshareSessionId,
+      'unknown',
+    );
   };
+  stopScreenshareRef.current = stopScreenshare;
 
-  const userScreenshare = async (isActive: boolean) => {
+  const userScreenshare = async (
+    isActive: boolean,
+    screenshareAttemptId: string,
+    screenshareSessionId: string,
+    stopOrigin: ScreenshareStopOrigin,
+    stopActorUid?: UidType,
+  ) => {
+    const startedAt = Date.now();
+    const action: ScreenshareAction = isActive ? 'start' : 'stop';
+    let stage = 'recording_layout';
+    let recordingLayoutFailed = false;
     logger.log(
       LogSource.Internals,
       'SCREENSHARE',
-      `${isActive ? 'starting' : 'stopping'}  screenshare`,
+      `${SCREENSHARE_JOURNEY} screen share ${action} workflow started`,
       {
-        channel,
+        action,
+        stage: 'journey',
+        outcome: 'started',
+        screenshareAttemptId,
+        screenshareSessionId,
+        recordingActive: props.isRecordingActive,
         screenShareUid,
-        encryption,
+        stopOrigin,
+        stopActorUid,
+        channel,
       },
     );
     try {
       if (props.isRecordingActive) {
-        executeRecordingQuery(isActive);
+        try {
+          await executeRecordingQuery(
+            isActive,
+            screenshareAttemptId,
+            screenshareSessionId,
+            stopOrigin,
+            stopActorUid,
+          );
+        } catch (recordingError) {
+          recordingLayoutFailed = true;
+          logger.error(
+            LogSource.Internals,
+            'SCREENSHARE',
+            `${SCREENSHARE_JOURNEY} screen share ${action} recording layout query failed; continuing screen share ${action}`,
+            recordingError,
+            {
+              action,
+              stage,
+              outcome: 'partial_failure',
+              screenshareAttemptId,
+              screenshareSessionId,
+              recordingActive: props.isRecordingActive,
+              screenShareUid,
+              stopOrigin,
+              stopActorUid,
+              ...getScreenshareError(recordingError),
+            },
+          );
+        }
+      } else {
+        logger.log(
+          LogSource.Internals,
+          'SCREENSHARE',
+          `${SCREENSHARE_JOURNEY} screen share ${action} recording layout query skipped because recording is inactive`,
+          {
+            action,
+            stage,
+            outcome: 'skipped',
+            screenshareAttemptId,
+            screenshareSessionId,
+            recordingActive: false,
+            screenShareUid,
+            stopOrigin,
+            stopActorUid,
+          },
+        );
       }
+      stage = 'rtc_operation';
+      logger.log(
+        LogSource.Internals,
+        'SCREENSHARE',
+        `${SCREENSHARE_JOURNEY} screen share ${action} calling RtcEngine.startScreenshare`,
+        {
+          action,
+          stage,
+          outcome: 'started',
+          screenshareAttemptId,
+          screenshareSessionId,
+          recordingActive: props.isRecordingActive,
+          screenShareUid,
+          stopOrigin,
+          stopActorUid,
+        },
+      );
       // @ts-ignore
       await rtc.RtcEngineUnsafe.startScreenshare(
         screenShareToken,
@@ -333,11 +665,56 @@ export const ScreenshareConfigure = (props: {
         rtc.RtcEngineUnsafe as unknown as IAgoraRTC,
         encryption as unknown as any,
         {encoderConfig: '1080p_2', optimizationMode: 'detail'},
+        'auto',
+        {
+          action,
+          screenshareAttemptId,
+          screenshareSessionId,
+          recordingActive: props.isRecordingActive,
+          screenShareUid,
+          stopOrigin,
+          stopActorUid,
+        },
+      );
+      logger.log(
+        LogSource.Internals,
+        'SCREENSHARE',
+        `${SCREENSHARE_JOURNEY} screen share ${action} RtcEngine.startScreenshare completed successfully`,
+        {
+          action,
+          stage,
+          outcome: 'success',
+          screenshareAttemptId,
+          screenshareSessionId,
+          recordingActive: props.isRecordingActive,
+          screenShareUid,
+          stopOrigin,
+          stopActorUid,
+        },
       );
       isActive && setScreenshareActive(true);
 
       if (isActive) {
+        activeScreenshareSessionIdRef.current = screenshareSessionId;
+        stage = 'local_active_state';
+        logger.log(
+          LogSource.Internals,
+          'SCREENSHARE',
+          `${SCREENSHARE_JOURNEY} screen share start local active state set to active`,
+          {
+            action,
+            stage,
+            outcome: 'success',
+            screenshareAttemptId,
+            screenshareSessionId,
+            recordingActive: props.isRecordingActive,
+            screenShareUid,
+            stopOrigin,
+            stopActorUid,
+          },
+        );
         // 1. Set local state
+        stage = 'screenshare_context';
         setScreenShareData(prevState => {
           return {
             ...prevState,
@@ -349,7 +726,24 @@ export const ScreenshareConfigure = (props: {
             },
           };
         });
+        logger.log(
+          LogSource.Internals,
+          'SCREENSHARE',
+          `${SCREENSHARE_JOURNEY} screen share start local context set to active`,
+          {
+            action,
+            stage,
+            outcome: 'success',
+            screenshareAttemptId,
+            screenshareSessionId,
+            recordingActive: props.isRecordingActive,
+            screenShareUid,
+            stopOrigin,
+            stopActorUid,
+          },
+        );
         // 2. Inform everyone in the channel screenshare is actice
+        stage = 'rtm_event';
         events.send(
           EventNames.SCREENSHARE_ATTRIBUTE,
           JSON.stringify({
@@ -359,23 +753,81 @@ export const ScreenshareConfigure = (props: {
           }),
           PersistanceLevel.Sender,
         );
+        logger.log(
+          LogSource.Internals,
+          'SCREENSHARE',
+          `${SCREENSHARE_JOURNEY} screen share start RTM event sent to remote users`,
+          {
+            action,
+            stage,
+            outcome: 'success',
+            screenshareAttemptId,
+            screenshareSessionId,
+            recordingActive: props.isRecordingActive,
+            screenShareUid,
+            stopOrigin,
+            stopActorUid,
+          },
+        );
       }
+      logger.log(
+        LogSource.Internals,
+        'SCREENSHARE',
+        `${SCREENSHARE_JOURNEY} screen share ${action} workflow ${
+          recordingLayoutFailed
+            ? 'completed with recording layout failure'
+            : 'completed successfully'
+        }`,
+        {
+          action,
+          stage: 'complete',
+          outcome: recordingLayoutFailed ? 'partial_success' : 'success',
+          screenshareAttemptId,
+          screenshareSessionId,
+          recordingActive: props.isRecordingActive,
+          screenShareUid,
+          stopOrigin,
+          stopActorUid,
+          elapsedMs: Date.now() - startedAt,
+        },
+      );
     } catch (e) {
+      const userCancelOrPermissionDenied = isUserCancelOrPermissionDenied(e);
       logger.error(
         LogSource.Internals,
         'SCREENSHARE',
-        'failed to start screen share',
-        e,
+        `${SCREENSHARE_JOURNEY} screen share ${action} workflow failed at ${stage}: ${
+          userCancelOrPermissionDenied
+            ? 'user cancelled picker or permission was denied'
+            : 'unexpected failure'
+        }`,
+        {
+          action,
+          stage,
+          outcome: userCancelOrPermissionDenied
+            ? 'user_cancel_or_permission_denied'
+            : 'failure',
+          screenshareAttemptId,
+          screenshareSessionId,
+          recordingActive: props.isRecordingActive,
+          screenShareUid,
+          stopOrigin,
+          stopActorUid,
+          elapsedMs: Date.now() - startedAt,
+          ...getScreenshareError(e),
+        },
       );
-      Toast.show({
-        leadingIconName: 'alert',
-        type: 'error',
-        text1: toastHeading,
-        text2: toastSubHeading,
-        visibilityTime: 1000 * 10,
-        primaryBtn: null,
-        secondaryBtn: null,
-      });
+      if (!userCancelOrPermissionDenied) {
+        Toast.show({
+          leadingIconName: 'alert',
+          type: 'error',
+          text1: toastHeading,
+          text2: toastSubHeading,
+          visibilityTime: 1000 * 10,
+          primaryBtn: null,
+          secondaryBtn: null,
+        });
+      }
     }
   };
 

package/template/src/subComponents/screenshare/__tests__/screenshareJourney.test.ts

@@ -0,0 +1,63 @@
+import {
+  getScreenshareError,
+  getScreenshareReleaseOrigin,
+  getScreenshareSessionId,
+  isUserCancelOrPermissionDenied,
+  SCREENSHARE_JOURNEY,
+} from '../screenshareJourney';
+
+describe('screenshare journey logging', () => {
+  it('uses the Datadog filter prefix', () => {
+    expect(SCREENSHARE_JOURNEY).toBe('[SCREENSHARE_JOURNEY]');
+  });
+
+  it.each([
+    [{code: 'PERMISSION_DENIED'}, true],
+    [{name: 'NotAllowedError'}, true],
+    [{message: 'AgoraRTCError PERMISSION_DENIED'}, true],
+    [{code: 'NETWORK_ERROR'}, false],
+  ])('classifies permission and cancellation errors', (error, expected) => {
+    expect(isUserCancelOrPermissionDenied(error)).toBe(expected);
+  });
+
+  it('normalizes SDK error details for structured logs', () => {
+    expect(
+      getScreenshareError({
+        code: 'PERMISSION_DENIED',
+        name: 'AgoraRTCError',
+        message: 'NotAllowedError: Permission denied by user',
+      }),
+    ).toEqual({
+      sdkErrorCode: 'PERMISSION_DENIED',
+      sdkErrorName: 'AgoraRTCError',
+      sdkErrorMessage: 'NotAllowedError: Permission denied by user',
+    });
+  });
+
+  it('reuses the active screen-share session ID when stopping', () => {
+    const createId = jest.fn(() => 'new-session-id');
+
+    expect(getScreenshareSessionId('stop', 'active-session-id', createId)).toBe(
+      'active-session-id',
+    );
+    expect(createId).not.toHaveBeenCalled();
+  });
+
+  it('creates a new screen-share session ID when starting', () => {
+    const createId = jest.fn(() => 'new-session-id');
+
+    expect(getScreenshareSessionId('start', null, createId)).toBe(
+      'new-session-id',
+    );
+    expect(createId).toHaveBeenCalledTimes(1);
+  });
+
+  it('classifies hidden-document release as page unload', () => {
+    expect(getScreenshareReleaseOrigin(undefined, 'hidden')).toBe(
+      'page_unload',
+    );
+    expect(getScreenshareReleaseOrigin(undefined, 'visible')).toBe(
+      'end_call_cleanup',
+    );
+  });
+});