An app instance is an installation of your app on a specific Wix site, identified by a unique instanceId. This ID remains the same across all extensions of your app on that site, even if the app is uninstalled and reinstalled.
Depending on your use case, you might need access to:
See example use cases.
Caution: Cloning a site creates a new app instance without triggering the consent flow. For apps using advanced OAuth, this means the new instance lacks a refresh token. You must prompt users to reinstall the app to generate the required token and complete the setup.
The app instance ID (instanceId) is the primary identifier for your app on a site and remains the same across all extensions of your app on that site, even if the app is uninstalled and reinstalled.
You can get instanceId from the following sources:
getDecodedAppInstance() for Wix BlocksTip: We recommend that you save instanceId upon app installation. You can subscribe to the App Instance Installed webhook or call Get App Instance (SDK | REST).
For security reasons, the instanceId isn’t directly accessible in extensions like dashboard pages, site widgets, settings panels, or embedded scripts. However, you can securely extract the instanceId in a backend API.
Learn how to:
App instance data provides information about your app's installation on a specific Wix site. This data includes the instanceId and other properties that describe the app's state and configuration on the site.
You can access app instance data through several methods, depending on your use case:
Important: These methods don't return exactly the same properties.
You can get app instance data by calling Get App Instance (SDK | REST). In both cases, the method returns app instance information that is independent of user context, unlike the encoded query parameter. The data includes the instanceId and other details about your app on the site.
Note: Access tokens sent from site extensions have a site visitor or member identity. To call Get App Instance, you'd need to elevate permissions:
You can get app instance data in Wix Blocks by calling getDecodedAppInstance(). The method returns the instanceId and the vendorProductId, which is the plan ID of the app installed on the site.
When a user interacts with external pricing pages, external dashboards, or iframe apps, an encoded instance query parameter is generated client-side and sent to your app's server endpoints.
When a user accesses your app through a frontend action, Wix provides data about the app instance as an encoded query parameter, instance, to your app endpoints. The instance query parameter includes the instanceId along with site and user information. The data is also signed to ensure its integrity and authenticity.
Apps that receive the encoded query parameter include:
Example use cases for instance data provided by the encoded query parameter include:
instanceId as the app iframe.The encoded instance parameter is composed of two parts separated by a dot:
Here's an example of the encoded instance parameter:
For examples on how to parse the parameter, see Parse Encoded App Instance Data.
Once decoded, you'll have access to the following data:
| Field | Description |
|---|---|
instanceId | The instance ID of the app within Wix. Read more about the App Instance ID below. |
signDate | The date of the payload signature. |
uid | The ID of the Wix user or site member who is logged in. |
permissions | The permission set of the Wix user or site member: Note: To check if the site owner is logged in, compare the uid to the siteOwnerId property. |
ipAndPort (deprecated) | The user's current IP address and port number. |
vendorProductId | (Optional, appears if the site owner upgraded the app) The Plan ID of the package the site owner purchased. |
aid | The ID of an anonymous site visitor. |
originInstanceId | (Optional, appears in copied sites) The instance ID of the app in the original site. |
siteOwnerId | The ID of the site owner. When this value is the same as the uid, it means the site owner is logged in. |
Warning: For dashboard security, restrict access if the aid parameter is returned, indicating that the user attempting to access the dashboard is anonymous. This applies to users who aren't the site's owner or collaborators, identifiable by the uid.
Note: The siteOwnerId associated with a particular instanceId may change. If a site owner transfers ownership to another user, the existing instanceId becomes linked to the new owner. For instance, if User A transfers the site to User B, the app retains its instanceId but becomes associated with User B's siteOwnerId.
The following examples illustrate use cases for instanceId versus app instance data provided by Wix.
instanceIdThe app instance ID is useful in the following scenarios:
instanceId as a foreign key to store and retrieve data tied to a site, such as user preferences, analytics, or user-generated content. This ensures all app-related and user-generated data remains linked to its originating site.instanceId when troubleshooting or requesting support for a specific app installation.App instance data provided by Wix is useful in the following scenarios:
installedWixApps property, and adjust integrations accordingly.originInstanceId. If originInstanceId is blank or missing, the site wasn't cloned with the app installed. If present, it provides the instanceId of the original installation. For apps using advanced OAuth, you need to prompt users of cloned sites to reinstall the app to generate an access token.