Identify the App Instance in a Self-Hosted Site Widget

For security reasons, the app instance ID isn’t directly accessible in site widgets or settings panels. Instead, you can securely extract it by sending a Wix access token to a backend API. The backend can decode the token, retrieve the instance ID, and perform any necessary business logic.

This article explains how to:

• Backend: Expose a backend API that securely extracts the app instance ID from a Wix access token.
• Frontend: Pass the Wix access token from your custom element to your backend.

Step 1 | Expose a backend API to extract the app instance ID

To securely identify the app instance:

1. Expose a backend API. You can build and deploy your backend API using any framework. The examples in this article are based on a Node.js server.

2. In your backend API code, get the Wix access token from the authorization header:

   Copy

3. Use the access token to call Get Token Info, which extracts instanceId from the token.

   Copy

Step 2 | Pass a Wix access token from your custom element to your backend

To send the app instance ID to your backend, include a Wix access token in the request.

1. Add a self-hosted site widget extension with a custom element. If you already have a site widget, skip to the next step.

2. In your custom element code, initialize a WixClient with the site authentication and host configuration:

   Copy

3. Add the following line to the constructor of your custom element class to inject the Wix access token:

   Copy

4. Import the httpClient submodule from the Essentials SDK:

   Copy

5. Call fetchWithAuth() to send the access token to your backend:

   Copy

Example

The following sections contain example backend and frontend code for retrieving the app instance ID from a custom element.

Backend code

The following example creates a Node.js Express API called get-instance.

Frontend code

The following example creates a custom element to display the mock instance data from the get-instance endpoint.

See also

• About Site Widget Extensions
• About App Instances