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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.arcware.cloud/web-integration/new-websdk/guidelines.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.