イベントオカレンスを送信する（ベータ版）

イベントタイプスキーマを定義し、そのfullyQualifiedNameを取得したら、アプリイベントAPIを使用してイベントオカレンスデータを送信できます。イベントデータを送信する際には、事前に作成したスキーマに従う必要があります。スキーマに一致しないリクエストは検証に失敗し、アプリはこのリクエストをキャプチャーしません。

イベントオカレンスの送信

1件のオカレンスを送信する
複数のオカレンスを一括送信する

1件のイベントオカレンスを送信するには、/integrators/timeline/v4/eventsに対するPOSTリクエストを送信します。リクエスト本文で、イベントタイプの定義済みスキーマの後にイベントデータを含め、eventTypeNameフィールドにfullyQualifiedName値を指定します。

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

複数のイベントオカレンスを一括送信するには、/integrators/timeline/v4/events/batchに対するPOSTリクエストを送信します。リクエスト本文のinputs配列に、カンマ区切りのイベントオカレンスオブジェクトを最大500個まで含めます。検証に失敗したオカレンスがある場合でも、正常に検証されたオカレンスは引き続き受け入れられ、保持されます。

{
  "inputs": [
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_100",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "mobileApp"
      },
      "extraData": {
        "surveyData": [
          {
            "question": "How was your login experience?",
            "answer": "Fine!"
          },
          {
            "question": "How likely are you to recommend logging in to a co-worker?",
            "answer": "Extremely likely"
          }
        ]
      }
    },
    {
      "EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_101",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "website"
      },
      "extraData": {}
    }
  ]
}

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

フィールド	型	説明
`eventTypeName`*	文字列	イベントタイプの完全修飾名。APIを使用してイベントを識別するときに使用します。この値はHubSpotによって自動設定され、イベントタイプの作成後に、APIを使用して取得できます。この値を作成後に変更することはできません。
`objectId`*	文字列	イベントオカレンスに関連付けるCRMレコードのID。このフィールドはあらゆるタイプのCRMレコードに使用でき、識別子として推奨されます。CRMレコードの関連付けについて詳細をご確認ください。
`email`	文字列	コンタクトの関連付けの場合、関連付けるコンタクトのEメールアドレスを指定できます。CRMレコードの関連付けについて詳細をご確認ください。
`utk`	文字列	コンタクトの関連付けの場合、関連付ける既存のコンタクトのユーザートークンを指定できます。CRMレコードの関連付けについて詳細をご確認ください。
`domain`	文字列	会社の`domain`プロパティー値を設定するときに、`objectId`に加えてこのフィールドを含めます。CRMレコードの関連付けについて詳細をご確認ください。
`timestamp`	文字列	イベントオカレンスの時刻（ISO 8601形式）を設定します。指定しない場合、既定でイベントオカレンスデータの送信時刻のタイムスタンプに設定されます。
`properties`	オブジェクト	イベントタイプに設定したプロパティーのプロパティー名と値のキーと値のペア。イベントプロパティーの詳細をご確認ください。
`extraData`	オブジェクト	タイムライン表示テンプレートで使用できる追加情報。有効なJSON形式である必要があります。
`timelineIFrame`	オブジェクト	このフィールドが含まれている場合、ユーザーがリンク先のコンテンツをiframeで表示できるハイパーリンクがタイムラインカードに組み込まれます。iframeの使用についての詳細をご確認ください。
`id`	文字列	イベントオカレンスの固有ID。イベントタイプ内で重複しないようにする必要があります。指定しない場合、HubSpotによりランダムなUUIDが生成されます。複数のイベントのIDが同一である場合、最初のイベントのIDが受け入れられ、その他は全て拒否されます。

CRMレコードの関連付け

各イベントオカレンスは、イベントタイプスキーマで定義されたCRMオブジェクトタイプを持つCRMレコードに関連付けられている必要があります。アプリイベントAPIには、イベントオカレンスデータをCRMレコードに関連付けるための複数のフィールドがあります。サポートされている全てのCRMオブジェクトでは、objectIdフィールドを使用することをお勧めします。ただし、場合によっては他のフィールドを使用することがあります。

utk/email：コンタクトのIDが不明な場合は、識別にutkフィールドとemailフィールドのいずれかまたは両方を使用します。両方の識別子を指定すると、コンタクトを作成および更新することもできます。以下に例を示します。
- utkが既存のコンタクトに一致してもemailが一致しない場合、HubSpotは新しいEメールアドレスで（utkに一致する）コンタクトを更新します。
- objectIdが指定されていない場合、イベントオカレンスはutk/emailに一致する既存のコンタクトに関連付けられ、一致するコンタクトが見つからない場合はHubSpotによって新しいコンタクトが作成されます。
- utkのみでは新しいコンタクトレコードを作成できないことにご注意ください。適切な関連付けを確保するために、常にutkとemailを含める必要があります。
domain：会社の関連付けの場合、objectIdを指定する必要があります。また、会社のdomainプロパティーを更新するためにdomainを含めることもできます。

以下に、CRMレコードの関連付けプロパティーの優先順位を示します。最も小さい数値が最も高い優先順位となります。

フィールド	優先順位	説明
`objectId`	1	CRMレコードID（推奨）。
`utk`	2	コンタクトのユーザートークン（コンタクトのみ）。
`email`	3	コンタクトのEメールアドレス（コンタクトのみ）。
`domain`	4	会社ドメイン（会社のみ）。

追加データの送信

イベントプロパティーへのデータの送信とイベントオカレンスによるCRMプロパティーの更新の他に、extraDataオブジェクトを使用してタイムライン表示のための追加データを含めることができます。

extraDataオブジェクトには有効なJSONのみを含めることができます。JSONの形式が正しくない場合、オカレンスは却下され、エラーレスポンスが返されます。

イベントタイプのdetailTemplateでは、{{extraData.fieldName}}構文を使用してextraDataフィールドの値にアクセスできます。extraDataの全ての属性レベルは、{{extraData.person1.preferredName}}などのドット表記形式で指定できます。例えば以下のテンプレートでは、customerNameプロパティーとloginLocationプロパティーのデータと、イベントオカレンスにより送信されたextraDataのsurveyDataフィールドが使用されています。コンタクトタイムラインに表示テンプレートの例がどのように表示されるかを示すスクリーンショット。

コンタクトタイムラインに表示テンプレートの例がどのように表示されるかを示すスクリーンショット。

イベントオカレンスデータ
タイムラインテンプレートの設定

{
  "eventTemplateId": "5488733",
  "objectId": "769851",
  "tokens": {
    "customerName": "Tim",
    "loginLocation": "mobileApp"
  },
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}

"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",

アプリを作成

機能を追加

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

イベントオカレンスを送信する（ベータ版）

イベントオカレンスの送信

CRMレコードの関連付け

追加データの送信

​イベントオカレンスの送信

​CRMレコードの関連付け

​追加データの送信

イベントオカレンスの送信

CRMレコードの関連付け

追加データの送信