Session Reuse, forceRefresh, and URL Parameters

The WebSDK includes built-in logic to reuse an existing stream session whenever possible. This behavior is especially important in single-page applications and frontend frameworks where initialization code may run multiple times due to re-renders, remounts, or route changes.

Understanding how session reuse, forceRefresh, clearSessionId(), and URL query parameters such as ?noSession work together is important when deciding whether the SDK should:

• reconnect to an existing session

• reuse existing SDK objects

• create a fresh session

• ignore previously stored session state

---

Two Different Layers of Reuse

There are two separate but related concepts involved:

Layer	What is reused
SDK object reuse	Previously created Config, PixelStreaming, and Application objects
Session reuse	Previously known streaming session ID

These two layers are related, but they are not the same.

---

1. SDK Object Reuse

When using ArcwareInit, the SDK protects your application from unintentionally creating multiple instances of:

• ArcwareConfig

• ArcwarePixelStreaming

• ArcwareApplication

This is particularly useful in frameworks like:

• React

• Vue

• Angular

• Svelte

where component lifecycle behavior can cause initialization code to run more than once.

By default, repeated calls to ArcwareInit(...) return the already existing SDK objects instead of creating fresh ones.

Example:

const { Config, PixelStreaming, Application } = ArcwareInit(
  { shareId: "<your-share-id>" },
  configuration
);

If the SDK was already initialized before, this call may return the existing objects.

---

2. Session Reuse

In addition to object reuse, the SDK can also reuse a previously known session ID.

This means that even if the connection is interrupted or the page is reloaded, the SDK may attempt to reconnect to the same stream session instead of starting a new one.

This behavior is useful for:

• reconnect flows

• page reloads

• temporary network interruptions

• preserving stream state

---

forceRefresh

The third parameter of ArcwareInit is:

ArcwareInit(ids, configuration, forceRefresh)

If forceRefresh is set to true, the SDK creates fresh SDK objects instead of reusing previous ones.

Example:

const { Config, PixelStreaming, Application } = ArcwareInit(
  { shareId: "<your-share-id>" },
  configuration,
  true
);

This affects SDK object reuse, not necessarily session reuse.

That means:

• new Config, PixelStreaming, and Application objects are created

• but a previous session may still be reused unless session reuse is also disabled

---

What forceRefresh Does

Behavior	Result
forceRefresh: false	Reuse existing SDK objects if available
forceRefresh: true	Always create new SDK objects

---

What forceRefresh Does Not Do

forceRefresh does not automatically guarantee a fresh backend session.

If a previous session ID is still available and allowed to be reused, the new SDK objects may still reconnect to that session.

---

clearSessionId

The SDK also exposes a method to explicitly remove the stored session ID in code:

ArcwarePixelStreaming.clearSessionId();

This affects session reuse, not object reuse.

After calling clearSessionId(), the SDK will no longer be able to restore the previously stored session automatically.

Typical use cases:

• force a clean new session from application code

• logout or reset flows

• "start over" buttons

• testing clean startup behavior without relying on URL parameters

Example:

ArcwarePixelStreaming.clearSessionId();

const { Config, PixelStreaming, Application } = ArcwareInit(
  { shareId: "<your-share-id>" },
  configuration,
  true
);

This is the code-based equivalent of disabling reuse of the stored session.

---

?noSession

The URL parameter:

?noSession

tells the SDK to start without reusing a previously stored session.

This affects session reuse, not object reuse.

When ?noSession is present, the SDK should behave as if no previous session exists.

Typical use cases:

• always start a fresh instance

• debugging clean startup behavior

• avoiding reconnect into previous state

• explicit new-user or new-run flows

Example:

https://example.com/?noSession

This parameter is only interpreted when:

useUrlParams: true

is enabled.

---

How forceRefresh, clearSessionId, and ?noSession Work Together

These mechanisms affect different layers:

Feature	Affects SDK objects	Affects session reuse
forceRefresh	✔	✖
clearSessionId()	✖	✔
?noSession	✖	✔

This means they can be combined.

---

Example Scenarios

Reuse everything

