Once you've created your Integration, it's ready to be installed. Each installation (also known as Configuration) is made under a certain scope.
You can install your Integration in three different ways:
The most common way to install an integration is via Vercel’s Integrations Marketplace.
Go to your desired integration page and click the "Add Integration" button. This shows the scope selection modal, followed by the project selection modal.
Here you can set two things:
- The scope to install an integration (e.g. Personal Account or Team).
- Projects that will have access to the integration (e.g. All or Specific Projects).
Your Integration can only be installed once per scope (Personal Account or Team). If you select a scope to which the Integration is already installed, you are directed to the "Integration Configuration" page.
If the Integration is not installed in the selected scope, you're directed to a popup page with your defined Redirect URL.
The External Flow is useful if you're building a mobile app or wish to start the installation flow from your side instead of from the Marketplace. In this case, redirect the user to the following URL to start the installation process from your side:
https://vercel.com/integrations/:slug/new
The user will be asked to select a Vercel scope (Personal Account or Team) to install this Integration. Next, we redirect the user to the defined Redirect URL (instead of a popup window).
When installing from the External flow, your Integration can only be installed once per scope (Personal Account or Team). If you select a scope to which the Integration is already installed, a new code is generated, and the user proceeds to the Redirect URL. No new Configuration is created.
When you create a Deploy Button for projects that are based on a Git repository, Vercel allows you to specify required integrations.
If integration ids are specified on the deploy button, we show a list of required integrations during the flow. Each integration has an Install button that opens up a popup with the Redirect URL.
If the Integration is already installed in the selected scope during the Deploy Button flow, the Redirect URL will be called with the most recent configurationId. Please make sure to store configurationId along with an access token such that if an existing configurationId was passed, you could retrieve the corresponding access token.