CRMカード
カスタムCRMカードは、他のシステムからの情報をHubSpotのコンタクト、会社、取引、またはチケットレコードに表示できる仕組みです。この機能を使用すると、他のシステムからのデータを表示するカスタムカードをアプリ上に作成できます。HubSpot上にデータを格納にする際に、ニーズを満たせるネイティブオブジェクトがない場合は、カスタムオブジェクトによってニーズを満たせるかどうかを検討してみてください。
使用例:エンジニアリングチームはあるソフトウェアサービスを使用して不具合を追跡していますが、カスタマーサービス担当者はHubSpotを使用しています。カスタマーサービス担当者はHubSpotを離れることなく、顧客からの不具合情報を確認したいと考えています。この情報は、貴社のアプリにカスタムカードを定義することで、HubSpotコンタクトレコード上に表示できます。
仕組み
カードはアプリの機能設定の一部として定義できます。アプリをインストールしたユーザーがターゲットのCRMレコードを表示すると、HubSpotはアプリにリクエストを送信して関連するデータを取得し、レコードページ上のカード内にそのデータを表示します。アプリには、この情報に基づいてユーザーが実行できるカスタムアクションを指定することもできます。カスタムアクションの一例として、アプリ独自のユーザーインターフェイス(UI)をモーダルとしてHubSpot上に表示するアクションが考えられます。
CRMカードの例を以下に示します。
また、CRM上にカードのプロパティーを表示する場合のデータフローの例を以下に示します。
CRMカードを設定する
CRMカードの作成と設定には開発者アカウントを使用します。カード内の項目は、カードプロパティーとして表されます。このプロパティーのタイトルを(必要に応じて)インテグレーターの外部システムに合わせておくことができます。カード内の「Powered by」の行では、貴社のアプリ設定のアプリ名が使用されることに留意してください。
アプリダッシュボードで、カードを追加するアプリを選択し、CRMカードに進みます。[CRMカードを作成]ボタンをクリックして作成を開始します。
スコープの要件
カスタムCRMカードを作成するアプリは、カードを表示するCRMレコードの変更に必要なOAuthスコープをリクエストする必要があります。つまり、コンタクト、会社、または取引のカードを設定するためのcontacts
スコープと、チケットのカードを設定するためのtickets
スコープをリクエストします。
スコープの詳細およびアプリの認証URLの設定については、OAuthのドキュメントを参照してください。
スコープを削除する
アプリですでにCRMカードを使用している場合、そのオブジェクトタイプに関連付けられている全ての既存カードを削除するまでは、contacts
スコープもtickets
スコープも削除できません。
新規カードを作成する
CRMカードを使用するための最初のステップは、カードテンプレートの作成です。ユーザーには、以下の内容が表示されます。
APIを使用してカードを設定する
APIを使用してカードを管理する方法は、このページの「エンドポイント」タブをご覧ください。
アプリ設定UIを使用してカードを設定する
開発者アカウントのアプリの機能設定からCRMカードを作成、管理*することもできます(前述の手順を参照)。
*1つのアプリにつき、最大25件のCRMカードを作成できます。
関連ドキュメント
データ フェッチ リクエスト
「概要」タブにある説明のように、アプリに関連付けられているCRMレコードをユーザーが表示するたびに、HubSpotからそのアプリにデータフェッチ(取得)リクエストが送信されます。これらのリクエストは、ペイロードとして該当するCRMレコードの詳細を付けて、カードに指定されているfetch/targetUrlに送信されます。
レスポンスには最大5つのカードプロパティーを含めることができます。特定のCRMオブジェクトにこれよりも多くのプロパティーがある場合は、アプリからそれらのプロパティーにリンクできます。
リクエストは5秒でタイムアウトすることに注意してください。そのため、3秒で接続を確立する必要があります。
データ フェッチ リクエストの例:
GET:https://example.com/demo-tickets?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com
ヘッダーの内容:
X-HubSpot-Signature: <some base64 string>
X-HubSpot-Signature
ヘッダーを使用して、リクエストがHubSpotから送信されていることを確認できます。詳細については、リクエストの署名を参照してください。
クエリーパラメーター:
userId
:データをリクエストしている顧客の数値形式のユーザーID。userEmail
:データをリクエストしているHubSpotユーザーのEメールアドレス。portalId
:データをリクエストしている顧客のHubSpotアカウントID。アカウントとポータルは同じ意味で使用されます。associatedObjectId
:現在のオブジェクトのID。associatedObjectType
によってIDのタイプは異なります。チケットの場合は、companyId
、dealId
、contact vID
、objectId
のいずれかです。associatedObjectType
:ユーザーがリクエストしているデータのオブジェクトタイプ(contact
、company
、deal
、またはticket
)。これは、このレコードタイプに指定されているassociatedHubSpotObjectTypes
のいずれかです。- また、リクエストされたいずれかの
associatedHubSpotObjectTypeProperties
の値です。リクエストされたプロパティーのいずれかが現在のオブジェクトで定義されていない場合、そのプロパティーはクエリー文字列に含められません。上記の例には、会社プロパティーとしてdomainが含まれています。下のスクリーンショットに示されているように、リクエストのプロパティーはアプリ設定UIで定義できます。
レスポンスの例:
定義:
results
:最大5個の有効なカードプロパティーのリスト。results[].objectId
:このオブジェクトの固有ID。このプロパティーは必須です。results[].title
:このオブジェクトのタイトル。このプロパティーは必須です。results[].link
:ユーザーがこのオブジェクトに関する詳細を取得するために使用できるURI。任意のプロパティーですが、どのオブジェクトにもリンクがない場合は、値としてnullを指定してください。results[].properties
:カード設定に定義されていないカスタムプロパティーのリスト。このリストを使用して、特定のオブジェクトに固有のプロパティーを表示することができます。これらのプロパティーは、カード設定で定義されたプロパティーの後に、提示した順に示されます。任意のプロパティーです。results[].actions
:このオブジェクトに対してユーザーが実行できるアクションのリスト。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。totalCount
:リクエストしたCRMオブジェクトに関連付けられているカードプロパティーの数が5個を超える場合に、使用可能なプロパティーの合計数。任意のプロパティーです。allItemsLink
:リクエストしたCRMオブジェクトに関連付けられているカードプロパティーの数が5個を超える場合に、その全てのプロパティーを示すURI。任意のプロパティーです。itemLabel
:「さらに表示」リンクなどで使用されるラベル(例:「チケットをさらに表示」)。任意のプロパティーです。指定がない場合、既定でカードのタイトルが使用されます。settingsAction
:ユーザーがアプリの設定を更新するために使用できるiframeアクション。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。primaryAction
:レコードタイプのプライマリーアクション(通常は「作成」アクション)。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。secondaryActions
:カードレベルに表示されるアクションのリスト。アクションの指定については、アクションタイプを参照してください。任意のプロパティーです。
上記のプロパティーに加えて、インテグレーターはカード設定で定義されているプロパティーの値を指定できます。上記の例のJSONプロパティーcreatedでは、
"created":"2016-08-04"
このオブジェクトにあらかじめ定義されているcreated
プロパティーの値が返されます。
アクションフックを処理する
アクションフックとして定義されているアクションをユーザーがクリックすると、HubSpotから、アクション定義に指定されているURIとHTTP
メソッドを使用してリクエストが送信されます。
リクエストの例:
DELETE https://example.com/tickets/245?userId=12345&userEmail=testuser@example.com&associatedObjectId=78912&associatedObjectType=COMPANY&portalId=9999999&domain=testcompany.com
ヘッダーの内容:
X-HubSpot-Signature: <some base64 string>
クエリーパラメーター:
userId
:データをリクエストしている顧客の数値形式のユーザーID。userEmail
:データをリクエストしている顧客のHubSpotユーザーEメールアドレス。associatedObjectId
:現在のオブジェクトのID。associatedObjectType
によってIDのタイプは異なります。チケットの場合は、companyId
、dealId
、contact vid
、objectId
のいずれかです。associatedObjectType
:ユーザーがリクエストしているデータのオブジェクトタイプ(contact
、company
、deal
、またはticket
)。portalId
:データをリクエストしている顧客のアカウントID(Hub IDとも呼ばれます)。- また、リクエストされたいずれかの
associatedObjectProperties
の値です。リクエストされたプロパティーのいずれかが現在のオブジェクトに定義されていない場合、そのプロパティーはクエリー文字列に含められません。上記の例には、会社プロパティーとしてdomainが含まれています。
インテグレーターはリクエストがHubSpotから送信されたことを確認するために、X-HubSpot-Signature
ヘッダーを使用できます。詳細については、リクエストの署名を参照してください。
レスポンスの例:
{"message":"Successfully deleted object"}
HubSpotは、アクションフックに対するレスポンスをJSONとして解析してメッセージプロパティーを検索しようと試みます。ユーザーには、成功または失敗のいずれかのメッセージが表示されます。
レスポンスのステータスコードが2XX
の場合は成功メッセージが表示され、4XX
または5XX
の場合はエラーメッセージが表示されます。
アクションタイプ
ここでは、指定できるアクションの各タイプについて説明します。
iframeアクション
ユーザーがiframeアクションをクリックすると、そのiframeで指定されているURLにあるモーダルダイアログが開きます。
iframeアクションの例:
定義:
type
:iframeアクションであることを示すIFRAMEを指定します。width, height
:目的のiframeサイズ。uri
:iframeで開くURI。label
:アクションドロップダウンに表示されるラベル。associatedObjectProperties
:関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。Iframeを開く際に、現在のオブジェクトのプロパティー値がクエリーパラメーターとしてURLに付加されます。
モーダルを閉じるための指示
ユーザーがiframeアクションを完了したら、モーダルダイアログを閉じて、ユーザーを元のCRM画面にリダイレクトする必要があります。ダイアログモデルを閉じるには、アプリでwindow.postMessageメッセージを使用できます。次のメッセージを使用できます。
{"action":"DONE"}
- ユーザーが正常にアクションを完了しました。{"action":"CANCEL"}
-ユーザーがアクションをキャンセルしました。
例:window.parent.postMessage(JSON.stringify({"action":"DONE"}), "*");
注:iframeアクションによってアクセスされたiframeモーダルは、レスポンシブな幅に設定されます。
アクションフックのアクション
アクションフックのアクションにより、サーバーサイドのリクエストがアプリに送信されます。このアクションでユーザーに表示されるUIは、成功メッセージまたはエラーメッセージのみです。このタイプのアクションは、ユーザー入力を必要としないシンプルな操作に役立ちます。
アクションフックのアクションの例:
定義:
type
:アクションフックのアクションであることを示すACTION_HOOK
を指定します。httpMethod
:リクエストに使用するHTTP
メソッド。GET
、POST
、PUT
、DELETE
、PATCH
のいずれかです。uri
:リクエストの送信先URI。label
:アクションドロップダウンに表示するラベル。associatedObjectProperties
:関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。httpMethod
がGET
またはDELETE
の場合、これらのプロパティー値がクエリーパラメーターとしてリクエストのURIに付加されます。それ以外の場合は、JSONリクエスト本文として送信されます。
アクションエンドポイントの実装方法については、アクションフックの処理を参照してください。
確認アクション
確認アクションは、アクションフックと同様に動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログが表示される点が異なります。
定義:
type
:アクションフックのアクションであることを示すACTION_HOOK
を指定します。httpMethod
:リクエストに使用するHTTP
メソッド。GET
、POST
、PUT
、DELETE
、PATCH
のいずれかです。uri
:リクエストの送信先URI。label
:アクションドロップダウンに表示するラベル。associatedObjectProperties
:関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。httpMethod
がGET
またはDELETE
の場合、これらのプロパティー値がクエリーパラメーターとしてリクエストのURIに付加されます。それ以外の場合は、JSONリクエスト本文として送信されます。
アクションエンドポイントの実装方法については、アクションフックの処理を参照してください。
確認アクション
確認アクションは、アクションフックと同様に動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログが表示される点が異なります。
定義:
type
:確認アクションのフックアクションであることを示すCONFIRMATION_ACTION_HOOK
を指定します。httpMethod
:リクエストに使用するHTTP
メソッド。GET
、POST
、PUT
、DELETE
、PATCH
のいずれかです。uri
:リクエストの送信先URI。label
:アクションドロップダウンに表示するラベル。associatedObjectProperties
:関連付けられているコンタクト、会社、取引、またはチケットのプロパティーのリスト。httpMethod
がGET
またはDELETE
の場合、これらのプロパティー値がクエリーパラメーターとしてリクエストのURIに付加されます。それ以外の場合は、JSONリクエスト本文として送信されます。confirmationMessage
:ユーザーへの確認ダイアログに表示するメッセージ。confirmButtonText
:OKボタンのテキスト。任意。既定では、ボタンのテキストは[OK]に設定されます。cancelButtonText
:キャンセルボタンのテキスト。任意。既定では、ボタンのテキストは[キャンセル]に設定されます。
アクションエンドポイントの実装方法については、アクションフックの処理を参照してください。
貴重なご意見をありがとうございました。