ArcwareInit(ids, configuration, false)

No ?noSession

Result:

• existing SDK objects may be reused

• existing session may be reused

---

Fresh SDK objects, but same session may still be reused

ArcwareInit(ids, configuration, true)

No ?noSession

Result:

• new SDK objects are created

• previous session may still be reused

---

Same SDK objects, but do not reuse previous session

ArcwareInit(ids, {
  ...configuration,
  useUrlParams: true
}, false)

URL:

?noSession

Result:

• existing SDK objects may still be reused

• previous session is not reused

---

Fresh session by code

ArcwarePixelStreaming.clearSessionId();

ArcwareInit(ids, configuration, false);

Result:

• existing SDK objects may still be reused

• previous stored session is removed and cannot be reused

---

Fully fresh start by code

ArcwarePixelStreaming.clearSessionId();

ArcwareInit(ids, configuration, true);

Result:

• new SDK objects are created

• previous stored session is removed and cannot be reused

---

Fully fresh start by URL

ArcwareInit(ids, {
  ...configuration,
  useUrlParams: true
}, true)

URL:

?noSession

Result:

• new SDK objects are created

• previous session is not reused

This is the closest behavior to a completely clean new start without calling clearSessionId() manually.

---

reconnect

The query parameter:

?reconnect

indicates that the SDK should attempt to reconnect to a previous session if one is known.

This is effectively the opposite intent of ?noSession.

Example:

https://example.com/?reconnect

If both reconnect behavior and previous session information are available, the SDK will attempt to restore the existing session.

---

?session=

The URL parameter:

?session=<session-id>

explicitly provides the session ID that should be used.

Example:

https://example.com/?session=abc123

This is the most explicit form of session reuse because the session is not merely restored from storage — it is directly specified in the URL.

---

Precedence and Intent

The mechanics can be understood by separating the two decision layers.

SDK Object Layer

Question:

Should the SDK reuse previously created objects or create fresh ones?

Controlled by:

• forceRefresh

---

Session Layer

Question:

Should the stream reuse a previous session or start fresh?

Influenced by:

• stored session state

• clearSessionId()

• ?reconnect

• ?session=<id>

• ?noSession

---

Practical Interpretation

In practice, the intent of these options is usually:

Mechanism	Intent
default initialization	reuse what already exists
forceRefresh: true	rebuild SDK objects
clearSessionId()	remove stored session so a fresh session is started
?noSession	do not restore previous session
?reconnect	try to restore previous session
?session=<id>	use this exact session

---

Recommended Usage Patterns

Typical SPA Integration

Use the default behavior.

ArcwareInit(ids, configuration)

This avoids accidental duplicate stream creation and allows normal reconnect behavior.

---

Clean New Session for Testing

Use either:

• forceRefresh: true together with ?noSession

or

• ArcwarePixelStreaming.clearSessionId() together with forceRefresh: true

This prevents both object reuse and session reuse.

---

Explicit Reconnect Flow

Use:

• default forceRefresh

• ?reconnect

This is useful when the application wants to guide the user back into an interrupted session.

---

Explicit Session Restore

Use:

• ?session=<id>

This is useful when session state is managed outside the SDK and passed into the application explicitly.

---

CoreSetup

CoreSetup does not create the UI layer, but session-related URL behavior still applies when URL parameters are enabled through configuration.

The same distinction remains:

• object creation is controlled by how and when CoreSetup is called

• session reuse is controlled by stored session state, clearSessionId(), and URL parameters

Because CoreSetup is headless, lifecycle and reconnect behavior are typically managed more explicitly by the application.

---

Summary

Mechanism	Purpose
default ArcwareInit behavior	reuse SDK objects and possibly reuse session
forceRefresh	rebuild SDK objects
clearSessionId()	remove stored session
?noSession	disable session reuse
?reconnect	prefer reconnecting to previous session
?session=<id>	force a specific session

A fully fresh start usually requires both:

• fresh SDK objects

• no previous session reuse

That can be achieved by combining:

forceRefresh: true

with either:

ArcwarePixelStreaming.clearSessionId()

or:

?noSession