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