Skip to content

Collaboration

The PCoIP Ultra Collaboration feature enables a PCoIP session user to share their session with a remote guest collaborator using standard PCoIP Soft Clients. While connected the guest collaborator can view the screen output and hear the audio output of the shared PCoIP session.

When discussing this feature, we'll refer to the first user as the host collaborator, and the second user who joins the session as the guest collaborator.

Requirements

  • The Collaboration feature must be hosted on a Graphics Agent for macOS 22.07 or higher, with Collaboration enabled, and:

    • for Standard Agents, PCoIP Ultra CPU Offload must be enabled.
    • for Graphics Agents, one of the Ultra offload modes must be enabled: CPU Offload, GPU Offload, or Auto Offload can all be used.
  • Both the host and the guest collaborators must connect using a PCoIP Software Client 22.07 or higher (macOS, Windows, or Linux).

  • Both collaborators must connect using PCoIP software clients that support PCoIP Ultra. PCoIP Zero Clients and PCoIP Mobile Clients are not supported.

  • Collaboration sessions use a UDP port which must allow inbound traffic, both at the cloud provider network level and the local firewall.

    The default collaboration port is UDP 64172; if necessary, this can be changed. See Changing the collaboration session port for details.

  • For brokered collaboration, the PCoIP Connection Manager and PCoIP Security Gateway 22.07 or later is required, and:

    • If the brokered connection is via the PCoIP Security Gateway, then the PCoIP Security Gateway must be able to connect to the host on the configured collaboration port (UDP 64172 by default).

    • If the brokered connection is not via a PCoIP Security Gateway, then the guest collaborator's PCoIP client must be able to connect to the host on the configured collaboration port (UDP 64172 by default).

  • For unbrokered (direct) collaboration, the guest collaborator's PCoIP client must be able to connect to the host on the configured collaboration port (UDP 64172 by default).

Current Limitations

  • Only one guest collaborator can connect at a time.

  • Collaboration sessions support only one screen. The host collaborator should set their PCoIP Software Client to Fullscreen One Monitor mode prior to starting the collaboration session.

  • If the host and guest screen resolutions are different, the guest's screen will use scrollbars and letterboxing to display the shared content.

    If high performance client mode is enabled, and if the host's resolution is greater than the guest's, the guest's screen will be clipped instead.

  • By default, the guest collaborator's session can only view and listen to the shared session. Keyboard and mouse control can be shared with guest collaborators by enabling input control, described below.

  • Collaboration invites expire after 1 hour. The expiration time is not currently configurable.

  • Collaboration invites are single-use. Once a guest has connected, a new invite must be generated.

  • When a collaboration session is disconnected by the guest collaborator, the Stop Collaboration button in the Collaboration Management console may incorrectly remain enabled. If this occurs, click Stop Collaboration to reset the button state and allow a new collaboration session to be started.

  • Collaboration using PCoIP Ultra GPU Offload and Auto Offload are supported on the PCoIP Graphics Agent only. PCoIP Ultra GPU Offload and Auto Offload are not supported on the PCoIP Standard Agent.

  • HP Anyware Brokered Collaboration sessions are only supported when the session connection is made using the PCoIP Connection Manager 22.07 or later.

  • Collaboration Mouse Visibility only works when the host collaborator and all guest collaborators are using a PCoIP Client in Standard Client mode. The high performance client mode does not support mouse visiblity.

Enabling Collaboration

The PCoIP Ultra Collaboration feature is disabled by default. To enable this feature, both PCoIP Ultra CPU Offload and Collaboration must be activated on the Graphics Agent for macOS.

  1. Open a Terminal window and enter the following commands:

    sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.enable_collaboration 1
    sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.ultra 1
    
  2. The default collaboration port is UDP 64172. If you need to change it, provide the new port number with an additional Terminal command:

    sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.collaboration_udpport <new_collaborator_port>
    
  3. Reboot the Mac.

See Configuration Guide - Configurable Settings for more detailed information on setting configuration values.

Hosting a Collaboration Session

