メインコンテンツへスキップ
以下でアプリカードの作成に関する参照情報を紹介します。

​
プロジェクトの構成

プロジェクトのコンテキストでは、アプリカードのコンポーネントはapp/内のcardsディレクトリーで定義されています。cardsディレクトリーには以下が含まれている必要があります。
  • 各カードタイプのJSONスキーマ定義ファイル（*-hsmeta.json）。
  • カードのフロントエンドをレンダリングするReactファイル。.jsxファイルまたは.tsxファイルを使用できます。
  • 必要なすべての依存関係を処理するためのpackage.jsonファイル。
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── cards/
            └── my-app-card-hsmeta.json
            └── my-app-card.jsx
            └── package.json

​
アプリカードのスキーマ

アプリカードの*-hsmeta.json設定ファイルに以下のプロパティーを指定します。 
{
  "uid": "example-card",
  "type": "card",
  "config": {
    "name": "Hello Example App",
    "description": "A description of the card's purpose.",
    "location": "crm.record.tab",
    "entrypoint": "/app/cards/ExampleCard.jsx",
    "objectTypes": ["contacts"]
  }
}

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

フィールド型説明
uid*文字列カードの固有ID。任意の文字列を指定できますが、カードを識別できる意味のある文字列である必要があります。HubSpotではこのIDでカードが識別されるため、CRMレコードの位置などの履歴データやステートフルデータを削除することなく、カードのタイトルを変更できます。
type文字列コンポーネントのタイプ。この場合はcardにする必要があります。
configオブジェクト設定の詳細を含むオブジェクト。
name*文字列HubSpotのUIに表示されるカードのタイトル。
description文字列カードの説明。
previewImageオブジェクトfileフィールドとaltTextフィールドを含むオブジェクト。fileフィールドは、プレビュー画像の相対パスです。有効なファイル拡張子はpng、jpeg、jpg、gifです。最大ファイルサイズは5.0MBです。altTextフィールドは、画像の簡単な説明です。
entrypoint*文字列カードのフロントエンドReactコードのファイルパス。
location*crm.record.tab | crm.record.sidebar | crm.preview |helpdesk.sidebarHubSpotのUIでカードが表示される場所。場所（location）の値は1つしか指定できませんが、locationとobjectTypesの組み合わせによっては、複数の場所がサポートされることもあります。詳細については、後述の__サポートされる場所セクションをご確認ください。
objectTypes*配列このカードが表示されるCRMレコードのタイプ。詳細については、後述のサポートされるオブジェクト__セクションをご確認ください。

​
サポートされるオブジェクト

カードの*-hsmeta.json設定ファイルのobjectTypes配列により、カードが表示されるCRMレコードのタイプが指定されます。現在サポートされているCRMオブジェクトとそのobjectType値、およびアプリに追加する最小スコープを以下に示します。
HubSpotの標準オブジェクトの場合、objectTypeの値では大文字と小文字が区別されず、単数形と複数形の両方がサポートされています。例えば、"CONTACT"と"contacts"はどちらも有効です。
CRMオブジェクトobjectTypeの値関連スコープ
コンタクトCONTACTcrm.objects.contacts.read
会社COMPANYcrm.objects.companies.read
取引DEALScrm.objects.deals.read
チケットTICKETStickets
カスタムオブジェクトp_objectName（大文字小文字の区別あり）crm.objects.custom.read
アプリオブジェクトapp_object_uidアプリオブジェクトのスコープを参照
また、以下のCRMオブジェクトがオブジェクトライブラリーで有効化されている場合は、これらのオブジェクトもサポートされます。
CRMオブジェクトobjectTypeの値関連スコープ
アポイントメントAPPOINTMENTScrm.objects.appointments.read
コースCOURSEScrm.objects.courses.read
掲載情報LISTINGScrm.objects.listings.read
サービスSERVICEScrm.objects.services.read

​
サポートされる場所

カードの*-hsmeta.json設定ファイルのlocationフィールドに、HubSpotでカードが表示される場所を指定します。現在サポートされている場所を以下に示します。
以前に中央列をカスタマイズしている場合は、新しく作成された拡張機能が表示されるように中央列ビューをカスタマイズする必要があります。
  • crm.preview：CRMでアクセスできるプレビューパネルにアプリカードが表示されます。この場所を使用する場合、JSON設定ファイルで指定されているobjectTypesをプレビューするときに拡張機能が利用可能になります。これには、CRMレコードページ、インデックスページ、ボードビュー、リストツール内でのレコードのプレビューが含まれます。プレビューのカスタマイズの詳細をご確認ください。
  • helpdesk.sidebar：ヘルプデスク内のチケットサイドバーにカードが表示されます。これには、ヘルプデスク ホーム ページのチケット プレビュー パネルとヘルプデスクの右サイドバーの両方が含まれます。この場所にカードを追加するには、ヘルプデスク設定を構成してカードを含める必要があります。
この場所に拡張機能を作成するときには、アプリのJSON設定ファイルのscopes配列にticketsが含まれており、カードのJSON設定ファイルのobjectTypesフィールドにticketsが含まれていることを確認する必要もあります。

​
Reactフロントエンドの作成

アプリカードのUIは、Reactコンポーネントファイル（.jsxまたは.tsx）により作成されます。このファイルは、カードのJSON設定ファイル（*-hsmeta.json）と共にcards/ディレクトリーに含まれています。カード設定ファイルのentrypointフィールドに、Reactファイルのパスを指定します。 シンプルなアプリカードの例を以下に示します。この例には、カードのコンテンツを表示するUIコンポーネントであるTextおよびButtonと、レイアウトを管理するためのFlexコンポーネントが含まれています。 
import React from "react";
import { Text, Button, Flex, hubspot } from "@hubspot/ui-extensions";

// Define the extension to be run within the Hubspot CRM
hubspot.extend(() => <Extension />);

// Define the Extension component
const Extension = () => {
  return (
    <Flex direction="column" gap="medium">
      <Text>This is a simple getting started UI extension with static text.</Text>
      <Button onClick={() => console.log("Button clicked!")}>Click me!</Button>
    </Flex>
  );
};
カードの外観と機能の作成に関しては、以下の参照ドキュメントが提供されています。

​
依存関係の管理

cards/ディレクトリー内にあるpackage.jsonファイルにアプリカードの依存関係を指定できます。hs project addコマンドでアプリカードを追加すると、既定では次の依存関係を持つpackage.jsonファイルが作成されます。
  • @hubspot/ui-extensions
  • react
  • typescript
package.jsonファイルを使用してプロジェクトコンポーネントの依存関係をインストールするには、プロジェクトディレクトリーでhs project install-depsコマンドを実行できます。 
{
  "name": "hubspot-example-extension",
  "version": "0.1.0",
  "license": "MIT",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}
Last modified on December 10, 2025