App Installations: Sample Use Cases and Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Search app installations

You want to find the app installation for a specific Wix site without knowing which of your apps is installed there or which field uniquely identifies it.

To find an app installation by free-text search:

  1. Call Search App Installation with search.search.expression set to the value you want to match. The search runs against site URL, business name, business email, site owner email, instance ID, and review title and description.
  2. Read appInstallations in the response. If there are more results than fit on a single page, use the cursor in pagingMetadata.cursors.next to retrieve the next page by calling Search App Installation again with the cursor in the request.

Query app installations

You want to list installations of one of your apps that match specific criteria. For example, all active installations in a country, all installations of a specific app version, or all installations whose plan ended in the last week.

To retrieve a filtered list of app installations:

  1. Call Query App Installations with a query.filter describing the criteria. For example, to retrieve installations of a specific app that are currently installed in the US:

    Copy

  2. Read appInstallations in the response. If there are more results than fit on a single page, use the cursor in pagingMetadata.cursors.next to retrieve the next page by calling Query App Installations again with the cursor in the request.

React to install and uninstall events

You want to keep your own backend in sync with the state of your apps' installations. For example, to provision tenant data on install, update on plan changes, and clean up on uninstall.

Uninstalls aren't delivered as a separate event. An uninstall is a status change on the existing app installation from INSTALLED to UNINSTALLED, which triggers the App Installation Updated event. To react to an uninstall, subscribe to the Updated event and filter the response for status set to UNINSTALLED.

To track app installations in real time:

  1. Subscribe your app to App Installation Created. On each event, provision the tenant in your system using appId, instanceId, and siteInfo from the event response.
  2. Subscribe to App Installation Updated. On each event:
    • If the entity's status is now UNINSTALLED, treat it as an uninstall. Clean up the tenant or mark it as uninstalled in your system.
    • If the entity's status is INSTALLED and was previously UNINSTALLED, use updatedEvent.modifiedFields to detect the transition. Treat it as a reinstall. Restore or re-activate the tenant.
    • Otherwise, update your stored state based on the modified fields in the event response.
  3. Optionally, call Query App Installations periodically to reconcile your state against the source of truth.
Did this help?