Guidelines

Integration & Security Guidelines

Introduction

This guide outlines recommended security, privacy, and integration guidelines when building applications with the Arcware Pixel Streaming WebSDK.

Modern browsers enforce strict policies around:

• device permissions

• autoplay restrictions

• fullscreen access

• WebRTC security

• cross-origin communication

Following these guidelines helps ensure that your application:

• behaves consistently across browsers

• respects user privacy

• complies with browser security models

• provides a trustworthy user experience

These recommendations apply to both UI integrations (ArcwareInit) and headless integrations (CoreSetup).

---

User Permissions and Device Access

Request Microphone Access Explicitly

Access to user devices such as microphones must always be explicitly triggered by a user interaction.

Browsers will block microphone access if it is requested automatically during page load or connection initialization.

Recommended pattern:

document.getElementById("btn-mic").addEventListener("click", () => {
  PixelStreaming.toggleMic(true, false);
});

This ensures the permission request originates from a clear user action.

---

Provide Clear Device Usage Indicators

Whenever the microphone is active, the application should visibly indicate this state to the user.

Examples:

• a microphone icon

• a recording indicator

• a toggle switch that reflects the current state

Providing clear indicators helps users understand when their device is in use and reinforces trust in the application.

---

Autoplay and Audio Policies

Modern browsers restrict autoplay of media that contains sound.

Because Pixel Streaming uses a video element internally, applications should consider the following:

• initialize streams with StartVideoMuted: true

• allow users to manually enable audio

• provide an audio toggle button

Example configuration:

initialSettings: {
  StartVideoMuted: true,
  AutoConnect: true,
  AutoPlayVideo: true
}

Once the user interacts with the page, audio can safely be enabled.

---

Fullscreen Functionality

Only Trigger Fullscreen via User Interaction

Browsers only allow fullscreen mode to be entered when triggered by a direct user action, such as clicking a button.

Example implementation:

document
  .getElementById("btn-fullscreen")
  .addEventListener("click", () => {
    PixelStreaming.rootElement.requestFullscreen();
  });

Attempting to enter fullscreen automatically during page load will typically be blocked.

---

Allow Users to Exit Fullscreen Easily

Always provide users with a clear and simple way to exit fullscreen mode.

Typical options include:

• a fullscreen toggle button

• visible UI controls when hovering the stream

• keyboard shortcuts such as Esc

This helps prevent confusion and ensures users remain in control of their browser environment.

---

Avoid Embedding Streams via Iframes

Embedding Pixel Streaming sessions through an <iframe> is strongly discouraged.

Although some iframe configurations may work, modern browsers apply additional restrictions to iframe content that can negatively affect streaming functionality.

---

Common Issues with Iframe Embedding

Security Restrictions

Iframe environments often enforce stricter security policies that can limit:

• WebRTC functionality

• device permission access

• fullscreen behavior

• clipboard and input handling

---

Cross-Origin Limitations

If the iframe content originates from a different domain, browser same-origin policies can prevent communication between the host application and the embedded content.

This may affect:

• interaction messaging

• session handling

• custom UI integrations

---

Reduced Performance and Responsiveness

Iframe-based integrations may introduce:

• layout inconsistencies

• mobile responsiveness issues

• slower page loading

• more complex input handling

---

Recommended Integration Approach

Instead of embedding a stream via iframe, integrate the stream directly using the WebSDK.

Example:

document
  .getElementById("video-container")
  .appendChild(PixelStreaming.rootElement);

Direct DOM integration provides:

• full control over the video element

• better input handling

• consistent browser behavior

• improved performance

---

Provide Clear Connection Feedback

Users should be informed about the current connection state of the stream.

Typical states to communicate include:

• connecting to stream

• waiting in queue

• stream starting

• stream ready

• connection lost

These states can be implemented using SDK event handlers such as:

• loveLetterHandler

• queueHandler

• videoInitializedHandler

• websocketOnCloseHandler

Providing feedback during connection phases improves user understanding and reduces confusion.

---

Handle Queue Scenarios Gracefully

When streaming capacity is fully utilized, users may be placed in a queue.

Applications should provide clear feedback such as:

• current position in queue

• estimated wait time

• confirmation that the system is working

Queue events are exposed through:

PixelStreaming.queueHandler

Handling queue events properly is important for maintaining a good user experience during peak usage.

---

Implement AFK Awareness

Streaming resources are limited, and sessions may be terminated when users remain inactive.

Applications should listen for AFK events and inform users before a timeout occurs.

Relevant events include:

• afkWarningActivate

• afkWarningUpdate

• afkWarningDeactivate

• afkTimedOut

Providing visual warnings allows users to remain active and prevents unexpected session termination.

---

Avoid Creating Multiple SDK Instances

In frameworks such as React or Vue, repeated component renders may accidentally trigger multiple SDK initializations.

To prevent this:

• use ArcwareInit() instead of manual initialization

• avoid creating SDK instances inside frequently re-rendered components

• reuse the returned SDK objects where possible

If a fresh initialization is intentionally required, use:

forceRefresh: true

---

Protect Against Unexpected Session Reuse

The SDK may reuse previously stored session IDs to reconnect to a stream.

If your application requires a clean new session, explicitly disable session reuse.

Options include:

• using the ?noSession URL parameter

• calling ArcwarePixelStreaming.clearSessionId()

• initializing the SDK with forceRefresh: true

This is particularly useful for:

• testing environments

• multi-user systems

• applications where session persistence should be avoided

---

Keep Dependencies Updated

The WebSDK evolves alongside the Pixel Streaming infrastructure and browser technologies.

To maintain compatibility:

• keep the WebSDK version updated

• pin production deployments to a specific version

• test integrations when upgrading major versions

Example installation:

npm install @arcware-cloud/pixelstreaming-websdk

For production environments, it is recommended to pin exact versions instead of using latest.

---

Stay Informed About Browser Changes

Browser vendors regularly update policies affecting:

• autoplay behavior

• device permissions

• WebRTC capabilities

• security restrictions

Developers should periodically review browser documentation to ensure their integrations remain compliant.

Useful resources:

Chrome for DevelopersChrome for Developers

MDN Web DocsMDN Web Docs

---

Summary

Following these guidelines helps ensure that WebSDK integrations are:

• secure

• privacy-aware

• compatible across browsers

• resilient to infrastructure changes

A well-designed integration should always prioritize:

• user control

• transparent device access

• clear connection feedback

• secure integration patterns.