アプリの設定（ベータ版）

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

プロジェクトの構成

全てのプロジェクトコンポーネントは、最上位レベルの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ファイルをプロジェクトに追加する方法を詳しくご確認ください。

アプリを作成

機能を追加

HubSpotマーケットプレイスに公開

アプリの設定（ベータ版）

プロジェクトの構成

GitHubでサンプルを表示

UIDを指定する

アプリスキーマ

GitHubでサンプルを表示

配布

認証

スコープ

アプリ機能を追加する

​プロジェクトの構成

GitHubでサンプルを表示

​UIDを指定する

​アプリスキーマ

GitHubでサンプルを表示

​配布

​認証

​スコープ

​アプリ機能を追加する

プロジェクトの構成

UIDを指定する

アプリスキーマ

配布

認証

スコープ

アプリ機能を追加する