# 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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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:

```bash
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:

{% embed url="<https://developer.chrome.com/>" %}

{% embed url="<https://developer.mozilla.org/en-US/>" %}

***

## 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**.