Configuration

Configuration and initialization the Arcware Pixel Streaming WebSDK is designed to be easily configurable to fit the needs of various web applications.

Below, we'll explain the configuration options that can be passed to ArcwareInit. ArcwareInit currently takes three parameters and returns three objects, see the following contract:

export function ArcwareInit(
ids: ConnectionInfo,
configuration?: ArcwareInitConfiguration,
forceRefresh: boolean = false
): ArcwareInitResult

Configuration Options

The ArcwareInit() function inherently guards your application against triggering multiple times and reinitializing each time, e.g. in case of rerenderings happening like in a useEffect() in React. If you intentionally want fresh objects provided by ArcwareInit, you can force this by setting forceRefresh to true.

1. ids: ConnectionInfo

The ConnectionInfo parameter is used to highlight the importance of the ShareId for establishing a connection with Arcware Cloud as the ShareId is the only required parameter for the Initialization function at all. If you prefer to initialize the objects (ArcwareConfig, ArcwarePixelstreaming and ArcwareApplication) without the init function, then the same parameter will be present in ArcwareConfigParams which is used to derive ArcwareInitConfiguration. In that case, it will be required to set the shareId on the ArcwareConfigParams.

interface ConnectionInfo {
    shareId: string;
    projectId?: string;
}

  • shareId: The shareId is always required and necessary to tell ArcwareCloud for which project to launch an instance. It can also be seen as an AccessToken which can at any point in time be revoked and modified.

  • projectId: If the shareId is not assigned to a single project but to multiple ones, then it is required to also provide the projectId. In 1:1 assignment, the shareId will know the project it is assigned to and the projectId is not required and can be left undefined

2. configuration: ArcwareInitConfiguration

The second input of type ArcwareInitConfiguration is an extension of Epic's pixelstreaming infrastructure, enhanced by Arcware specific configuration options. The following will give a brief explanation of the top level config

  • settings: Settings specifically for Arcware which will be detailed in a separate section

  • envName: optional parameter for internal testing in Arcware and can be ignored

  • initialSettings: the settings object exposed by pixelstreaming infrastructure. A full list of all available parameters will be given in a separate section. We will give a detailed explanation for each of the options that are tested and known to work with Arcware Cloud as well. For all non-described parameters, it does not mean they are not supported and working, but they are not tested by us.

  • useUrlParams: If set to true, the pixelstreaming application will try to interpret URL query parameters to derive configuration from it. Please refer to official documentation of pixelstreaming infrastructure. Arcware is using this option to read two parameters from query if set to true. One is "i" or "info", if this parameter is present (no value needed), we will show the info overlay for some information like FPS. This can be helpful in debugging scenarios. The other is the "wl" param used for enabling white labelling or directly providing the white labelling as base64 encoded object.

  • webSocketProtocols: not required and should be left undefined

2.1 initialSettings

These settings directly expose the initialSettings object of the original library of Epic Games.

Here is the full list of available properties from pixelstreaming infrastructure

