App configuration

​

Project structure

• All project components must live within the src directory specified in the top-level hsproject.json config file.
• All app features and components must live within the src/app/ directory. Within this app/ directory, you’ll define subdirectories for each feature you want your app to support:
  • App events are configured within app-events/.
  • App objects are defined within app-objects/.
  • All card features are defined within cards/ .
  • Settings page features are defined within settings/.
  • Telemetry is configured within telemetry/.
  • Webhook subscriptions are defined within webhooks/.
  • Custom workflow actions are defined within workflow-actions/.
• Within each feature subdirectory, you’ll configure the feature are using a *-hsmeta.json file. You can prefix the file name with something meaningful to your app (e.g., my-app-hsmeta.json), as long as the file ends with -hsmeta.json. These files must live at the root level of their respective folder (e.g., app/my-app-hsmeta.json, cards/my-card-hsmeta.json).

my-project-folder/
└── hsproject.json
└── src
    └── app/
        └── app-hsmeta.json/
        └── app-events/
            └── my-event-type-hsmeta.json
        └── cards/
            └── MyCard.jsx
            └── my-app-card-hsmeta.json
            └── package.json
        └── settings/
            └── Settings.tsx
            └── settings-hsmeta.json
            └── package.json
        └── telemetry/
            └── telemetry-hsmeta.json
        └── webhooks/
            └── webhooks-hsmeta.json
        └── workflow-actions/
            └── custom-action-hsmeta.json

​

Specifying UIDs

​

App schema

my-project-folder/
└── src
    └── app/
        └── app-hsmeta.json/

{
  "uid": "new_developer_platform_app",
  "type": "app",
  "config": {
    "description": "An example to demonstrate how to build an app with developer projects.",
    "name": "my first app",
    "distribution": "marketplace",
    "auth": {
      "type": "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

Fields marked with * are required.

​

Distribution

• If you plan to list your app on the HubSpot App Marketplace, set the distribution field to "marketplace". An example app schema for this option can be found here. If you choose this option, ensure that you set the type within the auth property to oauth, as detailed in the authentication section below.
• If you want to allow your app to be installed in a specific set of allowlisted accounts, or if you want to restrict installation to a single account at a time, set distribution to "private". Ensure that you set the type within the auth property accordingly:
  • If you want to install your app in multiple accounts based on an allowlist you configure in your project settings, set the authentication type to oauth. See the example app schema for this option here.
  • To restrict installation to a single account, either the same you use for development or another account that the installing user has access to, set the authentication type to static. An example app schema for static auth can be found here.

​

Authentication

Fields marked with * are required.

​

Scopes

"auth": {
      "type" : "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },

​

Adding app features

• Create an app card
• Define app events
• Create app objects
• Create a settings component
• Set up a custom workflow action
• Configure a webhook subscription
• Add telemetry