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

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

```typescript
ArcwareInit(ids, configuration, forceRefresh)
```

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

Example:

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

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

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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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.

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

```typescript
forceRefresh: true
```

with either:

```typescript
ArcwarePixelStreaming.clearSessionId()
```

or:

```
?noSession
```


---

# 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/in-depth/session-reuse-forcerefresh-and-url-parameters.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.