Skip to content

WebGL Programming Guide

Jump to bottom
Rick Cheng edited this page Nov 2, 2022 · 9 revisions

The WebGL plugin has almost the same applicable APIs as the original native SDK. This page explains the subtle differences between the native and WebGL target.

SDK Import

Download the complete package and that will include the main Unity SDK and the WebGL plugin.

Scene Update

The application needs an AgoraEventHandler instance to communicate with the WebGL layer of the engine. To do this, drag the AgoraEventHandler prefab from the Prefabs folder to the scene. This object is marked as DontDestroyOnLoad. Therefore, you only need to add it to your entry level scene once.

eventHandler

ScreenSharing

Clearly, ScreenSharing is on the top of the popular features list. The WebGL plugin covers this for:

  • App ScreenSharing: shares a particular texture within the Unity Application. This texture could be the entire visible screen through the main camera or a static texture. See the included app-screenshare-sample demo for this feature. The core API in use is PushVideoFrame(). The order of SetExternalVideoSource() and JoinChannel() calls are different from the native behavior.
  • Desktop ScreenSharing: shares a window captured by the desktop OS. This can be a whole display or a particular window on MacOS or Windows. Extended to the web browsers, this would also include tabs inside the browser. The core API is new, use StartScreenCaptureForWeb() for this call.

ScreenSharing on Web

Starting in Refactor3 release, two new Web only APIs are added:

  • StartScreenCaptureForWeb(audioEnabled): shares the screen, the current local user's webcam stream will be replaced by the screenshare stream. Use the audioEnabled parameter to include audio from the screen. This applies to a tab from the browser only.
  • StartNewScreenCaptureForWeb**(uid, audioEnabled)** can start a separate client that doesn’t take over the webcam stream. With an assigned uid, the remote client can identify this stream is a screensharing stream.
  • The similar APIs are also available to MultiChannel (i.e. AgoraChannel class)

screensharing_chrome

SetVideoEncoderConfiguration

This API is not a 100% match to the native SDK. The main difference is that the mirror mode parameter does not exist for the Web. If your original code sets the mirror-mode true and expects the video stream to become left-right flipped for the remote viewer, this won’t be the case for the Web user. Please leverage other ways to achieve the same effect. The following documents explain the difference:

String user id vs integer user id

In the original Unity SDK and the Web SDK, both string user id (a.k.a userAccount name) and unsigned integer user id (i.e. uid) are accepted. However, Unity always gets an uint uid for remote users from the OnUserJoin() call. The Web gets a string id if the remote user joins with a string id. Therefore, the guideline is that not to use string user id if the applications are talking across the native (Unity) SDK and the Web SDK. Here is the summary on correspondence:

  • If native SDK uses string UID, web SDK uses int UID, there is no issue with audio or video call between native user and web user. Web will return int UID for the remote user.
  • If native SDK uses int UID, web SDK uses string UID, native can receive audio and video stream from web side, but web cannot receive audio or video streams from native side, there is no call back for user joined or subscribe event on web side.
  • If both native SDK and web SDK uses string UID, the web will return string UID for the remote users.

OnVolumeIndication

  • On native, this includes local user’s callback; the WebGL version supports remote users only.
  • The native version doesn’t combine more than one user in one callback; the WebGL version implements the design with multiple users in the list when possible.

DataStream Signaling

Subtle differences in implementing the APIs are as described below:

Int streamID

StreamID is not used in WebGL. It will default to 0. This does not affect interoperation between native and WebGL.

public int CreateDataStream(bool reliable, bool ordered)

(Note this is marked deprecated)

  • Parameter reliable is useless.

  • Parameter Ordered means needsRetry; it provided some certainty that the message is delivered.

public int CreateDataStream(DataStreamConfig config)

  • Parameter syncWithAudio inside config is not supported. And Ordered means needsRetry,

callback OnStreamMessage(uint userId, int streamId, byte[] data, int length)

  • Working as normal.

Clone this wiki locally