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:

• Client-triggered instance data: Sent as an encoded query parameter, instance, to your app endpoints when a user accesses your app through a client-side action. The instance data token includes information about the site visitor, site member, or Wix user in context. See Properties.
• REST API instance data: Requested directly by your app without user interaction.
• Wix Blocks instance data: Accessed from components created with Wix Blocks.

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:

• Client-triggered instance data
• Webhook payloads
• Service plugin (formerly SPIs) metadata

Client-triggered instance data

When a user accesses your app through a client-side 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 app settings iframes 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:

1

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:

JSON example

1

REST API instance data

You can get app instance data without user action by calling the Get App Instance REST API endpoint. This endpoint provides app instance information independent of user context. You’ll need an access token obtained via either basic or advanced OAuth.

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 purchased by the site.

See also

• Parse Encoded App Instance Data