Identify the App Instance in Frontend Environments

When your app is installed on multiple Wix sites, you need a way to determine which site is making a request. This is done using the app instance.

In some cases, you may only need the instanceId to query your database and perform business logic. In other cases, you may want to fetch additional data about the app instance from Wix. This article covers both approaches across different frontend environments.

To identify the app instance in frontend environments:

1. Send a Wix access token to a secure backend API.
2. Decode the token in the backend to retrieve the instanceId and apply the necessary business logic.

This article focuses on how to send an access token to your backend. To learn how to decode it, see Identify the App Instance in Backend Environments.

Wix-hosted frontend

Wix-hosted frontend extensions include those built with the CLI or Blocks.

CLI

Frontend extensions built with the CLI can identify the app instance using a CLI web method extension or CLI API extension. Learn more about differences between web methods and API extensions.

Web method

To identify the app instance using a web method:

1. Implement a web method to decode a Wix access token, based on the web method backend example.
2. Import the web method in your frontend code. For example:

1. Call the web method. For example:

API extension

To identify the app instance using an API extension:

1. Implement an API extension to decode a Wix access token, based on the API extension backend example.

2. Install Essentials.

3. Call your API from your frontend code using httpClient.fetchWithAuth().

   Copy

Blocks

Frontend extensions built with Blocks can identify the app instance using a Blocks backend function. To do so:

1. Install Essentials.
2. Create a backend code file.
3. Implement a function to decode a Wix access token, based on the Blocks backend example.
4. Call your backend from your widget code. For example:

Alternatively, you can use the getDecodedAppInstance() Velo API.

Self-hosted frontend

For self-hosted site extensions, the method of sending an access token to your backend varies depending on the technology:

• Custom element
• Embedded script
• iframe

Custom element

To identify the app instance from a self-hosted custom element:

1. Implement a backend API to decode the token and identify the app instance, based on one of the following examples:
   • Self-hosted backend using the REST API
   • Self-hosted backend using the JavaScript SDK
2. In your frontend:
   1. Create a Wix client with site host and authentication.
   2. Inject the custom element with a Wix access token.
   3. Send a Wix access token to your backend by calling fetchWithAuth().

The following example demonstrates only the frontend logic.

Embedded script

To identify the app instance from a self-hosted embedded script:

1. Implement a backend API to decode the token and identify the app instance, based on one of the following examples:
   • Self-hosted backend using the REST API
   • Self-hosted backend using the JavaScript SDK
2. In your frontend:
   1. Create a Wix client with site host and authentication.
   2. Inject the embedded script with a Wix access token.
   3. Send a Wix access token to your backend by calling fetchWithAuth().

The following examples demonstrate only the frontend logic.

ECMAScript Module

Standard

iframe

Wix provides iframes with an encoded instance query parameter. This is relevant for self-hosted dashboard pages, dashboard plugins, settings panels, and external links.

To identify the app instance from an iframe:

1. Retrieve the instance query parameter from the URL.
2. Pass the instance value as the token to Token Info.
3. (Optional) Use the returned instanceId to create an app access token and call Get App Instance.