Understand app installation flow with the option for partner sign in

​

Understand limits and considerations

• All apps listed on the HubSpot Marketplace that make changes in the listing editor.
• Customers installing the app for the first time. Existing customers who have already installed the app are not affected.
• Installs initiated from the HubSpot Marketplace. Installs initiated from external websites or the app itself are not affected.
• The app’s installation process once you publish changes in the listing editor. Until then, the app’s current installation process will not change.

​

Opt into using a new install experience early

1. In your HubSpot account, navigate to Development. In the left sidebar menu, click App Listings.
2. Hover over an app, then click the More dropdown menu and select Edit draft.

3. In the Listing info section, click Enable Install Experience.

4. In the dialog box, select the checkbox that shows you understand you can’t return to the previous install flow, then click Enable Install Experience.
5. In the app listing editor, select an option in the Install experience section:
   • Seamless install: installs in HubSpot with a guided OAuth flow. Best for apps that want a native install flow in HubSpot.
   • Login via partner site: sends customers to an external sign-up or install flow. Best for apps that require additional setup.
   • No install button: no install button appears on the app listing. Best for apps that can’t yet support an install flow. Users will be shown a contact us or demo request button.
6. If you’re using the Seamless install experience:
   • Click the Install Button URL dropdown menu and select a URL. These URLs are populated from the redirect URLs set in your app settings.
   • In the Sign-in configuration section, select whether the app will require a separate partner sign-in.
7. If you’re using the Login via partner site experience, enter an install button URL that leads to the page on your partner site where the customer can install the app.

​

Understand the Seamless install flow without partner sign in

​

Use the Seamless install flow

1. In your HubSpot account, navigate to Development. In the left sidebar menu, click App Listings.
2. Hover over an app, then click the More dropdown menu and select Edit draft.

3. In the app listing editor, select Seamless install in the Install experience section:
4. Click the Install Button URL dropdown menu and select a URL. These URLs are populated from the redirect URLs set in your app settings.
5. In the Sign-in configuration section, select No partner login required, HubSpot OAuth only.

​

Developer perspective

// Helper function
function getQueryParam(param) {
    const params = new URLSearchParams(window.location.search);
    return params.get(param);
}

const code = getQueryParam('code');
const returnUrl = getQueryParam('returnUrl');

​

Customer perspective

1. In your HubSpot account, click the marketplace icon in the top navigation bar, then select HubSpot Marketplace.
2. Click an app card.
3. In the top left, click Install.
4. In the dialog box, review the app’s requirements, then select the checkbox and click Connect app.

5. Once the app is installed, you can start using the app:
   • Click Explore app features to start from the Feature Discovery section of the app overview page in your Connected Apps settings.
   • Click Customize app cards to start customizing the app’s app cards.
   • Click the X in the top right to return to the app listing page.

​

Understand the Seamless install flow with partner sign in

​

Use the Seamless install flow

1. In your HubSpot account, navigate to Development. In the left sidebar menu, click App Listings.
2. Hover over an app, then click the More dropdown menu and select Edit draft.

3. In the app listing editor, select Seamless install in the Install experience section:
4. Click the Install Button URL dropdown menu and select a URL. These URLs are populated from the redirect URLs set in your app settings.
5. In the Sign-in configuration section, select Include partner sign-in.

​

Developer perspective

https://www.myinstallserver.com/install?returnUrl=https://hubspotreturnurl/install-success&step=authorize

// Helper function
function getQueryParam(param) {
    const params = new URLSearchParams(window.location.search);
    return params.get(param);
}
const step = getQueryParam('step');
const returnUrl = getQueryParam('returnUrl');

function generateStateParameter() {
    const array = new Uint8Array(32);
    crypto.getRandomValues(array);
    return Array.from(array, byte => byte.toString(16).padStart(2, '0')).join('');
}
const state = generateStateParameter();

const returnUrlObj = new URL(returnUrl);
// Set state token and conditional scopes
const scopes = [
   'crm.objects.contacts.write',
   'crm.objects.companies.read',
   'crm.objects.companies.write'
]
returnUrlObj.searchParams.set('state', state);
returnUrlObj.searchParams.set('scope', scopes.join(' '));
// Redirect back to HubSpot
window.location.href = returnUrlObj.toString();
// e.g. returnUrlObj.toString() = "https://www.hubspotReturnUrl.com?state=123abc"
// or returnUrlObj.toString() = "https://www.hubspotReturnUrl.com?someHubSpotParam=returnUrlParam&state=123abc"

https://www.myinstallserver.com/install?code=123&state=30q94q3043&returnUrl=https://hubspotreturnurl/install-success&step=finalize

// Helper function
function getQueryParam(param) {
  const params = new URLSearchParams(window.location.search);
  return params.get(param);
}

const step = getQueryParam('step');
const code = getQueryParam('code');
const state = getQueryParam('state');
const returnUrl = getQueryParam('returnUrl');

​

Customer perspective

1. In your HubSpot account, click the marketplace icon in the top navigation bar, then select HubSpot Marketplace.
2. Click an app card.
3. In the top left, click Install.
4. In the dialog box, click Sign in to sign up or log in to the app.
5. In the new window, finish the app’s sign up / log in process externally.

6. After being redirected back to HubSpot, review the app’s requirements, then select the checkbox and click Connect app.

7. Once the app is installed, you can start using the app:
   • Click Explore app features to start from the Feature Discovery section of the app overview page in your Connected Apps settings.
   • Click Customize app cards to start customizing the app’s app cards.
   • Click the X in the top right to return the app listing page.

​

Understand the Login via partner site install flow

​

Developer perspective

1. In your HubSpot account, navigate to Development. In the left sidebar menu, click App Listings.
2. Hover over an app, then click the More dropdown menu and select Edit draft.

3. In the app listing editor, select the Login via partner site option in the Install experience section.
4. In the Install button URL field, enter the URL of the external page where customers can install your app. This link should not direct to your homepage or your setup documentation.

​

Customer perspective

1. In your HubSpot account, click the marketplace icon in the top navigation bar, then select HubSpot Marketplace.
2. Click an app card.
3. In the top left, click Install.
4. In the new window that opens, install the app from the developer’s website.
5. When the installation is complete, return to HubSpot.

​

Understand the No install button flow

​

Developer perspective

1. In your HubSpot account, navigate to Development. In the left sidebar menu, click App Listings.
2. Hover over an app, then click the More dropdown menu and select Edit draft.

3. In the app listing editor, select the No install button option in the Install experience section.
4. To add a meetings link, click the Add meetings URL dropdown menu and select a scheduling page. To create a new scheduling page, click Create meetings link. Learn more about working with scheduling pages.
5. To add a form, click the Add contact form dropdown menu and select a form. To create a new form, click Create contact form. Learn more about working with contact forms.

​

Customer perspective

1. In your HubSpot account, click the marketplace icon in the top navigation bar, then select HubSpot Marketplace.
2. Click an app card.
3. In the top right, click Schedule demo.
4. If multiple options are available, click the Schedule demo dropdown menu and select Schedule meeting or Request to be contacted.

​

Preview the install flow

1. In your HubSpot account, navigate to Development. In the left sidebar menu, click App Listings.
2. Hover over an app, then click the More dropdown menu and select Edit draft.
3. In the top right, click Preview.
4. Run through a test version of the installation process.