App install and setup
This article describes how to implement the installation and setup flows for your app.
Overview
Apps can learn when they are being installed and uninstalled, and control the behaviour and appearance of their panel inside the storefront of Talent App Store.
For example in the storefront your app can:
- Link to its launch page (e.g to show a dashboard)
- Show the settings icon
- Link to its settings page (e.g. for account hookup with your platform after the app is installed)
The roles of each app
TAS core. TAS core makes API calls on your app to tell it when it has been installed and uninstalled.
The storefront app. The storefront, where tenants can install and uninstall apps, is itself an app.
Whenever the storefront shows the user your app's panel, it first calls the GET /appStatus API on your app to give it a chance to provide details such as the launch page url, whether the setup required icon should be on, etc.
Your app. Your app produces the GET /appStatus API.
API flow to / from your app
Implementing the APIs
Produced APIs
These are APIs that your app exposes for other apps to consume them.
POST /tenants
Whenever a tenant clicks "install" on your app, your app is notified via an incoming core API call to your POST /tenants endpoint.
In the next example, TAS is informing your app that the tenant acme-sandbox-1 has just installed it.
.svg)
-- CODE language-json --
{
"shortCode": "acme-sandbox-1",
"name": "Acme sandbox testing site",
"contactEmail": "fred@gmail.com",
"type": "SANDBOX",
"logoUrl": "https://s3-aws.com/786745987969"
}
How you handle the incoming API call depends on your app.
In rare circumstances, you can send a response that will cause the install to fail. This can be useful if your app is truely private, and you only want known tenants to ever install it.
However normally you should not do this, but instead respond with 200 to let the install succeed. Even if you have mandatory steps at your end, such as account hookup/creation in your own system, you should still let the install proceed, and then show the settings icon. The user can click on the settings icon to complete your mandatory steps.
If your app is truely on demand, you can now do any per-customer setup, e.g. inserting into a customers table, creating a record in your customer management system, sending a welcome email, etc.
TAS supports a try before you buy model where customers you currently don't know can click to install your app and start using it. If your app can provide on demand demo accounts, that will make it a much smoother path for all potential customers to try your product.
GET /appStatus
-- CODE language-json --
{
"shortCode": "acme-sandbox-1",
"name": "Acme sandbox testing site",
"contactEmail": "fred@gmail.com",
"type": "SANDBOX",
"logoUrl": "https://s3-aws.com/786745987969"
}
As the user browses around the storefront, clicking "My apps", etc., from time to time the panels of installed apps will come into view.
Each time your app's panel comes into view, the storefront gives you a chance to customise its appearance by calling GET /appStatus on your app. In your response, you can cause a "Setup required" icon to appear, or "Open" or "Settings" buttons to lead to web pages within your app.
Domains used
The domainsUsed field allows you to communicate to the customer what urls your app will be using. Some customers may use this to e.g. whitelist the sites in a corporate internet gateway.
Strategies for onboarding new customers
Your app may need some setup or admin action itself before a new customer can really start using your app - for example, maybe you need an account in your platform.
The best approach is to let the app install succeed, and then light up the "setup required" icon. Then the user visually understands that something needs to be done to your app, and when they click in and on the "settings" button, they'll be led to your web page, where you could:
- Ask them to log into your system (embed the tenant shortcode in your link). Once the user logs in, you have joined the dots between the install app in TAS and the account on your own platform.
- Ask them to enter some special code/key, which you generate for an account in your platform.
Once the user has completed the account hookup, change your response to GET /appStatus to stop returning setupRequired.
Beware unverified tenants
There is no tenant vetting process in Talent App Store, and anyone can set up a tenant, and install publicly listed apps (or any app they have a link for), without any type of approval. Your new tenant could be a genuine potential customer, a wandering visitor, or a competitor looking at your product.
Your app should plan for malicious tenants (e.g. spammers, malware distributors, dodgy hosting sites). We recommend that you set up a limited demo or read-only account for every new tenant. This way you can let potential customers try out your product, but without incurring any significant risks or costs.
