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/ .
  • App pages are defined within pages/.
  • Settings page features are defined within settings/.
  • Serverless functions are configured within functions/.
  • 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
        └── app-objects/
            └── my-app-object-hsmeta.json
        └── cards/
            └── MyCard.jsx
            └── my-app-card-hsmeta.json
            └── package.json
        └── functions/
            └── NewFunction.js
            └── private-function-hsmeta.json
            └── package.json
        └── pages/
            └── Pages.tsx
            └── pages-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",
    "logo": "/app/app-logo.png",
    "distribution": "marketplace",
    "isUserLevel": true,
    "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"
    }
  }
}

​

Distribution

• If you plan to list your app on the HubSpot Marketplace, set the distribution field to "marketplace". 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.
  • 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.

​

Authentication

​

Scopes

{
  "uid": "oauth-sample-app",
  "type": "app",
  "config": {
    "description": "An example OAuth app.",
    "name": "my first app",
    "logo": "/app/app-logo.png",
    "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"
    }
  }
}

​

Adding app features

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