Identify the App Instance in a Site Widget Built with the CLI

In This Article

For security reasons, app instance ID (instanceId) 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, get the instance ID or instance data, and perform any necessary business logic.

This article explains how to:

Backend: Expose a backend API to identify the app instance.
Frontend: Pass a Wix access token from your custom element to your backend.

Step 1 | Expose a backend API

To securely identify the app instance:

Add a Backend API Extension in the Wix CLI.
In the api.ts file of your backend API extension, import the auth submodule from the Essentials SDK:
Copy
```
import { auth } from "@wix/essentials";
```
Depending on your use case, you may only need instanceId or you may need more detailed app instance data.
- To extract instanceId:
  
  In the GET endpoint, call getTokenInfo() to extract instanceId from the access token.
Copy
```
const tokenInfo = await auth.getTokenInfo();
const instanceId = tokenInfo.instanceId;
```
- To fetch instance data:
  
  Elevate API call permissions to an app identity. Then, call getAppInstance(). Elevation is necessary because access tokens sent from site widgets are tied to a site visitor or member identity, which don't have access to instance data.
Copy
```
import { appInstances } from "@wix/app-management";

// Elevate permissions in your GET endpoint
const elevatedGetAppInstance = auth.elevate(appInstances.getAppInstance);
const instanceResponse = await elevatedGetAppInstance();
```

Step 2 | Pass a Wix access token to your backend

To pass a Wix access token from your custom element to your backend:

Add a Site Widget Extension in the CLI. If you already have a site widget, skip to the next step.
In the element.tsx file of your site widget extension, import the httpClient submodule from the Essentials SDK.
Copy
```
import { httpClient } from "@wix/essentials";
```

Call fetchWithAuth() to send a request to your backend with a Wix access token.

Copy


const response = await httpClient.fetchWithAuth(
  `${import.meta.env.BASE_API_URL}/<YOUR_BACKEND_API_NAME>`,
);

Tip: To get instanceId in the settings panel, call fetchWithAuth() from your panel.tsx file.

Examples

Depending on your use case, the logic of your backend API will vary. For example, you may only need to extract instanceId and then use it to make a request to your own database. Alternatively, you may wish to request app instance data from Wix, in which case you'd need to elevate your access token.

See the relevant example for your use case:

Backend: Extract `instanceId`

The following example is based on a CLI backend API extension called get-instance. The API extracts instanceId from the access token provided by the frontend request.

Copy


import { auth } from "@wix/essentials";

// Edit this code based on your business logic
const mockDatabaseQuery = async (instanceId) => {
  console.log(`Mock database query with instance ID: ${instanceId}`);
  if (instanceId) {
    return {
      status: "Success",
    };
  } else {
    return {
      status: "No instance ID.",
    };
  }
};

export async function GET(req) {
  try {
    // Extract the app instance ID from the access token
    const tokenInfo = await auth.getTokenInfo();
    const instanceId = tokenInfo.instanceId;
    console.log("Instance ID:", instanceId);

    // Edit this code based on your business logic
    const data = await mockDatabaseQuery(instanceId);

    return Response.json(data);
  } catch (error) {
    console.error("Error decoding token:", error);
    return new Response(
      JSON.stringify({ error: "Failed to process request" }),
      {
        status: 500,
        headers: { "Content-Type": "application/json" },
      },
    );
  }
}

Backend: Fetch instance data

The following example is based on a CLI backend API extension called get-instance. The API elevates permissions and requests instance data from Wix.

Copy


import { auth } from "@wix/essentials";
import { appInstances } from "@wix/app-management";

export async function GET(req) {
  try {
    const elevatedGetAppInstance = auth.elevate(appInstances.getAppInstance);
    const instanceResponse = await elevatedGetAppInstance();

    return Response.json(instanceResponse.data);
  } catch (error) {
    console.error("Error decoding token:", error);
    return new Response(
      JSON.stringify({ error: "Failed to process request" }),
      {
        status: 500,
        headers: { "Content-Type": "application/json" },
      },
    );
  }
}

Frontend: Call your backend

The following example creates a custom element that makes a request to the get-instance endpoint.

Copy


import React, { useState, useEffect } from 'react';
import reactToWebComponent from 'react-to-webcomponent';
import ReactDOM from 'react-dom';
import styles from './element.module.css';
import { httpClient } from '@wix/essentials';

interface Props {
  displayName: string;
}

const CustomElement: React.FC<Props> = ({ displayName }) => {
  const [instanceData, setInstanceData] = useState<any>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const callMyBackend = async () => {
      try {
        // Send the access token to your backend
        const response = await httpClient.fetchWithAuth(`${import.meta.env.BASE_API_URL}/get-instance`);
        const data = await response.json();
        setInstanceData(data);
        setLoading(false);
      } catch (err) {
        console.error("Error calling get-instance:", err);
        setError("Failed to fetch instance data.");
        setLoading(false);
      }
    };

    callMyBackend();
  }, []);

  return (
    <div className={styles.root}>
      <h2>Hello {displayName || 'Wix CLI'}</h2>
      {loading ? (
        <p>Loading instance data...</p>
      ) : error ? (
        <p>{error}</p>
      ) : (
        <div>
          <p>Success!</p>
        </div>
      )}
    </div>
  );
};

const customElement = reactToWebComponent(
  CustomElement,
  React,
  ReactDOM as any,
  {
    props: {
      displayName: 'string',
    },
  }
);

export default customElement;