Build UI extensions for public apps (BETA)

UI extensions can be built for both private apps and public apps, and follow the same principles and limitations in both types of apps. However, while most UI extension concepts are transferable from private apps to public apps, there are two key differences:

• When developing a UI extension using a private app, you install the app directly in the target production account. When developing using a public app, you instead build the app in a developer account, then its install URL can be used to install it into other accounts. So while private apps are created on a per-account basis, public apps are intended to be installed across multiple accounts.
• UI extensions in private apps use serverless functions and the private app's access token to fetch external data. UI extensions in public apps instead require you to bring your own self-hosted back end and use the hubspot.fetch() API.

Using the CLI, you can create a project with a public app using any of the following methods:

• Follow the quickstart guide to create an app from a boilerplate project template, which includes a card for contact records.
• Migrate an existing public app to the developer projects framework. If an app hasn't been migrated yet, you can also copy it into a developer project by running hs project clone-app.
• Manually create a public app in a project.

Whichever method you choose, you'll handle app configuration in the app’s public-app.json file Learn more about creating and configuring apps.

When building UI extensions, check out the following resources to learn more about the utilities, functionalities, and components available to you:

• UI extensions overview
• Create UI extensions
• UI extensions SDK
• List of available UI components
• Sample UI extensions

While developing UI extensions, you can run a local development server to see your saved changes in real-time without needing to re-upload the project. The local development server is only available for the front end portion of the app, and assumes the backend is either running locally or is hosted. Because public apps require you to bring your own back end, there are a few differences for running local development for public apps, depending on your setup.

Learn more about local development.

While private apps can use serverless functions to fetch data, when you build UI extensions inside public apps, you need to bring your own REST-based backend and use the hubspot.fetch() API to fetch data. You'll specify the URLs that the app can request data from in the allowedUrls array in the public-app.json file. 

Learn more about fetching data with hubspot.fetch.

Build webhooks into your app to subscribe to events happening in the account that the app is installed in. Webhooks in project-based public apps can use generic webhook subscriptions to subscribe to events for a wide range of HubSpot objects. However, you can still subscribe to classic webhook subscriptions by including a legacyCrmObjects or HubEvents, depending on the subscription type.

Webhook subscriptions are defined in the webhooks.json file within a webhooks folder in the same directory as your app (e.g., src/app). You'll also need to update your public-app.json configuration file to reference that file.

Learn more about using webhooks in public apps.

All apps built for the App Marketplace are subject to the App Marketplace listing requirements, and certified apps are subject to the additional App Marketplace certification requirements. If you're adding a UI extension to an app intended for the App Marketplace, you'll need to adhere to the additional criteria below.

• Naming: per the App Partner Program branding guidelines:
  • Do not modify, imitate, or abbreviate any HubSpot brands or names (e.g., "HubSpot," "Hub," etc.) anywhere in the name of your UI extension.
  • Do not use a generic product name + any HubSpot brands or names (e.g., "UI extension for HubSpot").
  • Do not brand your UI extension using the word "inbound" in a way that would tie it to HubSpot's INBOUND event (e.g., "Inbound Sales UI extension").
• Logos and icons: 
  • Per the App Partner Program branding guidelines, do not use the HubSpot company logo or sprocket without permission.
  • Do not use company or brand logos other than your own as icons.
• Sensitive data:
  • Your app must not be participating in the current sensitive data for public apps private beta.
  • Your UI extension must not display sensitive information, as defined in HubSpot's Terms of Service.

• Your app must have advanced scope settings turned on ("advancedScopeSettingsEnabled": true in public-app.json). All required, conditionally required, and optional scopes should be selected to prevent errors. 
• Your app must use all of the scopes that it requests during installation. Scopes that are not used must be removed. If certain scopes only apply to a subset of your app's user base, they should be included as conditionally required or optional scopes.

For linked assets such as images and JavaScript, avoid using absolute links. Instead, use relative links and include the assets in your files. Exceptions may only be made if you use a reputable CDN.

• Buttons:
  • Forms must include submit Buttons. 
  • Ensure destructive button styles denote a destructive behavior.
  • Include only one primary button per surface (app card, modal, or panel).
• Text: 
  • It's recommended to not use underline formatting for text that's next to a hyperlink, as it will also appear clickable.
  • Do not use Tags in place of Buttons or Links.