> ## 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 SupportedProducts = ({marketing, sales, service, cms, marketingLevel, salesLevel, serviceLevel, cmsLevel}) => {
  const translations = {
    header: "サポートされる製品",
    description: "次のいずれかの製品またはそれ以上が必要です。",
    productNames: {
      marketing: "Marketing Hub",
      sales: "Sales Hub",
      service: "Service Hub",
      cms: "Content Hub"
    },
    tiers: {
      free: "無料ツール",
      starter: "Starter",
      professional: "Professional",
      enterprise: "Enterprise"
    }
  };
  const translateTier = tier => {
    if (!tier) return '';
    const lowerTier = tier.toLowerCase();
    return translations.tiers[lowerTier] || tier;
  };
  const products = [{
    name: marketing ? translations.productNames.marketing : '',
    level: translateTier(marketingLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/marketing-bolt.svg",
    alt: "Marketing Hub"
  }, {
    name: sales ? translations.productNames.sales : '',
    level: translateTier(salesLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/sales-star.svg",
    alt: "Sales Hub"
  }, {
    name: service ? translations.productNames.service : '',
    level: translateTier(serviceLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/service-heart.svg",
    alt: "Service Hub"
  }, {
    name: cms ? translations.productNames.cms : '',
    level: translateTier(cmsLevel),
    icon: "https://mintlify-assets.b-cdn.net/Icons/content-play.svg",
    alt: "Content Hub"
  }].filter(product => product.name && product.level);
  if (products.length === 0) return null;
  return <div>
      <div className="text-sm mb-2">{translations.description}</div>
      <div className={`grid ${products.length === 1 ? 'grid-cols-1' : 'grid-cols-2'} gap-1.5`}>
        {products.map((product, index) => <div key={index} style={{
    display: 'flex',
    alignItems: 'center'
  }}>
            <img src={product.icon} alt={product.alt} className="w-3.5 h-3.5 mr-1.5 mt-2.5 mb-2.5 flex-shrink-0 align-middle" />
            <span className="font-medium mr-1 text-sm">{product.name} -</span>
            <span className="text-sm">{product.level}</span>
          </div>)}
      </div>
    </div>;
};

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>;
};

<AccordionGroup>
  <Accordion title="サポートされる製品" defaultOpen="true" icon="cubes">
    <SupportedProducts marketing={true} marketingLevel="enterprise" sales={true} salesLevel="enterprise" service={true} serviceLevel="enterprise" cms={true} cmsLevel="enterprise" />
  </Accordion>

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

<RelatedApiLink />

カスタムイベントは、イベントの詳細をイベントプロパティーに格納するアカウント定義のイベントです。イベントデータをHubSpotに送信するように[追跡コードをカスタマイズ](/api-reference/legacy/tracking-code-v1/overview)できるだけでなく、このAPIを介してイベント完了データを送信することもできます。

APIを使用してカスタムイベントを作成し、カスタムイベントデータを送受信する方法について以下に説明します。

## イベントの定義

イベント完了データをHubSpotに送信するには、まず、イベントのメタデータ、CRMオブジェクト、関連付け、プロパティーなど、イベント自体を定義する必要があります。イベントを定義するには、[カスタムイベント定義API](/api-reference/events-manage-event-definitions-v3/guide)を使用するか、**Marketing Hub** Enterpriseをご利用の場合は[HubSpotでイベントを作成](https://knowledge.hubspot.com/ja/analytics-tools/create-codeless-custom-behavioral-events)することができます。イベントを作成するとHubSpotによって[デフォルトのイベントプロパティー](/api-reference/events-manage-event-definitions-v3/guide#hubspot-s-default-event-properties)のセットが追加され、ユーザーはそこにイベントデータを格納できます。イベントの[追加プロパティーを作成](/api-reference/events-manage-event-definitions-v3/guide#define-new-properties)することもできます。イベントのプロパティーは、いつでも作成または編集できます。

イベントを設定したら、APIを介して、または[HubSpotトラッキングコードをカスタマイズ](/api-reference/legacy/tracking-code-v1/overview)して、イベントにデータを送信できます。

## イベントデータを送信する

イベントデータをHubSpotに送信するには、リクエスト本文にイベントデータを指定して、`POST`リクエストを`https://api.hubspot.com/events/v3/send`に送信します。イベントデータを送信する前に、後述の制限を確認してください。制限を超えるとエラーが発生します。

```json theme={null}
{
  "eventName": "pe1234567_login_event",
  "objectId": "608051",
  "occurredAt": "2024-06-28T12:09:31Z",
  "properties": {
    "hs_city": "Cambridge",
    "hs_country": "United States",
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE",
    "hs_device_type": "PDA;Smartphone",
    "hs_touchpoint_source": "DIRECT_TRAFFIC"
  }
}
```

| パラメーター       | タイプ    | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventName`  | 文字列    | イベントの内部名。これを確認するには、[既存のイベント定義をクエリー](/api-reference/events-manage-event-definitions-v3/guide#get-existing-event-definitions)するか、[HubSpotアプリ内で確認](https://knowledge.hubspot.com/ja/reports/create-custom-events#find-internal-name)します。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `objectId`   | 必須文字列  | イベントが関連付けられるCRMレコードのID。コンタクトの場合は、`email`または`utk`フィールドを使用して、Eメールアドレスまたは[HubSpotユーザートークン](/api-reference/legacy/tracking-code-v1/overview)でコンタクトを識別することもできます。イベントにカスタム一致IDが定義されていない限り、他の全てのオブジェクトタイプでは`objectId`が必要です。イベントに`customMatchingId`が定義されている場合、HubSpotは設定されたマッピングに基づいて`objectId`を自動的に設定またはオーバーライドします。詳しくは[カスタムイベント定義ガイド](/api-reference/events-manage-event-definitions-v3/guide#create-an-event-definition)をご参照ください。                                                                                                                                                                                                                                                                                            |
| `occurredAt` | 文字列    | HubSpotではデフォルトで、イベント完了タイムスタンプをリクエストが送信された時間に設定します。イベントの完了時刻を指定するには、`POST`リクエスト本文の`occurredAt`フィールドにタイムスタンプを含めます（[ISO 8601形式](https://ja.wikipedia.org/wiki/ISO_8601)）。これは、現実のイベントの完了を正確に反映するために、イベントデータの日付をさかのぼって設定する場合に特に役立ちます。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `properties` | オブジェクト | データの送信先となるイベントプロパティー。これには、[HubSpotのデフォルトのイベントプロパティー](/api-reference/events-manage-event-definitions-v3/guide#hubspot-s-default-event-properties)や、イベントに定義した任意の[カスタムプロパティー](/api-reference/events-manage-event-definitions-v3/guide#define-new-properties)を含めることができます。デフォルトのイベントプロパティーのほとんどは文字列プロパティーですが、[イベント定義をクエリー](/api-reference/events-manage-event-definitions-v3/guide#get-existing-event-definitions)するか、HubSpotのイベントにナビゲートすることで、全てのイベントプロパティーを確認できます。カスタム一致IDが[イベントに設定](/api-reference/events-manage-event-definitions-v3/guide#create-an-event-definition)されている場合は、`objectId`を省略できます。HubSpotでは、設定されたマッピングに基づいてイベントの`objectId`を設定することにより、イベントとCRMオブジェクトのリンクを試みます。[イベントプロパティー](#event-properties)の詳細については後述します。 |

<Warning>
  ### 注：

  次のいずれかの制限を超えると、リクエストは失敗します。

  * プロパティーラベルと内部名は50文字に制限されています。
  * URLとリファラーのプロパティーは最大1,024文字まで、その他のプロパティーは最大256文字までです。
  * 各イベント完了には、最大で50個のプロパティーのデータを含めることができます。
  * プロパティーの内部名はアルファベットで始まる必要があり、使用できるのは小文字のa～z、数字の0～9、アンダースコアのみです。
  * 小文字にした後の内部名が同じプロパティーは重複していると見なされ、完了時にはどちらか一方のプロパティーのみが使用されます。HubSpotでは、辞書の順序の昇順で並べ替え、最初の50個のプロパティーのうち、最後に表示されたプロパティーを保持します。
  * アカウントごとの一意のイベント定義数の上限は500です。
  * 1か月あたりのイベント完了数の上限は3,000万です。
</Warning>

## イベントデータを取得する

[イベントデータを取得](/api-reference/events-manage-event-definitions-v3/guide#get-%2Fevents%2Fv3%2Fevents%2F)するには、`GET`リクエストを`/events/v3/events`に送信します。

* 特定のイベントの全てのイベント完了を返すには、`eventType`パラメーターと内部イベント名（例：`pe123456_custom_event`）を含めます。[イベントアナリティクスAPI](/api-reference/events-manage-event-definitions-v3/guide#get-%2Fevents%2Fv3%2Fevents%2Fevent-types)を使用して、全てのイベントタイプを取得できます。
* 特定のオブジェクトのイベント完了を返すには、`objectId`パラメーターまたは`objectProperty.<property>`パラメーターと一緒に`objectType`パラメーターを含めます。`objectType`ではCRMオブジェクトのタイプ（`contact`など）を指定し、その他のパラメーターではオブジェクトの固有のID値（レコードIDまたは固有のIDプロパティー値）を指定します。コンタクトの場合は`email`を固有IDプロパティーとして使用できます。

例えば、特定のコンタクトによって完了した全てのイベントを取得する場合、リクエストURLは以下のようになります。

`/events/v3/events?objectType=contact&objectId=111111`

また、コンタクトのEメールアドレスを使用することもできます。

`/events/v3/events?objectType=contacts&objectProperty.email=bilbo@shire.com`

特定のイベントプロパティー値を持つイベント完了で結果を絞り込むには、`property.<propertyName>`パラメーターを含めます。例えば、ホームページのページ訪問イベントを取得する場合、リクエストURLは以下のようになります。

`/events/v3/events?eventType=e_visited_page&property.hs_page_title=home`

<Info>
  プロパティー値にスペースが含まれる場合は、スペースを`%20`または`+`に置き換えます。
  例えば、`property.hs_page_title=home+page`のようにします。
</Info>

使用可能なパラメーターの詳細については、[リファレンスドキュメント](/api-reference/events-manage-event-definitions-v3/guide#get-%2Fevents%2Fv3%2Fevents%2F)をご参照ください。

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

イベント完了データはイベントプロパティーに格納されます（[デフォルトのイベントプロパティー](/api-reference/events-manage-event-definitions-v3/guide#hubspot-s-default-event-properties)または[カスタム定義プロパティー](/api-reference/events-manage-event-definitions-v3/guide#define-new-properties)のいずれか）。イベントデータを送信するときは、更新するプロパティーのキーと値のペアを持つ`properties`オブジェクトと、保存するプロパティー値を含めます。

```json theme={null}
"properties": {
    "property1": "string",
    "property2": "string",
    "property3": "string"
  }
```

送信する値は、イベントプロパティーのタイプによって異なります。デフォルトのイベントプロパティーのほとんどは、単行テキスト（文字列）です。ただし、イベントごとに任意のタイプのカスタムプロパティーを作成できます。プロパティー値の書式を設定するときは、以下の表を確認してください。

| プロパティータイプ     | 説明                                                                                                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bool`        | `true`または`false`のブール値。                                                                                                                                                       |
| `enumeration` | 一連のオプションを表す文字列。複数の値を送信する場合は、値をセミコロンで区切ります。このタイプは、HubSpotでのドロップダウン選択、ラジオ選択、および複数チェックボックスのプロパティーに対応しています。                                                                      |
| `date`        | 特定の年月日を表す値。値はUTC時間で表す必要があります。値の形式として、[ISO 8601文字列](/api-reference/crm-properties-v3/guide#add-values-to-date-and-datetime-properties)またはミリ秒単位のエポック時間タイムスタンプ（UTC深夜0時）を使用できます。 |
| `datetime`    | 特定の年月日と時刻を表すタイムスタンプ。値はUTC時間で表す必要があります。値の形式として、[ISO 8601文字列またはミリ秒単位のUNIXタイムスタンプ](/api-reference/crm-properties-v3/guide#add-values-to-date-and-datetime-properties)を使用できます。   |
| `number`      | 小数第1位までの数値。このタイプは、HubSpotでの数値および計算プロパティーに対応しています。                                                                                                                            |
| `string`      | プレーンテキスト文字列。65,536文字までに制限されています。このタイプは、HubSpotでの単行および複数行のテキストプロパティーに対応しています。                                                                                                 |

イベントの利用可能なプロパティーを表示するには、次の操作を行います。

* HubSpotアカウントで、［データ管理］＞［カスタムイベント］に移動します。
* テーブル内でCTAの**名前**をクリックします。
* 上部にある［プロパティー］タブをクリックします。
* プロパティーテーブルで、プロパティーの名前の下に表示されているプロパティーのタイプを確認します。

<Frame>
  <img src="https://www.hubspot.jp/hubfs/Knowledge_Base_2021/Developer/custom-event-properties-table.png" alt="カスタムイベントプロパティーのテーブル" />
</Frame>

## アトリビューションレポート

[クリックされた要素](https://knowledge.hubspot.com/ja/analytics-tools/create-codeless-custom-behavioral-events)イベントや[訪問されたURL](https://knowledge.hubspot.com/ja/analytics-tools/create-codeless-custom-behavioral-events)イベントなどのJavaScriptイベントには、アトリビューションレポート用にアセットタイプとインタラクションデータが自動的に取り込まれます。手動でトラッキングされるイベントに同じデータを含めるには、イベントプロパティーを使用して、リクエスト本文に手動でデータを含める必要があります。詳しくは[カスタムイベントの分析](https://knowledge.hubspot.com/ja/analytics-tools/analyze-custom-behavioral-events)をご参照ください。

以下に、アセットタイプとインタラクションソースとして有効な値の説明とリクエストの例を記載します。

### アセットタイプ

特定のアセットタイプをカスタム行動イベントのリクエストに結び付けるには、リクエスト本文に`hs_page_content_type`プロパティーを含めます。以下に例を示します。

```json theme={null}
{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}
```

<Info>
  `hs_asset_type`プロパティーを使用することもできます。`hs_page_content_type`と`hs_asset_type`の両方が1つのリクエストに含まれている場合、`hs_page_content_type`が`hs_asset_type`の値よりも優先されます。
</Info>

ランディングページやブログ記事などのHubSpotの標準コンテンツタイプは、次の値で表すことができます。

| 値                   | 説明                   |
| ------------------- | -------------------- |
| `STANDARD_PAGE`     | ウェブサイトページでのインタラクション。 |
| `LANDING_PAGE`      | ランディングページでのインタラクション。 |
| `BLOG_POST`         | ブログ記事でのインタラクション。     |
| `KNOWLEDGE_ARTICLE` | ナレッジベース記事でのインタラクション。 |

その他全てのタイプのアセットには、次の値を使用します。

| 値                              | 説明                                                                           |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `AD`                           | Facebook広告やGoogle 広告などの広告でのインタラクション。                                         |
| `CALL`                         | コールでのインタラクション。                                                               |
| `CONTACT_IMPORT`               | コンタクトインポートを介したインタラクション。                                                      |
| `CONVERSATION`                 | HubSpotコミュニケーションに関連するインタラクション。                                               |
| `CUSTOM_BEHAVIORAL_EVENT_NAME` | カスタムイベントの内部名（例：`pe123456_manually_tracked_event`）。                           |
| `EMAIL`                        | Eメールでのインタラクション。                                                              |
| `EXTERNAL_PAGE`                | 外部ページでのインタラクション。                                                             |
| `INTEGRATIONS`                 | 連携を介したインタラクション。                                                              |
| `MARKETING_EVENT`              | [マーケティングイベント](/api-reference/marketing-marketing-events-v3/guide)でのインタラクション。 |
| `MEDIA_BRIDGE`                 | [メディアブリッジ](/api-reference/cms-media-bridge-v1/guide)を介したインタラクション。            |
| `MEETING`                      | ミーティングでのインタラクション。                                                            |
| `SALES_EMAIL`                  | 1対1のセールスEメールでのインタラクション。                                                      |
| `SEQUENCE`                     | シーケンスでのインタラクション。                                                             |
| `SOCIAL_POST`                  | ソーシャルメディア投稿でのインタラクション。                                                       |
| `OTHER`                        | 上記のいずれのカテゴリーにも該当しないアセットでのインタラクション。                                           |

### アセットタイトル

カスタムイベントをアセットに結び付けるには、リクエストに`hs_page_title`または`hs_asset_title`プロパティーを追加し、アセットの名前を文字列の形式で指定します。以下に例を示します。

`hs_page_title:`

```json theme={null}
{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}
```

### インタラクションソース

カスタム行動イベントを特定のソースに結び付けるには、リクエストに`hs_touchpoint_source`プロパティーを追加し、次のいずれかの値を設定します。

| 値                 | 説明                                                                                       |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `CONVERSATION`    | インタラクションソースがコミュニケーションであることを示します。                                                         |
| `DIRECT_TRAFFIC`  | インタラクションソースが直接トラフィックであることを示します。                                                          |
| `EMAIL_MARKETING` | インタラクションソースがマーケティングEメールであることを示します。                                                       |
| `HUBSPOT_CRM`     | インタラクションソースがHubSpotのCRMであることを示します。                                                       |
| `INTEGRATION`     | インタラクションソースが連携であることを示します。                                                                |
| `MARKETING_EVENT` | インタラクションソースが[マーケティングイベント](/api-reference/marketing-marketing-events-v3/guide)であることを示します。 |
| `OFFLINE`         | インタラクションソースがオフラインであることを示します。                                                             |
| `ORGANIC_SEARCH`  | インタラクションソースがオーガニック検索であることを示します。                                                          |
| `OTHER_CAMPAIGNS` | インタラクションソースが未分類のキャンペーンからのものであることを示します。                                                   |
| `PAID_SEARCH`     | インタラクションソースが有料検索広告であることを示します。                                                            |
| `PAID_SOCIAL`     | インタラクションソースが有料ソーシャル広告であることを示します。                                                         |
| `REFERRALS`       | インタラクションソースがリファーラルであることを示します。                                                            |
| `SALES`           | インタラクションソースが営業であることを示します。                                                                |
| `SOCIAL_MEDIA`    | インタラクションソースが（有料ソーシャル広告ではない）ソーシャルメディアであることを示します。                                          |