> ## 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.

# カスタムイベントの定義

export const ScopesList = ({scopes = [], description = "この API には、次のいずれかのスコープが必要です。"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<RelatedApiLink />

<ProductTier
  tiers={[
'marketing_hub-enterprise',
'sales_hub-enterprise',
'cms-enterprise',
'service_hub-enterprise',
'operations_hub-enterprise',
]}
/>

カスタムイベントを使用すれば、サイト上でのイベントやアプリ内のイベントなど、ビジネスに固有のイベントを定義して追跡できます。情報をプロパティーに格納するようにイベントを構成し、そのイベントをHubSpotのツール全体で使用することができます。

[カスタムイベント](/api-reference/events-send-event-completions-v3/guide)のデータをHubSpotに送信するには、まずイベントを定義する必要があります。カスタムCRMオブジェクトと同様に、最初にカスタムオブジェクトを定義してからでないと、そのオブジェクトに関する個々のレコードを作成できません。イベント定義には、イベントのメタデータ、CRMオブジェクトの関連付け、プロパティーなどの詳細が含まれます。

以下にて、イベントAPIを使用してイベント定義を作成し、管理する方法をご説明します。APIを使用せずにイベント定義を作成する方法については、[HubSpotのナレッジベース](https://knowledge.hubspot.com/ja/reports/create-custom-events)をご覧ください。

<Accordion title="スコープ要件">
  <ScopesList
    scopes={[
  'behavioral_events.event_definitions.read_write'
]}
  />
</Accordion>

## イベント定義を作成する

カスタムイベントスキーマを作成するには、`POST`リクエストを`events/v3/event-definitions`に送信します。リクエスト本文に、イベントスキーマの定義（イベントのラベル、名前、CRMオブジェクトの関連付け、カスタムプロパティーなど）を含めます。

以下のリクエスト本文は、イベント定義の基本的な例を示しています。

```json theme={null}
{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "choice-property",
      "label": "Choice property",
      "type": "enumeration",
      "options": [
        {
          "label": "Option 1",
          "value": "1"
        },
        {
          "label": "Option 2",
          "value": "2"
        }
      ]
    },
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "includeDefaultProperties": true
}
```

指定したCRMオブジェクトタイプのレコードにイベントの完了を自動的にリンクさせるには、`POST`リクエストに`customMatchingId`を含めます。このフィールド内に、2つのフィールドを使用して`primaryObjectRule`オブジェクトを定義します。それは、`targetObjectPropertyName`として事前に設定しておいた一意のオブジェクトプロパティーと、イベント定義の`propertyDefinitions`で定義したプロパティーです。

例えば、以下のリクエスト本文では、CRMオブジェクトプロパティー名の`"unique_object_property"`とイベントプロパティー名の`"string_property"`に一致する`customMatchingId`を指定しています。

```json theme={null}
{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "customMatchingId": {
    "primaryObjectRule": {
      "targetObjectPropertyName": "unique_object_property",
      "eventPropertyName": "event_property"
    }
  }
}
```

リクエスト本文で使用できる全てのパラメーターを、以下の表で詳しく説明します。

| パラメーター                     | タイプ    | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`                    | 文字列    | HubSpotに表示する、人間が読んで理解できるイベントのラベル（最大100文字）。HubSpotのUIの特定の部分では、文字数の多いラベルが切り詰められる場合があります。                                                                                                                                                                                                                                                                                                                                                            |
| `name`                     | 文字列    | イベントの一意の内部名。APIを介してイベントを参照する際は、この内部名を使用します。値を指定しない場合、HubSpotではラベルに基づいて値が自動的に生成されます。<ul><li>このプロパティーをイベント定義の作成後に変更することはできません。</li><li>このプロパティーに使用できるのは小文字の英字、数字、アンダースコア、ハイフンのみです（最大50文字）。</li><li>最初の文字は英字でなければなりません。</li></ul>                                                                                                                                                                                                                    |
| `description`              | 文字列    | HubSpotに表示するイベントの説明。                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `primaryObject`            | 文字列    | イベントデータが関連付けられるCRMオブジェクトのタイプ。イベントの完了は、そのオブジェクトタイプのCRMレコードに表示されます。指定できる値は、`"CONTACT"`（デフォルト）、`"COMPANY"`、`"DEAL"`、`"TICKET"`、`"<CUSTOM_OBJECT_NAME>"`です。イベント定義が作成された後にこのプロパティーを変更することはできません。                                                                                                                                                                                                                                                       |
| `propertyDefinitions`      | 配列     | [HubSpotのデフォルトのイベントプロパティー](#hubspot-s-default-event-properties)に加え、この配列を含めることでカスタムイベントプロパティーを定義できます（最大50個）。各プロパティーオブジェクトには、次のフィールドを含めます。<ul><li>`name`：APIを介してイベントデータを送信するときに使用するプロパティーの内部名。</li><li>`label`：プロパティーのアプリ内ラベル。</li><li>`type`：[プロパティーのタイプ](#event-properties)。デフォルト値は`string`です。</li><li>`options`：`enumeration`型プロパティーの場合、この配列で使用可能な値を定義します。各オプションの`label`と`value`の両方を含める必要があります。</li><li>`description`：プロパティーを説明するテキスト。</li></ul> |
| `customMatchingId`         | オブジェクト | ターゲットオブジェクトの`objectId`をイベント完了データに含める代わりに、このオプションフィールドでは、指定されたCRMオブジェクトタイプのレコードにイベント完了を自動的にリンクするルールを定義します。これは、イベントデータのプロパティーの値をターゲットオブジェクトの<u>一意</u>のプロパティー値と照合することによって行われます。このオブジェクトにはネストされた`primaryObjectRule`オブジェクトを含める必要があり、さらに2つのフィールドを含める必要があります。<ul><li>`targetObjectPropertyName`：照合に使用するターゲットCRMオブジェクトの一意のプロパティーの名前を指定する文字列。</li><li>`eventPropertyName`：照合に使用するカスタムイベントデータ内のプロパティーの名前を指定する文字列。</li></ul>                                 |
| `includeDefaultProperties` | ブール値   | デフォルトの[イベントプロパティー](#hubspot-s-default-event-properties)のセットをイベントに含めるかどうかを指定する任意のフィールド。値を指定しない場合、このフィールドは自動的に`true`に設定されます。                                                                                                                                                                                                                                                                                                                        |

## イベントプロパティー

カスタムイベントプロパティーは、個々のカスタムイベント完了に関する情報を格納するために使用します。イベント完了を送信する際に適切であれば、カスタムイベントプロパティーを使用すべきですが、イベント完了を有効にするために、これらのプロパティーが必須となるわけではありません。HubSpotではイベント定義ごとに、32個のデフォルトのプロパティーを用意しています。デフォルトのプロパティーに加え、イベント定義ごとに最大50個のカスタムプロパティーを含めることができます。

プロパティーには、次のいずれかの型を指定できます。

* `bool`：ブール値を受け取るプロパティー。値は`true`または`false`として表す必要があります。
* `date`：特定の年月日を表す日付を受け取るプロパティー。値はUTC時間で表す必要があります。値の形式として、[ISO 8601文字列](/api-reference/crm-properties-v3/guide#add-values-to-date-and-datetime-properties)またはミリ秒単位のエポック時間タイムスタンプ（UTC深夜0時）を使用できます。
* `datetime`：タイムスタンプを表すエポックミリ秒またはISO8601の値を受け取るプロパティー。
* `enumeration`：定義済みのオプションを使用するプロパティー。このタイプのプロパティーを作成する際は、使用可能な値を設定するために`options`配列を含めます。
* `number`：小数第1位までの数値を受け取るプロパティー。
* `string`：プレーンテキスト文字列を受け取るプロパティー。プロパティー名に`url`、`referrer`、または`link`という単語が含まれる場合、プロパティー値は最大1,024文字にすることができます。それ以外の場合、プロパティー値は最大256文字に制限されます。

以降のセクションで、HubSpotのデフォルトのイベントプロパティーと、[既存のイベントに新しいプロパティーを定義する](#define-new-properties)方法、[既存のカスタムイベントプロパティーを更新する](#update-existing-custom-properties)方法について説明します。

### HubSpotのデフォルトのイベントプロパティー

* `hs_asset_description`
* `hs_asset_type`
* `hs_browser`
* `hs_campaign_id`
* `hs_city`
* `hs_country`
* `hs_device_name`
* `hs_device_type`
* `hs_element_class`
* `hs_element_id`
* `hs_element_text`
* `hs_language`
* `hs_link_href`
* `hs_operating_system`
* `hs_operating_version`
* `hs_page_content_type`
* `hs_page_id`
* `hs_page_title`
* `hs_page_url`
* `hs_parent_module_id`
* `hs_referrer`
* `hs_region`
* `hs_screen_height`
* `hs_screen_width`
* `hs_touchpoint_source`
* `hs_tracking_name`
* `hs_user_agent`
* `hs_utm_campaign`
* `hs_utm_content`
* `hs_utm_medium`
* `hs_utm_source`
* `hs_utm_term`

### 新しいプロパティーを定義する

既存のカスタムイベントの新しいプロパティーを定義するには、`POST`リクエストを`events/v3/event-definitions/{eventName}/property`に送信します。リクエスト本文に、プロパティーの定義を含めます。

```json theme={null}
{
  "name": "property-name",
  "label": "Property name",
  "type": "enumeration",
  "options": [
    {
      "label": "label",
      "value": "value"
    }
  ]
}
```

プロパティーに名前を付ける際は、次の点に留意してください。

* プロパティーを作成した後に、プロパティーの名前を変更することはできません。
* 名前に使用できるのは、小文字の英字、数字、アンダースコア、ハイフンのみです。
* プロパティー名の最初の文字は英字でなければなりません。
* プロパティーの名前とラベルは、それぞれ最大50文字に制限されています。
* プロパティー名が指定されていない場合、プロパティーのラベルを使用してプロパティー名が自動生成されます。
* HubSpotのUIの特定の部分では、文字数の多いラベルが切り詰められる場合があります。

### 既存のカスタムプロパティーを更新する

カスタムイベントの既存のプロパティーを更新するには、`PATCH`リクエストを`events/v3/event-definitions/{eventName}/property`に送信します。プロパティーで更新できるフィールドは、列挙プロパティーの`label`、`description`、`options`のみです。

<Warning>
  ### 注：

  プロパティーの型を変更するには、`DELETE`エンドポイントを使用してプロパティーを削除してから、適切な型でプロパティーを再作成します。
</Warning>

### プロパティーを削除する

カスタムイベントの既存のプロパティーを削除するには、`DELETE`リクエストを`events/v3/event-definitions/{eventName}/property/{propertyName}`に送信します。

プロパティーが削除されると、そのプロパティーは以降のイベント完了で使用できなくなります。ただし、削除前のイベント完了では、削除されたプロパティーの値が維持されます。

## イベントを更新する

既存のカスタムイベントスキーマを更新するには、`PATCH`リクエストを`events/v3/event-definitions/{eventName}`に送信します。

更新できるイベント定義フィールドは、`label`と`description`のみです。

```json theme={null}
{
  "label": "Event label",
  "description": "A description of the event"
}
```

## イベントを削除する

カスタムイベントを削除するには、`DELETE`リクエストを`events/v3/event-definitions/{eventName}`に送信します。

カスタムイベントを削除すると、ワークフローやレポートなど、そのイベントを参照している他のHubSpotツールから削除されます。

<Warning>
  ### イベントを削除する場合の注意事項

  1. そのイベント定義の全てのイベントが削除されて、復元できなくなります。
  2. 以前に削除した`eventName`は<u>使えません</u>。イベントを削除するときは注意が必要です。
</Warning>

## 既存のイベント定義を取得する

単一のイベント定義を取得するには、`GET`リクエストを`events/v3/event-definitions/{eventName}`に送信します。

特定の条件でイベント定義を検索するには、`GET`リクエストを`events/v3/event-definitions`に送信します。次のクエリーパラメーターを指定して、検索を絞り込むことができます。

* `searchString`：指定した文字列が`name`フィールドに含まれているイベントを検索します。あいまい検索では<u>なく</u>、単純に「含まれているかどうか」で検索されます。
* `after`：ページ処理されたレスポンスに表示される、検索結果の次のページを表示するためのハッシュ化された文字列。
* `limit`：取得する結果の最大数。
* `includeProperties`：返される結果にイベントプロパティーを含めるかどうかを指定するブール値。