最終更新日: 2025年9月11日
以下では、開発者プラットフォームのアプリ機能に関するリファレンス情報（設定ファイルの定義、スコープの詳細など）を紹介します。

​
プロジェクトの構成

  • 全てのプロジェクトコンポーネントは、最上位レベルのhsproject.json設定ファイルで指定されたsrcディレクトリー内に配置される必要があります。
  • アプリの全ての機能とコンポーネントはsrc/app/ディレクトリー内に配置される必要があります。このapp/ディレクトリー内に、アプリでサポートする予定の機能ごとのサブディレクトリーを次のように定義します。
    • アプリイベントはapp-events/内で設定されます。
    • アプリオブジェクトはapp-objects/内で定義されます。
    • 全てのカード機能はcards/内で定義されます。
    • 設定ページ機能はsettings/内で定義されます。
    • テレメトリーはtelemetry/内で設定されます。
    • Webhook配信登録はwebhooks/内で定義されます。
    • カスタム ワークフロー アクションはworkflow-actions/内で定義されます。
  • 各機能のサブディレクトリー内で、*-hsmeta.jsonファイルを使用して機能を設定します。ファイル名の前に、そのアプリを記述する名前（例：my-app-hsmeta.json）を付けることができます。ただし、ファイルの末尾は-hsmeta.jsonである必要があります。これらのファイルは、該当するフォルダーのルートレベルに配置されている必要があります（例：app/my-app-hsmeta.json、cards/my-card-hsmeta.json）。
以下のディレクトリー構造の例は、利用可能な全ての機能の概要を示しています。最上位レベルのアプリスキーマapp-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

GitHubでサンプルを表示

 HubSpot Visual Studio Code拡張機能では、*-hsmeta.json設定ファイル内の各プロパティーの型検証を行うことができます。

​
UIDを指定する

uidフィールドは、特定のアプリ内部で一意の識別子です。また、これはプロジェクト全体で重複しないラベルにする必要があります。アプリ機能ごとに、それぞれの*-hsmeta.jsonファイル内に独自のuidが定義されます。これは、アプリのapp-hsmeta.jsonファイルで選択する最上位レベルuidとは区別される必要があります。

​
アプリスキーマ

アプリの最上位レベルの設定は、appディレクトリー内のapp-hsmeta.json設定ファイルの中で指定されます。 
my-project-folder/
└── src
    └── app/
        └── app-hsmeta.json/
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"
    }
  }
}

GitHubでサンプルを表示

 各設定オプションの詳細については、次の表をご覧ください。アプリの配布、認証の設定、スコープの指定に関する詳しいコンテキスト情報は、表の下のセクションにあります。

*でマークされたフィールドは必須です。

フィールド型説明
uid*文字列アプリの内部固有ID。プロジェクト全体で重複しないラベルにする必要があります。最大64文字の任意の文字列を指定できます。大文字または小文字を使用できます。数字、アンダースコア（_）、ダッシュ（-）、ピリオド（.）を含めることができます。
type*文字列コンポーネントのタイプ。親フォルダーの名前（app）に一致している必要があります。
description*文字列インストールを実行するユーザーに対するアプリの動作の説明。最大8192文字の任意の文字列を指定できます。
name*文字列HubSpotに表示されるアプリの名前。最大200文字までの任意の文字列を指定できます。先頭や末尾を空白文字にすることはできません。
distribution*文字列アプリの配布方法。次のいずれかに設定できます。
  • marketplace：アプリをHubSpotアプリマーケットプレイスへの掲載対象する場合に使用します。
  • private：許可リストに含まれる特定のアカウントセットにのみアプリをインストールする場合、または一度に1つのアカウントにのみインストールする場合にこれを使用します。

詳しくは、下記の配布のセクションをご覧ください。

auth*オブジェクトアプリの認証方法の詳細を含むオブジェクト。詳しくは、下記の認証のセクションをご覧ください。
permittedUrlsオブジェクトアプリが呼び出すことができるURLを含む配列。URLではHTTPSスキームを使用する必要があります。また、URLにはオーソリティー、とその後に（必要に応じて）オプションのパスプレフィックスを含める必要があります。
supportEmail文字列ユーザーがサポートを受けるために連絡できる有効なEメールアドレス。
documentationUrl文字列ユーザーがサポートドキュメントを参照するためにアクセスできる外部URL。HTTPSを使用する必要があります。
supportUrl文字列ユーザーが追加のサポートを受けるためにアクセスできる外部URL。HTTPSを使用する必要があります。
supportPhone文字列ユーザーがサポートを受けるために連絡できる電話番号。プラス記号（+）で始まる必要があります。