To host a PCoIP Ultra Collaboration session, the host collaborator starts a PCoIP session, then generates an invitation token that is passed to the guest collaborator:

  1. Connect to a PCoIP session with PCoIP Ultra CPU Offload enabled.

  2. Open the Collaboration Management Console by pressing +spacebar and typing PCoIP Collaboration, or by locating PCoIP Collaboration app in the Applications folder.

  3. In the Collaboration Management Console, click Request a new invite.

    Request new invite

    Generating a new link and invite code

    If you have already generated an invite but need to create a new one, click Stop Collaboration to invalidate the first invite and then click Start Collaboration to create a new one.

  4. The Collaboration Management Console provides two pieces of information that are used to invite the guest collaborator:

    • Link: The guest collaborator will use this link to join your session. This URI may be opened on any Mac, Windows or Linux machine with a PCoIP Software Client 21.03 or newer.

      This URI contains a collaboration token which will expire 1 hour after the Host session was established. The generated URI can only be used once. If the token expires, a new invite must be generated.

    • Invite Code: This is a 6-digit code that confirms the identity of the individual connecting to the collaboration session. A new code is generated along with each new token.

    Collaboration invite code

    Note: Collaboration features have version requirements

    Collaboration features such as Mouse Visibility are only available with PCoIP agents and software clients 22.07 or newer.

  5. Share the PCoIP URI and the Collaboration Invitation Code with the guest collaborator.

    Security best practice

    We recommend that these two pieces of information be shared with the guest user in separate communications, reducing risk in the event that a message is inadvertently sent, forwarded, or intercepted by a third party.

  6. When the guest collaborator attempts to join the session, the Collaboration Management Console will display options to accept or reject the connection.

    Accept or reject the invite

  7. Click Accept to start the collaboration session. Click Decline to deny the request. Whether you accept the request or not, the invite has been used and is now disabled. Subsequent attempts will require a new invite.

Joining a Collaboration Session

The guest collaborator can join the session once they have received the PCoIP URI and the Collaboration Invitation code.

  1. Open a web browser and go to the PCoIP URI shared with you (you may be able to click this link directly, depending on how it was shared with you).

  2. The web browser will warn you that the link is attempting to open the PCoIP Client application. Allow the browser to open the PCoIP client.

  3. When the PCoIP client opens, it will prompt you for your name and the Collaboration Invitation Code. The value you enter for your name is used to tell the host who is joining; the Collaboration Invitation Code is the six digit number provided by the host. Enter both values and click Submit.

  4. Once the host collaborator accepts your connection request, the Collaboaration screen share will start.

  5. To leave the collaboration session, select Connection > Disconnect from the PCoIP Client menu.

Collaborator Input Control

Collaborator input control allows the guest collaborator to control the host's desktop by using their mouse, keyboard, or other input device. This feature is disabled by default, and must be enabled on the host's PCoIP agent.

Warning: Input Control cannot be turned off in-session

In the current release, input control is enabled and disabled on the host's PCoIP agent prior to establishing a session. When this mode is enabled, guest collaborators who join a session will immediately be able to control the host's desktop, subject to the limitations described below. This access can only be disabled by ending the session.

This limitation will be removed in a future release.

Taking Control

A collaborator who has input control can release it by idling—stopping all keyboard, mouse, and pointer activity—for a short time. Once the control timeout has elapsed, the floor is open, and whichever collaborator provides input next takes control.

By default, the control timeout is 3 seconds. The timeout value can be configured when enabling the input control feature, described below.

For example: the host has initial control of the session. In order to give control to the guest, the host takes their hands off the keyboard and mouse for three seconds, allowing the control timeout to pass. The guest collaborator then moves their mouse, which gives them control. To give control back to the host, the guest takes their hands off their keyboard and mouse for three seconds. This exchange continues as long as desired.

Important: The host always has control of their PCoIP client's in-session menu

The host always has control of their PCoIP client's in-session menu. If the host is unable to reclaim session input control for any reason, they can disconnect the PCoIP session using the in-session menu option. When the host disconnects from the session, the guest is immediately disconnected.

To enable Collaborator Input Control:

  1. Open a terminal window on the host's PCoIP agent machine.

  2. Type the following:

    sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.enable_collaboration_input_control 1
    
  3. Optionally, provide a custom input control timeout value (specified in milliseconds; 3000ms is 3 seconds):

    sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.collaboration_input_control_timeout <timeout_value_in_ms>
    
  4. Restart the machine.

To disable Collaborator Input Control:

  1. Open a terminal window on the host's PCoIP agent machine.

  2. Type the following:

    sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.enable_collaboration_input_control 0
    
  3. Restart the machine.

Ending a Collaboration Session

The collaboration session will end when the host stops collaborating, or if either the host or guest collaborator disconnects their PCoIP connection.

To stop collaborating with a guest:

In the Collaboration Management Console, click the Stop Collaboration button. This ends the collaboration session. Once the session ends, the host can request a new invite and repeat the process above to start a new session.

Stop collaborating

Changing the Collaboration Session Port

The default UDP Port for collaborator sessions is 64172. If necessary, you can change this port.

To change the Collaboration session port:

  1. Open a Terminal window, and type the following command specifying the new UDP port number to use:

    sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.collaboration_udpport <new_collaborator_port>
    
  2. Reboot the machine.

Mouse Visibility

Collaboration Mouse Visibility allows collaborators to see the other collaborator's mouse cursor movements. This feature is only available when both collaborators are using a PCoIP Software Client 22.07 or newer, and the Graphics Agent for macOS is version 22.07 or later.

Currently, both host and guest collaborators must be using PCoIP Software clients running in standard client mode. High performance client mode does not currently support the Mouse Visibility.

Future releases will add the ability for the Guest Collaborator to take control of the session mouse and keyboard.