Collaboration

PCoIP Ultra Collaboration enables a PCoIP session user to share their session with multiple remote collaborators using Anyware Software Clients.

Up to 5 collaborators can join an ongoing PCoIP session using the same invitation. The maximum number of collaborators can be reduced by configuring the agent.

While connected, all collaborators can view and hear the session owner's screens and audio, and see the controlling collaborator's mouse movements. If permitted by the session owner, they can also share control of the session owner's keyboard and mouse using input control.

During a collaboration session, all of the session owner's desktop screens may be shared depending on the session owner's Anyware software client display settings. See Understanding Display Behavior for more information.

Collaboration Requirements

PCoIP Ultra Collaboration is supported by all Anyware agents. Anyware software clients that support PCoIP Ultra can participate in collaboration sessions (all Anyware software clients 23.04 and higher meet this requirement).

Some collaboration features have specific version requirements for Anyware agents and Anyware software clients; these are noted below.

Feature Version Requirements

PCoIP Ultra Collaboration features depend on coordinated updates in Anyware agents and Anyware clients, so review these requirements carefully to ensure the features you need are supported by your system. We strongly recommend using the latest versions of both Anyware agent and Anyware client.

Network Requirements

Each collaborator connection requires a separate UDP port. These ports are assigned in a range that begins with the configured UDP port (by default, 64172), and increments with each additional collaborator. All ports in this range must be open, both at the cloud provider network level and the local firewall at the host.

For example, using the default configuration and hosting three collaborators, the system would require inbound UDP ports 64172, 64173, and 64174 to be open.

You can change the starting port number if desired. If you change the configured starting UDP port, adjust these ranges and ensure your host firewall configuration allows traffic on the new ports.

For direct connections, or brokered connections that do not use a Security Gateway, each collaborator's Anyware client must be able to reach these ports. For brokered connections using a Security Gateway, only the Security Gateway must be able to reach them.

Enabling Collaboration

PCoIP Ultra Collaboration is enabled, disabled, and configured on the Anyware agent machine. It is disabled by default, and must be enabled by activating both PCoIP Ultra and Collaboration on the remote desktop.

The following steps apply to the session owner's desktop machine.

To enable PCoIP Ultra Collaboration:

1. Open a terminal window.

2. If PCoIP Ultra is not already enabled, enable it by specifying a PCoIP Ultra Offload mode:

       sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.ultra <offload_mode>
   

   ...where <offload_mode> is 1, 2, or 3:

   PCoIP Ultra mode	Write this value
   CPU Offload	1
   GPU Offload	2
   Auto Offload	3

3. In the terminal window, enter the following command to enable collaboration:

   sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.enable_collaboration 1
   

4. Optional: To enable Collaboration Input Control, stay in the Terminal window and follow the instructions in Enabling Input Control below.

5. Optional: You can change the UDP starting port if needed (the default starting port is UDP 64172). To set a new starting port number, run an additional Terminal command:

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

   ...where <new_collaborator_port> is your new starting port number.

6. Restart the Mac.

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

Input Control

Collaborator input control allows collaborators to use their own mice and keyboards to control the session owner's desktop. This feature is disabled by default, and must be enabled on the Anyware agent before it is available.

Enabling Input Control

Input control is disabled by default, and the option to give collaborators input control cannot be selected.

To use Input Control, enable it on the Anyware agent. This change takes effect on the next PCoIP session:

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

2. Turn on input control:

   sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.enable_collaboration_input_control 1
   

3. Optional: 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>
   

Disabling Input Control

If Input Control has been enabled and you wish to disable it again:

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

2. Type the following:

   sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.enable_collaboration_input_control 0
   

Configuring Collaboration

Changing the Collaboration Starting Port

The default starting UDP Port for collaborator sessions is 64172. You can change this value if needed. Remember that you must also open a range of UDP ports that begin with this value to accommodate all of your collaborators; see Network Requirements for examples.

To change the Collaboration session port:

1. Open a Terminal window, and type the following command specifying the new starting 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.

Changing the Maximum Number of Collaborators

PCoIP Ultra Collaboration supports up to 5 collaborators on the same PCoIP session. You can further limit the number of allowed collaborators by changing the maximum collaborators setting to a value from 1-5. By default, the system allows 5 collaborators.

To Change the Maximum Number of Collaborators:

1. Open a terminal window.

2. Type the following command, replacing <maximum number of collaborators> with your desired number:

   sudo defaults write /Library/Preferences/com.teradici.pcoip-agent.plist pcoip.max_collaborators <maximum number of collaborators>
   