​
配布

アプリスキーマのdistributionフィールドを使用すると、アプリの配布方法を次のように設定できます。
  • HubSpotアプリマーケットプレイスにアプリを掲載する予定の場合は、distributionフィールドを"marketplace"に設定します。このオプションのアプリスキーマの例については、こちらをご覧ください。このオプションを選択する場合は、下記の認証セクションで詳しく説明されているように、authプロパティー内のtypeを必ずoauthに設定してください。
  • 許可リストに含まれる特定のアカウントセットにアプリのインストールを許可する場合、またはインストールを一度に1つのアカウントに制限する場合には、distributionを"private"に設定します。authプロパティー内のtypeを、次のように適切に設定してください。
    • プロジェクト設定で構成した許可リストに基づき複数のアカウントにアプリをインストールするには、認証のtypeをoauthに設定します。このオプションのアプリスキーマの例については、こちらを参照してください。
    • インストールを1つのアカウント（開発に使用するのと同じアカウント、またはインストールするユーザーがアクセスできる別のアカウント）に制限するには、認証のtypeをstaticに設定します。静的認証のアプリスキーマの例については、こちらを参照してください。

​
認証

アプリの認証を設定するには、アプリスキーマのauthプロパティーを使用します。アプリのスコープ要件、リダイレクトURL、認証タイプを指定できます。

*でマークされたフィールドは必須です。

フィールド型説明
type*文字列認証タイプ。次のいずれかに設定できます。
  • oauth：OAuth経由でのインストールを許可します。このインストールは、許可リストに登録された特定のアカウントに対してのみ行うか、HubSpotアプリマーケットプレイスに掲載して行います。
  • static：アプリのインストールを、インストールを実行するユーザーがアクセスできる1つのアカウントに制限します。
redirectUrls*配列OAuthプロセスで再ルーティング先として許可されるURLのリスト。各アプリには少なくとも1つの認証リダイレクトURLが必要であり、このURLではHTTPSを使用する必要があります。唯一の例外として、テスト目的の場合はhttp://localhostを使用できます。
requiredScopes*配列アプリの必須スコープのリスト。各アプリには少なくとも1つのスコープが含まれる必要があります。アプリを正常にインストールするには、インストールを行うユーザーがこれらのスコープを付与する必要があります。スコープの詳細については、以下の説明をご確認ください。
optionalScopes配列アプリの任意のスコープのリスト。アプリをインストールするアカウントまたはユーザーに適切な権限がない場合は、インストール時にこれらのスコープを認証から除外できます。その場合、作成されるリフレッシュトークンやアクセストークンにはスコープが含まれません。スコープの詳細については、以下の説明をご確認ください。
conditionallyRequiredScopes配列インストールURLのscopeクエリーパラメーターに含まれている場合にのみ必須であるスコープのリスト。スコープの詳細については、以下の説明をご確認ください。

​
スコープ

アプリ設定ファイルのauthフィールドでは、必須スコープ、条件次第で必須となるスコープ、任意のスコープという3種類のスコープを指定できます。 関連付けられたCRMオブジェクトタイプに顧客がアクセスできるようにするには、少なくともreadスコープをアプリに含める必要があります。 
"auth": {
      "type" : "oauth",
      "redirectUrls": ["http://localhost:3000/oauth-callback"],
      "requiredScopes": [
        "crm.objects.contacts.read",
        "crm.objects.contacts.write"
      ],
      "optionalScopes": [],
      "conditionallyRequiredScopes": []
    },
使用可能な全てのスコープのリストについては、スコープリファレンスを参照してください。

​
アプリ機能を追加する

Webhook配信登録、カスタム ワークフロー アクション、アプリカードなどのアプリ機能を設定するには、下記のガイドを参照して、関連する*-hsmeta.jsonファイルをプロジェクトに追加する方法を詳しくご確認ください。