> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 新しい開発者プラットフォーム（ベータ版）で構築されたアプリの設定オプションに関するリファレンス情報

<style>
  {`
    .github-link a div,
    .github-link a div p {
      display: inline;
      margin: 0;
      padding: 0;
    }
    .github-link {
      background-color: rgb(255, 255, 255);
      border-radius: 24px;
      box-shadow: rgba(0, 0, 0, 0.25) 0px 2px 4px 0px;
      padding: 5px;
      max-width: 247px;
      display: flex;
      align-items: center;
      margin-bottom: 20px;
    }
    .github-icon {
        display: inline;
        width: 24px;
        margin-right: 8px;
        flex-shrink: 0;
    }
    .table-key, .table-key div, .table-key p {
      margin: 0;
      font-size: 14px;
    }
    `}
</style>

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

## プロジェクトの構成

* 全てのプロジェクトコンポーネントは、最上位レベルの`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`ファイルの設定について、詳しくは下記の[アプリ スキーマ セクション](#app-schema)を参照してください。アプリの機能を追加する準備ができたら、[アプリ機能の追加](#adding-app-features)セクションをご覧ください。

```shell theme={null}
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
```

<Card title="GitHubでサンプルを表示" href="https://github.com/robrown-hubspot/hubspot-project-components-ua-app-objects-beta/tree/main/projects/app-object-getting-started-template" icon="github" horizontal />

HubSpot Visual Studio Code拡張機能では、`*-hsmeta.json`設定ファイル内の各プロパティーの[型検証](/developer-tooling/local-development/vs-code-extension#validate-hs-meta-json-config-files)を行うことができます。

## UIDを指定する

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

## アプリスキーマ

アプリの最上位レベルの設定は、`app`ディレクトリー内の`app-hsmeta.json`設定ファイルの中で指定されます。

```shell theme={null}
my-project-folder/
└── src
    └── app/
        └── app-hsmeta.json/
```

`app-hsmeta.json`で使用できる設定オプションを以下に示します。

```json theme={null}
{
  "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"
    }
  }
}
```

<Card title="GitHubでサンプルを表示" href="https://github.com/robrown-hubspot/hubspot-project-components-ua-app-objects-beta/blob/main/projects/app-object-getting-started-template/src/app/app-hsmeta.json" icon="github" horizontal />

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

<p className="table-key">
  <span style={{ color: 'red' }}>\*</span>でマークされたフィールドは必須です。
</p>

| フィールド                                               | 型      | 説明                                                                                                                                                                                                                                              |
| --------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid`<span style={{color:"red"}}>\*</span>          | 文字列    | アプリの内部固有ID。プロジェクト全体で重複しないラベルにする必要があります。最大64文字の任意の文字列を指定できます。大文字または小文字を使用できます。数字、アンダースコア（`_`）、ダッシュ（`-`）、ピリオド（`.`）を含めることができます。                                                                                                                    |
| `type`<span style={{color:"red"}}>\*</span>         | 文字列    | コンポーネントのタイプ。親フォルダーの名前（`app`）に一致している必要があります。                                                                                                                                                                                                     |
| `description`<span style={{color:"red"}}>\*</span>  | 文字列    | インストールを実行するユーザーに対するアプリの動作の説明。最大8192文字の任意の文字列を指定できます。                                                                                                                                                                                            |
| `name`<span style={{color:"red"}}>\*</span>         | 文字列    | HubSpotに表示されるアプリの名前。最大200文字までの任意の文字列を指定できます。先頭や末尾を空白文字にすることはできません。                                                                                                                                                                              |
| `distribution`<span style={{color:"red"}}>\*</span> | 文字列    | アプリの配布方法。次のいずれかに設定できます。<ul><li>`marketplace`：アプリをHubSpotアプリマーケットプレイスへの掲載対象する場合に使用します。</li><li>`private`：許可リストに含まれる特定のアカウントセットにのみアプリをインストールする場合、または一度に1つのアカウントにのみインストールする場合にこれを使用します。</li></ul> <p>詳しくは、下記の[配布](#distribution)のセクションをご覧ください。</p> |
| `auth`<span style={{color:"red"}}>\*</span>         | オブジェクト | アプリの認証方法の詳細を含むオブジェクト。詳しくは、下記の[認証のセクション](#authentication)をご覧ください。                                                                                                                                                                                |
| `permittedUrls`                                     | オブジェクト | アプリが呼び出すことができるURLを含む配列。URLではHTTPSスキームを使用する必要があります。また、URLには[オーソリティー](https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_URL#authority)、とその後に（必要に応じて）オプションのパスプレフィックスを含める必要があります。                        |
| `supportEmail`                                      | 文字列    | ユーザーがサポートを受けるために連絡できる有効なEメールアドレス。                                                                                                                                                                                                               |
| `documentationUrl`                                  | 文字列    | ユーザーがサポートドキュメントを参照するためにアクセスできる外部URL。HTTPSを使用する必要があります。                                                                                                                                                                                          |
| `supportUrl`                                        | 文字列    | ユーザーが追加のサポートを受けるためにアクセスできる外部URL。HTTPSを使用する必要があります。                                                                                                                                                                                              |
| `supportPhone`                                      | 文字列    | ユーザーがサポートを受けるために連絡できる電話番号。プラス記号（`+`）で始まる必要があります。                                                                                                                                                                                                |

### 配布

アプリスキーマの`distribution`フィールドを使用すると、アプリの配布方法を次のように設定できます。

* [HubSpotアプリマーケットプレイス](https://ecosystem.hubspot.com/marketplace/apps)にアプリを掲載する予定の場合は、`distribution`フィールドを`"marketplace"`に設定します。このオプションのアプリスキーマの例については、[こちら](https://github.com/robrown-hubspot/hubspot-project-components-ua-app-objects-beta/blob/main/projects/public-app-getting-started-template/src/app/app-hsmeta.json)をご覧ください。このオプションを選択する場合は、下記の[認証](#authentication)セクションで詳しく説明されているように、`auth`プロパティー内の`type`を必ず`oauth`に設定してください。
* 許可リストに含まれる特定のアカウントセットにアプリのインストールを許可する場合、またはインストールを一度に1つのアカウントに制限する場合には、`distribution`を`"private"`に設定します。`auth`プロパティー内の`type`を、次のように適切に設定してください。
  * [プロジェクト設定で構成した許可リスト](/apps/developer-platform/build-apps/manage-apps-in-hubspot#manage-authentication-for-your-app)に基づき複数のアカウントにアプリをインストールするには、認証の`type`を`oauth`に設定します。このオプションのアプリスキーマの例については、[こちら](https://github.com/robrown-hubspot/hubspot-project-components-ua-app-objects-beta/blob/main/projects/private-app-oauth-getting-started-template/src/app/app-hsmeta.json)を参照してください。
  * インストールを1つのアカウント（開発に使用するのと同じアカウント、またはインストールするユーザーがアクセスできる別のアカウント）に制限するには、認証の`type`を`static`に設定します。静的認証のアプリスキーマの例については、[こちら](https://github.com/robrown-hubspot/hubspot-project-components-ua-app-objects-beta/blob/main/projects/private-app-static-getting-started-template/src/app/app-hsmeta.json)を参照してください。

### 認証

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

<p className="table-key">
  <span style={{ color: 'red' }}>\*</span>でマークされたフィールドは必須です。
</p>

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

### スコープ

アプリ設定ファイルの`auth`フィールドでは、必須スコープ、条件次第で必須となるスコープ、任意のスコープという[3種類のスコープ](/apps/legacy-apps/public-apps/overview#scope-types)を指定できます。

関連付けられたCRMオブジェクトタイプに顧客がアクセスできるようにするには、少なくとも`read`スコープをアプリに含める必要があります。

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

```

使用可能な全てのスコープのリストについては、[スコープリファレンス](/apps/legacy-apps/authentication/scopes)を参照してください。

## アプリ機能を追加する

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

* [アプリカードを作成する](/apps/developer-platform/add-features/ui-extensibility/app-cards/create-an-app-card)
* [アプリイベントを定義する](/apps/developer-platform/add-features/app-events/overview)
* [アプリオブジェクトを作成する](/apps/developer-platform/add-features/app-objects/quickstart-guide-to-app-objects)
* [設定コンポーネントを作成する](/apps/developer-platform/add-features/ui-extensibility/create-a-settings-component)
* [カスタム ワークフロー アクションを設定する](/apps/developer-platform/add-features/custom-workflow-actions)
* [Webhook配信登録を設定する](/apps/developer-platform/add-features/configure-webhooks)
* [テレメトリーを追加する](/apps/developer-platform/add-features/add-telemetry)