3. Restart the machine.

Changing the Input Control Timeout Value

Input control is released and made available to other collaborators by idling all input devices for a brief period. By default, this control timeout is 3 seconds (3000ms). You can change this value by configuring the Anyware agent machine as follows:

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

2. 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>
   

3. Restart the machine.

Sharing Your Session With Collaborators

You can invite up to 5 collaborators to participate in your session, and optionally allow them to control your desktop.

Collaboration sessions are managed using the Collaboration manager. The collaboration manager shows you who is connected to your session, whether each collaborators can view or control the session, and allows you to invite new collaborators or stop collaborating.

To launch the Collaboration Manager:

1. Connect to a PCoIP session with PCoIP Ultra and Collaboration enabled.

2. From the remote session, open the Collaboration Manager using either of these methods:

   • From the client menu: From the client's in-session menu, select Collaborate > Invite to Collaborate.

     

     The Collaborate menu appears if both the Anyware agent and Anyware client are version 23.06 and higher, and if both support Collaboration.

   • From the menu bar: Click the Anyware Collaboration icon in the menu bar:

     

     This example shows a macOS desktop; yours may vary depending on which operating system you are connecting to.

To invite collaborators, the session owner generates a collaboration invitation using the collaboration manager, and distributes the invitation to all collaborators.

About Collaboration Invitations

Collaboration invitations are created by the session owner and distributed to collaborators, who use them to join an established collaboration session.

Inviting the First Collaborator

To begin a collaboration session, generate an invitation using the Collaboration Manager.

To generate a collaboration invitation:

1. Connect to a PCoIP session with PCoIP Ultra and Collaboration enabled.

2. From the remote session, open the Collaboration Manager using either of these methods:

   • From the client menu: From the client's in-session menu, select Collaborate > Invite to Collaborate.

     

     The Collaborate menu appears if both the Anyware agent and Anyware client are version 23.06 and higher, and if both support Collaboration.

   • From the menu bar: Click the Anyware Collaboration icon in the menu bar:

     

     This example shows a macOS desktop; yours may vary depending on which operating system you are connecting to.

3. The Collaboration manager generates and displays an invitation:

   

   The invitation contains two pieces of information that are used to invite the collaborator:

   • Invitation Link: The collaborator will use this link to join your session. The link may be opened on any Mac, Windows or Linux machine with a Anyware Client 21.07 or newer.

   • Invitation passcode: 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.

4. Share the invitation link and the invitation passcode with the collaborator.

   • To share both the link and the code at once, click the Copy invitation button. This will create a single message containing both the link and the code and place it on your clipboard. Share this with your collaborators using any acceptable method.

   • To share the link and code separately, click the copy button beside each item and share them using separate communications. Sharing the invitation this way reduces risk in the event that a message is inadvertently sent, forwarded, or intercepted by a third party.

Inviting Additional Collaborators

Once the collaboration session has been created, you can invite additional collaborators by sharing the same invitation link and passcode with them. You can also view the invitation, and copy its link and passcode for sharing, using the Collaboration Manager.

To view and copy the invitation link and passcode:

1. From the remote session, open the Collaboration Manager using either of these methods:

   • From the client menu: From the client's in-session menu, select Collaborate > Invite to Collaborate.

     

     The Collaborate menu appears if both the Anyware agent and Anyware client are version 23.06 and higher, and if both support Collaboration.

   • From the menu bar: Click the Anyware Collaboration icon in the menu bar:

     

   The collaboration manager shows a list of your active collaborators (if any).

2. In the Collaboration manager, below the list of active collaborators, click Invite Collaborator:

   

3. The Collaboration manager displays the generated invitation. Note that this is the same invitation link and passcode you used previously. It is not a new invitation:

   

4. Share the invitation link and the invitation passcode with the additional collaborators.

Accepting or Declining Collaborators

Once distributed, the session owner's collaborators can join the collaboration session. As collaborators use the invitation, the session owner is notified and can accept or reject each connection attempt.

To respond to a collaborator:

1. When the collaborator attempts to join the session, the Collaboration manager will display options to accept or reject the connection.

   

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

Ending a Collaboration Session

The collaboration session will end when the session owner disconnects their PCoIP session, or if they stop collaborating using the collaboration manager.

Ending the collaboration session invalidates the invitation. To start a new session, generate a new invitation by inviting another collaborator.