Some of these settings can potentially be overriden by WebSDK settings of the project in the platform. Please consult your projects settings if you want to make sure the settings are governed by your configuration in code or by platform. Settings that are not present in platform will not touch the settings in code.

  • ss[wss://signalling-client.ragnarok.arcware.cloud]: signalling server URL, which should be left as the default

  • AutoConnect [false]: if true, the instance will directly start the connection initialization. If false, the trigger for connecting needs to come externally (default is a play button being visible in the videoPlayerElement). This is strongly connected to AutoPlayVideo. If AutoConnect is true, the video will be made ready in background but it will only be rendered in the VideoElement if play button is pressed or also the AutoPlayVideo is true

  • AutoPlayVideo[true]

  • TimeoutIfIdle: Afk detection feature toggle, that turns AFK feature on and off. Please do not rely on this setting. As this is the correct setting to handle that feature and Arcware also using it, there is still multiple places from where Arcware might touch this variable and cause unintended effects on the user side. The Afk information is provided to the WebSDK through the streamInfo event on the websocket which might override your settings. Please set up Afk from shareId settings or project settings in Arcware Cloud Platform.

  • HoveringMouse[true]: Flag to toggle if mouse is captured by video element or hovering

  • ForceMonoAudio[false]

  • ForceTurn: this flag is ignored by Arcware, we always force relay server

  • FakeMouseWithTouches[false]

  • StartVideoMuted[true]:

  • SuppressBrowserKeys[true]:

  • UseMic[true]:

  • UseModalForTextInput[false]: untested

  • UseCamera[false]: untested

  • KeyboardInput[true]:

  • MouseInput[true]:

  • TouchInput[true]:

  • GamePadInput[true]:

  • XRControllerInput[true]:

  • WaitForStreamer[false]: does not apply for Arcware

  • HideUI[false]: untested

  • AFKTimeoutSecs[600]: See TimoutIfIdle setting, AFK is governed through platform

  • AFKCountdownSecs[10]: See TimoutIfIdle setting, AFK is governed through platform

  • ...Other parameters not found in this list but above are untested or not even functional

2.2 settings

The settings object helps to configure Arcware Cloud features. If not default is depicted it is false or undefined.

  • session: option to manually provide sessionId. This should not be used to force new instance and session. Usually, this parameter is governed inherently by the SDK

  • errorHandler: Currently it only bubbles up the errors from pixelstreaming infrastructure, but it is planned to also emit Arcware based errors.

  • queueHandler: Handler that provides information about queuing positions. Useful if you want to develop your own overlay

  • sessionIdHandler: returns the sessionId if you want to store and handle sessions on your end.

  • loveLetterHandler: returns a love letter as soon as it gets sent from backend. These indicate the current position during the loading of an instance, i.e. the stages until first frame gets rendered. This can be used to make your own overlay with your rephrased message or "fake" loading bar

  • fullscreenButton[true]

  • settingsButton

  • infoButton

  • audioButton[true]

  • micButton

  • stopButton

  • connectionStrengthIcon: we do not recommend to show or use it, as it seems to be derived from UserAgent of browser and is not reliable.

  • shareId: required if you manually create the ArcwareConfig object

  • projectId: required if you have a shareId that is assigned to multiple projects

  • loveLetterLogging: toggle to output the love letters to browser console

  • startWidth:

  • startHeight:

  • orientationZoom: this is an option to provide potential zoom states that are sent to Unreal. This will only work if implemented on Unreal side also. The feature is kind of deeply integrated with our ArcwareTemplate

  • whiteLabelling: This object can be used to customize a few thing on the WebSDK. As you can use all of these options also from the settings in code, it was mainly intended to be used for non frontend developers to customize with settings from shareId. How it works: if fetchRemoteWhiteLabelling is true, the SDK will attempt to fetch whitelabelling information (I.e. this object here) from backend with async call and on return apply the settings. If query parameter ?wl is provided, and useUrlParams is true, then it will set fetchRemoteWhiteLabelling also to true, unless ?wl has a value. Then SDK will try to decode this object from the base64 encoded value.

    • splashScreenUrl: URL to a static ressource which can be relative path locally or full URL. Allowed is images and videos. See list of mime types below. This will be shown as background image on the videoElement until the stream starts rendering

    • loadingIconFadeMs: this is a number in milliseconds with with the loading icon will fade in and out to create kind of a loading effect. Only applies if loadingIconUrl is given. If not prodived, the icon will be static and not flash, e.g. if intended to have static image or if the image is animated itself.

    • loadingIconUrl: to a static ressource which can be relative path locally or full URL. Allowed is image. This will be shown as loading Icon instead of the Arcware Logo

    • splashScreenMode: depicts the mode how the background image should be treated, like cropping, stretching, repeat

    • splashScreenBgColor: can be used instead of a background image to just have a static color that is not black

    • hideLoveLetters: option to hide the letters being shown under the icon

    • hideAfkOverlay: This hides the countdown overlay of the AFK feature. This does not disable the feature it will just not give visuals.

  • fetchRemoteWhiteLabelling: depicts if whitelabelling should be applied by requesting settings from backend.

Interaction with Unreal Engine Application

If you have come this far, you might be interested in how to interact with your application from your web-app:

Interacting with Unreal Engine

PreviousBest practicesNextInteracting with the Stream

Last updated