When a Wix user adds your app to their site, Wix generates a new app instance. An app instance represents a unique installation of your app on a specific Wix site. Each app instance has a unique ID (instanceId) that's shared by all of your app extensions and remains the same even if the app is uninstalled and reinstalled.
The instanceId lets you identify your users and manage site-specific data or requirements. You can use it as a foreign key in your own database to efficiently organize data by site, while also accessing additional app instance data that Wix stores through our APIs.
Note: When building a public app for the Wix App Market, you must identify users using the instanceId.
App instances enable you to build scalable, secure, and personalized experiences for each site that installs your app. Depending on your use case, you may need just the instanceId or additional app instance data.
For example, you can use app instances to do the following:
instanceId as your database key.instanceId.Learn how to get the app instance ID and fetch instance data.
Tip: Subscribe to the App Instance Installed event to save the instanceId when your app is installed on a site.
When users access your app through iframes or external dashboards, Wix sends them to your endpoint with a signed app instance query parameter. This data helps you understand which user is accessing your app, from which website, and what their role is, such as website owner or contributor.
Consider these approaches for automatic login:
instanceId: When users access your app, use the instanceId from the signed app instance parameter to create a user session or link to an existing account, eliminating the need for separate login credentials.permissions field to determine if the current user is the site owner or a contributor, then grant appropriate access to features and data for that specific site.uid (user ID) and instanceId to allow the same person to access multiple sites they manage without re-authenticating, while keeping each site's data separate.Wix users can create thousands of websites under the same Wix account. There are many reasons for this, ranging from small businesses creating multiple websites for different products, to large partners creating thousands of websites for their clients. That's why apps must support users with multiple sites.
Consider these approaches for multi-site support:
instanceId as your primary database key to isolate data between sites, even when the site owner uses the same email address across multiple business websites. This ensures that Site A's customer data, inventory, or settings don't appear when the user accesses your app from Site B.permissions field in the app instance data to determine if the current user is the site owner or a contributor. Use this with the instanceId to ensure contributors can only access data for sites where they have permissions, preventing them from switching between sites they shouldn't see.instanceId values, then let verified site owners toggle between their sites without returning to Wix.The originInstanceId property indicates whether the current site was duplicated from another site. If originInstanceId is present, it contains the instanceId of the original installation. If it's missing or empty, the site wasn’t duplicated. Wix includes this property when you retrieve instance data using the REST API, SDK, encoded instance query parameter, or the app instance installed event.
Consider these approaches for handling site duplication:
originInstanceId to query your database for the original site's configurations, user data, or content, then copy it to the new instanceId to maintain continuity.originInstanceId to inherit preferences like language, dashboard layouts, or feature configurations from the original site, then allow users to customize them for the duplicated site.Caution: When a site is duplicated, a new app instance is created without triggering the consent flow. If your app uses custom authentication (legacy), this means no refresh token is generated. To address this, you can either:
instanceId, app ID, and app secret.The instanceId uniquely identifies your app on a site. You can get it from:
getDecodedAppInstance() for Wix BlocksImportant: These methods don't return exactly the same set of properties.
The method depends on your environment:
Warning: Don't trust an instanceId sent to your backend as plain text, as it can be manipulated by an attacker.
Wix stores specific data about each app instance, which can be accessed using the following methods based on your use case:
getDecodedAppInstance() to get the instanceId and the vendorProductId, which is the ID of the plan that the site owner purchased. This can only be called from Blocks frontend code.Note: Wix Blocks apps should generally follow the same guidance as other apps, especially if the instanceId is required on the backend.
When users access your app through certain frontend interactions, Wix automatically sends app instance data as an encoded instance query parameter to your app's endpoints. This parameter contains the instanceId plus additional context like user information and site details. The data is signed to ensure it hasn't been tampered with.
This is particularly useful for apps that need to know which site they're running on and who the current user is without making additional API calls.
Apps that receive the app instance query parameter include:
Learn how to parse the app instance query parameter.
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 the Encoded App Instance Parameter.
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 `instanceId` 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 | The instance ID of the app in the original site. This property is only relevant for duplicated sites. |
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.