Identify Users with App Instance ID

The App Instance ID (instanceId) is the unique identifier of your app within a specific user's website.

When a user adds an app to their website, the Wix platform generates a new App Instance ID for that site. It's always unique, fixed to a single website, and shared by all of your app endpoints (i.e., all of your app components will get the same App Instance ID).

It's persistent inside a website and will keep its value if the user decides to delete the app and add it again. This makes it ideal for identifying your users and their needs/requirements.

Get the App Instance ID

There are a few ways you can access the App Instance ID:

1. To get the App Instance ID for iframe apps call our getInstanceId method.
2. To get the App Instance ID for OAuth apps use our Get App Instance API.
3. During a live session, Wix's client side App Instance is embedded in the URL (it's encoded with base64 URL, so you’ll need to decode it). It's also appended when a user clicks "Open App", or for apps with an external package picker on "Upgrade App".

When to use the App Instance ID

Use the App Instance ID as the primary ID for your app in the user's site:

• Set the App Instance ID as the identifier of the website, and use it to link the content of the app to a specific site.
• Use the App Instance ID to figure out which features to activate for a user's site, including to track upgrades and downgrades.
• Use the App Instance ID to check if a user has any Wix business solution/s installed (e.g., Wix Stores) by checking the installedWixApps key.
• If your app includes App Settings, the App Settings iframe opens with the same App Instance ID as the app iframe and identifies the active user.
• Use the App Instance ID as the bridge (foreign key) between your app and the Wix website for persistent data storage, the collection of data, or any other action that requires the use of a unique ID.
• Use the App Instance ID to automatically log users in to your app, if account authentication is required or in cases where a user has multiple sites.

Automatically log users in to your app

When users access your app from the Wix platform, we always send them to your endpoint with a signed App Instance. The App Instance helps you understand which user is accessing your app, from which website, and what their role is (e.g. Website Owner, or a Contributor).

Logging users in automatically helps you to:

• Reduce complexity for users, preventing site owners and contributors from needing to make additional accounts (or even if they do, they don't necessarily need to login as long as they access the app from Wix).
• Allow users share their accounts with multiple contributors without forcing them to share their sensitive login info to do so.
• Allow users to continue using the app if they've forgotten their login / account information for a particular site.

Manage users with more than one website

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, or a giant partner of Wix creating thousands of websites for their clients. That's why we ask for apps to cater for users with multiple sites as a basic requirement.

Here are some examples of why your system needs to support a wide range of use cases:

• Users will have the same email address in their Wix account across all of their websites but could be managing websites for 100+ different businesses. They should be able to set a different email address than their Wix account address if needed.
• In some cases you may want to allow users to set up a separate account for each website, but like the example above they might want to use the same email address across them all. If a user has one account for multiple sites, you should determine which site has opened the app by instanceID and present this site’s app dashboard for this site only.
• Contributors could be allowed to access one website, but not others. Even if the app was set up using the same email address, their contributors are likely to be different, so it shouldn't be possible for contributors to switch between "Websites" inside of the app. Find out how to test your app as a contributor.
• For some app types it's common for a website owner to have multiple sites (e.g. users that use one dropshipping app, but have different sites for different products). In these cases, having a way for site owners using an external dashboard (not contributors) to switch between sites without going back to Wix could improve the user experience.

Check if users have duplicated their website (and your app with it)

When your app endpoint is called, check if the instance parameter has an originInstanceId property. If it does, this means that the app is being copied from another site. The value of originInstanceId is the instanceId of the app in the original site. You'll also be able to see the originInstanceId in the App Installed Webhook.

You should copy over visual and important settings to make sure users who duplicate their website have a seamless experience.