Understanding app URL state

Implementing app URL state

Using the application.urlState query and mutation, you can take three actions with the app URL state: read, save, or clear it.

Consider a Marketplace app that has multiple tabs and a date picker. The following example shows how to save the Optimizations tab and the 30 days range in the date picker into the app URL state:

// Save the view
try {
  await client.mutate('application.urlState', {
    params: { state: { tab: 'optimizations', range: '30d' } },
  });
} catch (error) {
  console.error('Error saving app URL state:', error);
}

The fields tab and range are properties of the saved state object. The host handles the encoding and URL update.

To read the state:

const { data, error } = await client.query('application.urlState');
if (error) {
  console.error('Error retrieving app URL state:', error);
} else {
  const savedState = data?.state ?? null;
  // Validate savedState before restoring the view.
}

To reset the state:

// Clear the saved view
try {
  await client.mutate('application.urlState', {
    params: { state: null },
  });
} catch (error) {
  console.error('Error clearing app URL state:', error);
}

Note the following about state:

• Saving state replaces the previous state. Saving null clears the state.
• The SDK validates the state before sending it. If validation fails, the mutation rejects and the previously saved state remains unchanged.
• The current state is stored in memory. A query after a successful save returns the new value, even if the URL hasn't updated yet.
• URL updates can briefly lag behind saves, so you need to wait for the browser URL to update before copying it.

Scope and lifetime

State belongs to an app instance within a specific Sitecore organization and environment.

Each app instance accesses its own state through the SDK, including instances of the same app. A link opened in another organization or environment doesn't restore its state, and switching environments resets it.

Closing and reopening an app in the same session keeps its state unless the host removes it to meet the shared size limit.

View state is separate from route persistence, and existing route events continue to work as before.

Supported values and size limits

Save state as a plain JSON object. The object can contain strings, finite numbers, booleans, null, arrays, and nested objects. The top-level value must be an object or null.

The object can't contain functions, Date, Map, Set, class instances, circular references, NaN, or Infinity.

Object properties set to undefined are omitted, including nested properties. undefined values in arrays are rejected.

Both encoded and uncompressed limits apply. The nesting limit includes the top-level object. It's best practice to save IDs rather than complete content items as state. When the shared URL budget is full, the host can remove the saved states of other instances. Always handle state: null, even after an earlier save.

Security

URL state isn't encrypted. Anyone with the URL can read or change it, and URLs can appear in browser history and logs.

It's best practice to:

• Not save secrets or personal data in the state.
• Not log the state.
• Validate restored values and check the user's permissions before loading referenced data. A saved view doesn't grant access to the data.

Handle errors

The client package exports ErrorCode and UrlStateErrorReason for checking error values.