Instances
The Instances page in the vendor portal shows the installs of your apps that report in with their license status checks: which customers run them, which version each one runs, and which ones are behind the newest version their customer can pull. It's built for two jobs: finding the customers still on old versions, and giving support a quick answer to "what is this customer running?"
Instances come from your app. Each license status check can carry an instance ID, a version and a few details of your choosing; see Reporting instances for what to send. Nothing shows here until your app sends them.
Seeing instances is part of the Growth, Scale and Enterprise plans. Reports are recorded on every plan, so when you upgrade, the installs that have been checking in are there straight away. On other plans the page shows how many instances are reporting and offers an upgrade.
Active and stale
An instance is active while it has checked in within the last 7 days, and stale after that: it may be switched off, or it may come back. An instance that hasn't checked in for 90 days is deleted.
The page shows active instances unless you pick Stale or All under Last check-in.
Behind
An instance is behind when the version it reports is older than the newest version its customer can run. That newest version is the highest tag in the product's version repository that the customer's active licenses for the product can pull, leaving out pre-releases such as 2.4.0-rc.1. Tag patterns count, so a customer licensed for 1.x isn't behind for not running 2.0.
Versions are compared as semantic versions: 2.3.1 and v2.3.1 are the same, and anything after a + or _ is ignored. A version that isn't a semantic version is shown as it is and is never counted as behind.
Behind instances show a badge with the version they could run, such as 2.4.1 available.
The version repository
A product with one repository uses it as its version repository. A product with several needs you to pick which one carries the app's versions, in the product's Version repository setting (see Products). Until you do, the Instances page asks you to, and that product's instances show no "available" badges.
The Instances page
- Version spread shows, for each product, how many active instances run each version and how many of those are behind. Click a version to list its instances.
- Filters narrow the list by product, customer, reported version and last check-in. Behind only lists just the instances that are behind.
- The list shows each instance's customer, product, version, ID, when it last checked in, and its status. An instance whose last check-in used a key that's no longer valid shows the key's status too, such as Expired or Revoked, so you can spot installs still running on a license that has ended.
- Export CSV downloads the list as filtered, with the columns
instance_id,customer,product,version,latest_available_version,behind,state,last_status,first_seen_at,last_seen_atanddata(the instance's data as JSON).
Click an instance to see its details: the license it reported with, its key status and generation, when it was first and last seen, and the data your app sent, as a table.
On customer and license pages
A customer's page and each license page show an Instances card with that customer's or license's most recent instances, and a link to the Instances page filtered to them. Support can see what a customer is running without leaving the customer.
Removing an instance
Admins and owners can remove an instance from its detail page, for example a test install you don't want in the list. It's only taken off the list: if the install checks in again, it comes back as a new instance.
Through the API
The Vendor API lists, shows and removes instances too, with the same filters as the page (product_id, customer_id, license_id, version, state and behind). On plans without instances, those endpoints answer 403 with {"error": "plan_required"}. The API Explorer has the details.