In This Article

About App Instances

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.

Depending on the scenario, you can access different types of data about an app instance:

App instance ID: Primary identifier for your app on a site.
API instance data: Requested directly by your app.
Wix Blocks instance data: Accessed from components created with Wix Blocks.
Client-triggered instance data (not recommended): Sent as an encoded query parameter, instance, to your app endpoints when a user accesses your app through a frontend action. The instance data token includes information about the site visitor, site member, or Wix user in context.

App instance ID

The app instance ID (instanceId) is the primary identifier for your app on a site and remains the same even if the app is uninstalled and reinstalled. You can use the instanceId to:

Authenticate using OAuth.
Link app content to a specific site.
Act as a bridge (foreign key) for persistent data storage and data collection.
Communicate to Wix support about a specific app instance.
Get information about specific app instances via webhooks and payout logs.

You can get the instanceId from:

Tip: We recommend that you save the instanceId upon app installation. If using basic OAuth, subscribe to the Instance App Installed webhook. If using advanced OAuth, save the instanceId when returned to the redirect URL.

API instance data

You can get app instance data without any action by the user by calling the Get App Instance API. You can access this API through REST and the SDK.

REST

The Get App Instance endpoint provides app instance information independent of user context. You’ll need an access token obtained via either basic or advanced OAuth.

Note: When a site is cloned, a new app instance is effectively created. However, users bypass the consent flow. For apps using advanced OAuth, this can lead to accessing the app from a new instance without a refresh token. In such cases, prompt users to reinstall the app to obtain the necessary refresh token for completing the installation process.

SDK

The getAppInstance() function provides app instance information independent of user context. If your app is making API calls with site visitor or site member authentication, such as in a site extension or a dashboard extension, you need to elevate permissions to call this function.

Example use cases

Example use cases for app instance data provided by the REST API include:

Activate features per site, including tracking upgrades and downgrades. For more information, see Identify and Manage Users.
Check if a site has any Wix business solutions installed with the installedWixApps property.
Track app installation due to user site cloning with the copiedFromTemplate property.

Wix Blocks instance data

You can get app instance data in Wix Blocks by using the getDecodedAppInstance() function. The function returns the instanceId and the vendorProductId, which is the plan ID of the app installed on the site.

Client-triggered instance data

We don't recommend implementing client-triggered instance data, but it continues to be supported for iframe apps (deprecated).

Learn about client-triggered instance data

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 client-triggered instance data include:

iframe apps
External dashboard apps (when a user clicks Open App)
Apps with an external pricing page (when a user clicks Upgrade App)

Example use cases

Example use cases for client-triggered instance data include:

Activate features per site, including tracking upgrades and downgrades. For more information, see Identify and Manage Users.
Automatically log users into your app. Useful for users with multiple sites.
Identify the active user in an app settings iframe using the same instanceId as the app iframe.
Differentiate between site owner and site contributor roles.
Display content in the user's preferred language.

Data structure

The encoded instance parameter is composed of two parts separated by a dot:

Signature: HMACSHA-256 signature. Generated using the app secret and the data part of the instance. The signature is Base64 URL encoded.
Data: A Base64 URL encoded JSON object. This JSON includes the instance properties, listed below. You’ll need to decode the data to see these properties.

Here's an example of the encoded instance parameter:

Copy

For examples on how to parse the parameter, see Parse Encoded App Instance Data.

Properties

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.

JSON example

Copy