Skip to content

WebGL Programming Guide

Jump to bottom
Rick Cheng edited this page May 22, 2023 · 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 (Push Video Stream): 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() and StartNewScreenCaptureForWeb for this call.

ScreenSharing on Web

Starting from the 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, screenshareToken) 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. Note that the screenshare token is a separate token from the token that is used for the main camera. And it is associated with the uid you pass in this call.
  • The similar APIs are also available to MultiChannel (i.e. AgoraChannel class)

screensharing_chrome

ScreenSharing FAQ

Q: How do I share my screen without enabling webcam first? A: Use the proper JoinChannel API.

int JoinChannel(string token, string channelId, string info, uint uid, ChannelMediaOptions options)

in which set publishLocalVideo to false in ChannelMediaOptions.

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.
  • To adjust the response latency of the callback, use the SetParameter API call
_agoraEngine.SetParameter("AUDIO_VOLUME_INDICATION_INTERVAL", time);

The time ranges from 200ms to 4000ms.

OnVideoSizeChanged (How to detect remote video resolution)

In the Web SDK, there is no equivalent passive callback API that would activate OnVideoSizeChanged as in Unity. The way you can get the resolution is by calling getRemoteVideoStats from the Web client. Therefore, the wrapper API is added in the WebGL SDK for this purpose. Try calling GetRemoteVideoStats from your application code logic to activate the OnVideoSizeChanged callback.

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