To stop collaborating:

1. From the remote session, open the Collaboration Manager using either of these methods:

   • From the client menu: From the client's in-session menu, select Collaborate > Invite to Collaborate.

     

     The Collaborate menu appears if both the Anyware agent and Anyware client are version 23.06 and higher, and if both support Collaboration.

   • From the menu bar: Click the Anyware Collaboration icon in the menu bar:

     

     This example shows a macOS desktop; yours may vary depending on which operating system you are connecting to.

2. Click the Stop Collaboration button.

Allowing Collaborators to Control the Session

Collaborator input control allows collaborators to use their own mice and keyboards to control the session owner's desktop. This feature is disabled by default, and must be enabled on the Anyware agent before it is available.

Once enabled, input control options are available from the collaboration manager. Input control can be granted (or retracted) for each user separately or for all users at once.

Enabling Input Control for Collaborators

The following steps will allow one or more collaborators to take control of the session desktop. The collaborators will not immediately have control when this is granted; they must still take control using the process described above.

This option will not be available if Input Control has been disabled on the Anyware agent.

To allow collaborators to control the session desktop:

1. From the remote session, open the Collaboration Manager using either of these methods:

   • From the client menu: From the client's in-session menu, select Collaborate > Invite to Collaborate.

     

     The Collaborate menu appears if both the Anyware agent and Anyware client are version 23.06 and higher, and if both support Collaboration.

   • From the menu bar: Click the Anyware Collaboration icon in the menu bar:

     

     This example shows a macOS desktop; yours may vary depending on which operating system you are connecting to.

2. Grant input control using one of these methods:

   • To allow input control for all collaborators, click the dropdown menu at the top right and select All can control.

     

   • To allow input for one collaborator, click the dropdown menu beside the collaborator's name and select Can control.

Stopping input control

To return a user (or all users) to view-only mode:

1. From the remote session, open the Collaboration Manager using either of these methods:

   • From the client menu: From the client's in-session menu, select Collaborate > Invite to Collaborate.

     

     The Collaborate menu appears if both the Anyware agent and Anyware client are version 23.06 and higher, and if both support Collaboration.

   • From the menu bar: Click the Anyware Collaboration icon in the menu bar:

     

     This example shows a macOS desktop; yours may vary depending on which operating system you are connecting to.

2. Beside the collaborator's name, click the dropdown menu and select Can View.

Understanding Display Behavior

Collaboration sessions support sharing of multiple monitors, which varies by session owner's client setting as follows:

• Windowed mode: The session in the owner's client window will be shared.

• Fullscreen One Monitor: The single fullscreen session will be shared. The session owner should set their Anyware Client to Fullscreen One Monitor mode prior to starting the collaboration session.

• Fullscreen All Monitors: All monitors will be shared, beginning with the Session Owner's monitor 1 and continuing up to the number of displays in the collaborator's system. The monitors that are shared cannot be configured, and are shared in system order.

  When using this mode, the session owner should assume that collaborators can see all displays unless a specific configuration has been tested and verified.

  For example, if the session owner has four monitors and a collaborator only has two, the collaborator will see the session owner's first and second monitors. If different collaborators have a different number of screens, each will see as many displays their system supports; in this scenario, you may have some displays that are visible to certain collaborators but not others.

  The session owner should set their Anyware Client to Fullscreen All Monitors mode prior to starting the collaboration session.

If the session owner's and collaborator's screen resolutions are different, the collaborator's screen will use scrollbars and letterboxing to display the shared content.

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

Joining a Collaboration Session

Collaborators receive the invitations generated by session owners, and use the invitation URI and passcode to connect to the session.

Each collaborator can join the session with the collaboration link and the Collaboration Invitation passcode. The same URI and passcode are used for all collaborators on the same session.

To join a collaboration session as a collaborator:

1. Open a web browser and go to the collaboration link 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 Anyware Client application. Allow the browser to open the Anyware client.

3. When the Anyware client opens, it will prompt you for your name and the Collaboration Invitation passcode. The name you provide here will identify you in the collaboration session. The collaboration invitation passcode is the six digit number provided by the session owner. Enter both values and click Submit.

4. Once the session owner accepts your connection request, the Collaboaration screen share will start.

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

Collaborator Input Control

If the session owner has enabled input control for a collaborator, the collaborator can take control of the session owner's desktop including mouse, keyboard, and pointer activity. The session owner retains the ability to stop input control at any time.

Using Input Control as a Collaborator

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.

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