> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Sample Flows

## Article: Sample Flows

## Article Link: https://dev.wix.com/docs/api-reference/app-management/app-installations/sample-flows.md

## Article Content:

# 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](https://dev.wix.com/docs/api-reference/app-management/app-installations/search-app-installation.md) 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.
1. 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](https://dev.wix.com/docs/api-reference/app-management/app-installations/search-app-installation.md) 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](https://dev.wix.com/docs/api-reference/app-management/app-installations/query-app-installations.md) with a `query.filter` describing the criteria. For example, to retrieve installations of a specific app that are currently installed in the US:

    ```json
    {
      "query": {
        "filter": {
          "appId": { "$eq": "<YOUR_APP_ID>" },
          "status":{ "$eq": "INSTALLED" },
          "siteInfo.countryCode": { "$eq": "US" }
        },
        "sort": [{ "fieldName": "createdDate", "order": "DESC" }]
      }
    }
    ```

1. 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](https://dev.wix.com/docs/api-reference/app-management/app-installations/query-app-installations.md) 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](https://dev.wix.com/docs/api-reference/app-management/app-installations/app-installation-created.md). On each event, provision the tenant in your system using `appId`, `instanceId`, and `siteInfo` from the event response.
1. Subscribe to [App Installation Updated](https://dev.wix.com/docs/api-reference/app-management/app-installations/app-installation-updated.md). 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.
1. Optionally, call [Query App Installations](https://dev.wix.com/docs/api-reference/app-management/app-installations/query-app-installations.md) periodically to reconcile your state against the source of truth.