トラッキングコードAPIの概要｜HubSpot（ハブスポット）

このページは、新しいカスタム行動イベントの使い方を紹介するために更新されました。従来のカスタムイベントについては、レガシードキュメント（英語）をご参照ください。

HubSpotトラッキングコードを使用すると、ページビューのトラッキングに加えて、訪問者の特定やイベントのトラッキングが可能になります。また、ページを再読み込みすることなくページビューを手動で追跡することも可能になります。トラッキングコードAPIを使用すると、HubSpotでイベントを動的に作成したり、イベントデータを追跡したりできるようになります。

ウェブサイトにプライバシーに関する同意バナーを設置している場合は、CookieバナーAPIによって訪問者のブラウザーに追加されるCookieを管理する方法をご確認ください。

関数呼び出しは_hsq配列に含めます。例として、以下のような場合が挙げられます。

var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', { path string }])

この記事では、トラッキングコードに関数を追加して、訪問者を識別したり、ページビューを追跡したり、イベントデータを送信したりする方法を説明します。

コンタクトを識別する

HubSpotアナリティクスツールでは、次の2組のデータを使用してコンタクトを識別します。

  • usertoken（訪問者の「hubspotutk」ブラウザーCookieに格納されます）
  • コンタクトのEメールアドレス

HubSpotトラッキングコードにより訪問者のアクション（ページビューなど）が追跡される際、そのアクションは訪問者のusertokenに自動的に関連付けられます。トラッキングコードAPIを使用してEメールアドレスで訪問者を特定する場合、アナリティクスシステムによってEメールアドレスがusertokenと結び付けられることで、既存のコンタクトレコードの更新や新規作成を行える仕組みです。usertokenに関連付けられているアナリティクスデータ（ページビューやオリジナルソースなど）が、コンタクトレコードに表示されます。

訪問者のID（Eメールアドレスなど）が判明している場合は、identify関数を使用してトラッカー内にIDを設定できます。次に、個別のtrackPageViewまたはtrackCustomBehavioralEvent呼び出しを行って、IDをHubSpotに送信できます。

この関数を使用する場合は、次の点に留意してください。

  • 不明な訪問者用のプレースホルダーEメールアドレスを使用することは避けてください。HubSpotによってプレースホルダーEメールアドレスを持つコンタクトレコードが作成され、訪問者のusertoken Cookieがそのレコードに関連付けられるからです。その結果、全ての不明な訪問者がプレースホルダーコンタクトに関連付けられます。
  • コンタクトレコードにIDを設定し、固有のプロパティーがある場合、一意性に違反するプロパティーは全てIDから削除されます。

訪問者を識別する

注：アカウントが2021年9月8日より前に作成され、トラッキングコードでのコンタクトプロパティーの更新が可能な場合は、他のコンタクトプロパティーもこの関数による更新の対象に含めることができます。2021年9月8日以降に作成されたアカウントの場合、この機能は非推奨になります。

_hsq.push(["identify", { {identity details} }]);

このエンドポイントは、ウェブサイトの訪問者やコンタクトを特定するために使用します。

  • 訪問者：HubSpotコンタクトであるかどうかにかかわらず、全てのウェブサイト訪問者を指します。HubSpotでは、コンタクトの場合と同様に訪問者に関するレコードは作成されません。
  • コンタクト：HubSpot内にレコードが存在する訪問者またはオフラインコンタクトを指します。コンタクトは、一意のEメールアドレスで識別することができます。

訪問者またはコンタクトを手動で識別するには、Eメールアドレスと一意の外部IDのいずれかを使用することができます。

  • Eメール：既存のコンタクトを更新したり、新しいコンタクトを作成したりする場合に、Eメールアドレスで訪問者を識別します。そのEメールアドレスを持つコンタクトがHubSpot内に存在する場合は、そのコンタクトレコードがアナリティクスデータで更新されます。そのEメールアドレスを持つコンタクトが存在しない場合は、新しいレコードが作成されます。
  • ID：訪問者を識別するためのカスタム外部ID。このIDで訪問者を識別すると、その訪問者にアナリティクスデータが関連付けられます。ただし、IDを使用するだけでは、HubSpotでコンタクトは作成されません。アナリティクスデータは、以下の場合にのみ、この方法を通して既存のコンタクトに関連付けることができます。
    • 訪問者がIDとEメールの両方で識別されたことがある。
    • 訪問者がIDで識別されたことがあり、そのレコードにフォーム送信が関連付けられている。

注：この外部IDは、HubSpotトラッキングコードでのみ使用できます。他のHubSpotツールまたはAPIでのレコードの取得や更新には使用できません。訪問者のEメールアドレスが分かっている場合は、そのEメールアドレスを一意の識別子として使用することをお勧めします。同様に、IDで訪問者を識別するのは、Eメールアドレスが分かっていない場合に限られます。

訪問者のIDのみを使用してHubSpotにアナリティクスデータを送信した場合は、後でIDとEメールアドレスの両方を含めることで、そのIDからのデータをコンタクトに関連付けることができます。そうすれば、既存のコンタクトが更新されるか、コンタクトが存在しない場合は新規に作成されます。

/* The below example gets the value of a query string parameter '?email=' and uses that to identify the visitor */ function getParameterByName(name) { var match = RegExp('[?&]' + name + '=([^&]*)').exec(window.location.search); return match && decodeURIComponent(match[1].replace(/\+/g, ' ')); } var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: getParameterByName("email") }]); /* The below example sets the email, as well as a custom property favorite_color */ var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: getParameterByName("email"), favorite_color: 'orange' }]); /* The below example sets the email and a custom external ID for the visitor. This assumes that your site includes a variable named 'user' that includes that user's ID in an 'id' property, and their email in an 'email' property. */ var _hsq = window._hsq = window._hsq || []; _hsq.push(["identify",{ email: user.email, id: user.id }]);
この関数を使用する場合は、次の点に留意してください。
  • この関数呼び出しでは、データがトラッカーに保存されますが、この呼び出しによってデータがHubSpotに渡されるわけではありません。データは、ページビューまたはイベントの追跡時にのみ渡されます（trackPageView関数またはtrackEvent関数のいずれかを使用）。
  • コンタクトには、IDやEメールアドレスを1つしか関連付けることができません。1つのEメールに2つのIDを割り当てようとすると、最初のIDだけがEメールアドレスに関連付けられます。
  • データをコンタクトに結びつけるには、Eメールアドレスを含める必要があります。
  • アカウントが2021年9月8日より前に作成され、トラッキングコードでのコンタクトプロパティーの更新が可能な場合は、他のコンタクトプロパティーもこの関数による更新の対象に含めることができます。
  • この関数では、以前に削除されたコンタクトは復元できません。そのようなコンタクトは、HubSpot上で復元する必要があります。

単一ページアプリでトラッキングを行う

HubSpotトラッキングコードでは、コードの初回読み込み時にページビューが記録されます。しかし、トラッキングコードを再読み込みすることなく単一ページアプリのページビューを手動で追跡することもできます。現在のページを更新してトラッキングを行うには、setPath関数とtrackPageView関数を使用します。例として、以下のような場合が挙げられます。

<!-- Set up the path for the initial page view --> <script> var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/home']); </script> <!-- Load the HubSpot tracking code --> <!-- Start of HubSpot Embed Code --> <script type="text/javascript" id="hs-script-loader" async defer src="//js.hs-scripts.com/{hubId}.js"> </script> <!-- End of HubSpot Embed Code --> <!-- Tracking subsequent page views --> <script> var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/about-us']); _hsq.push(['trackPageView']); </script>

ページパスを設定する

hsq.push(['setPath', { path string }])

トラッカーに保存された現在のページのパスを更新します。単一ページアプリで、ページ読み込み時に現在のページを更新する場合は、この関数を使用してください。この関数を使用してパスを更新した後、trackPageView関数を呼び出して現在のページの表示を追跡する必要があります。

単一ページアプリでは、トラッキングコードの読み込み前にsetPath呼び出しを_hsqに含めて、最初のページビューにおいて追跡されるURLを設定する必要があります。例として、後述する「ページビューを追跡する」セクションを参照してください。

SetPathを呼び出すときは、現在のページのパスを指定します。指定したパスは、表示されている現在のドメインとの相対パスとして処理されます。パスの先頭は常にスラッシュでなければなりません。URLにパラメーターが含まれている場合、それらもパスに含める必要があります。例として、上記コードをご覧ください。

この関数を使用する場合は、次の点に留意してください。
  • setPath関数を使用してパスを設定すると、Refererヘッダーのデータが変更されます。したがって、setPathを1度呼び出した後は、トラッキングを行うビューごとにsetPathを使用してパスを更新する必要があります。
  • setPathを繰り返し呼び出すと、リファラーが上書きされます。これは、トラッキングリクエストがいつ送信されたかによって、コンタクトのオリジナルソースに影響することがあります。 
  • この関数で更新できるのは、URLのパス部分のみです。ドメインは、読み込み時のページのURLに基づいて自動的に設定されます。この関数を使用して設定するパスは常に、検出されたドメインに対する相対パスとして処理されます。
Example usage: // These examples assume that the domain of the site is // www.mydomain.com // Set the path to '/' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/ // Set the path to '/contact-us' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/contact-us']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/contact-us // Set the path to '/blog/post?utm_campaign=my-campaign' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/blog/post?utm_campaign=my-campaign']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/blog/post?utm_campaign=my-campaign // Set the path to '/#/about-us' and track the page var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/#/about-us']); _hsq.push(['trackPageView']); // This will result in a view being recorded for // http://www.mydomain.com/#/about-us

ページビューを追跡する

_hsq.push(['trackPageView']);

現在のページのページビューを追跡します。この関数はページでトラッキングコードが読み込まれたときに自動的に呼び出されます。単一ページアプリの場合、この関数を手動で呼び出して以降のビューを追跡することができます。

注：初回のページ読み込みの前または読み込み中にこの関数を手動で呼び出すと、トラッキング対象のビューが重複するおそれがあります。

この関数には引数を追加できません。追跡されるページタイトルが、document.titleの現在の値になります。

追跡されるURLは、次のいずれか1つに基づきます。

  • setPath関数を使用して設定したパス。単一ページアプリとして作成されたサイトの場合、トラッキング対象パスの設定方法としてこの関数が推奨されます。この関数に関する免責事項については、前述のsetPathセクションをご覧ください。
  • 「setPath」が一度も呼び出されていない場合、トラッキング対象URLは、訪問者のブラウザーからHubSpotのトラッキングサーバーに向けて行われたリクエスト内のReferer HTTPヘッダーになります（ブラウザーの履歴に変更を加えると、ヘッダーに使用される値が更新されます）。RefererヘッダーではURLフラグメント（URLの#より後の部分）はサポートされません。フラグメントはRefererヘッダーに含められないからです。
Example usage: // Track a new page using setPath: // Update the path stored in the tracker: var _hsq = window._hsq = window._hsq || []; _hsq.push(['setPath', '/#/new-page']); // Track the page view for the new page _hsq.push(['trackPageView']); // Track a new page by updating the browser state: // Update the browser state, showing "updated.html" in the browser address bar var stateObj = { foo: 'updated' }; history.pushState(stateObj, "updated page", "updated.html"); //Track the page view for the new page, '/updated.html' var _hsq = window._hsq = window._hsq || []; _hsq.push(['trackPageView']);

この関数を使用する場合は、次の点に留意してください。

  • トラッキングコードの読み込み時にこの関数が自動的に呼び出されることは回避できませんが、そのページについて記録されるURLを制御することは可能です。そのためには、トラッキングコードの読み込み前に、setPathの呼び出しを_hsqに含めます。
  • サイトが単一ページアプリの場合、ページに<link rel="canonical">タグを含めないでください。ブラウザーの履歴状態を更新するだけの場合、検出される全てのURLはlinkタグに設定されたcanonical URLによって変更されるため、ページ内で<link rel="canonical">タグを使用する場合、setPath関数を使用して新しいページのパスを更新する必要があります。

トラッキングのプライバシーポリシー

ウェブサイトにプライバシーに関する同意バナーを設置している場合、関数を使用して、訪問者のブラウザーに設定されているCookieの確認および管理ができます。詳しくはプライバシーに関する同意バナーCookieを管理する方法をご確認ください。

クロスドメインリンクのパラメーターを取得する

_hsq.push(['addIdentityListener', function(hstc, hssc, hsfp) {}]) 

HubSpotトラッキングコードは、ドメインの異なる複数のウェブサイトにわたって使用できます。この関数を使用することで、異なるドメイン全体で訪問者のトラッキングを可能にするリンクの作成に必要なクエリーパラメーターを取得できます。HubSpotトラッキングコードはこれらのクエリーパラメーターを使用して、追跡された1人の訪問者に異なるドメインの別個のCookieを結び付けることで、複数のドメイン間で訪問者を識別できます。クロスドメイン クエリー パラメーターは、トラッキングコードの読み込み後、ページに動的に追加されるリンク内でも使用できます。

クロスドメインリンクが必要になるのは、単一のHubSpotアカウント上で同様にトラッキング対象となっている別のドメイン（「domain-one.com」と「domain-two.com」など）にリンクする場合に限定されます。サブドメイン間（例：「www.domain-one.com」と「blog.domain-one.com」）の訪問を追跡する場合、クロスドメイン リンク パラメーターは不要です。 

// Get the cross-domain query parameters and store them in a string, //so that they can be appended to links as needed. _hsq.push(['addIdentityListener', function(hstc, hssc, hsfp) { // Add these query parameters to any links that point to a separate tracked domain crossDomainTrackingParams = '&__hstc=' + hstc + '&__hssc=' + hssc + '&__hsfp=' + hsfp; }]);

アナリティクス イベント ハンドラーを再適用する

_hsq.push(['refreshPageHandlers'])

この関数は、HubSpotアカウントのアナリティクス設定でアナリティクス イベント ハンドラーが設定されている場合に、再適用します。

要素クリックイベントが設定されている場合は、その再適用も含まれます。

 この関数を使用すると、コンテンツのセクションの更新やページ上でのモーダルウィンドウの表示など、ページ上のコンテンツが更新された時点で、クリックハンドラーを自動的に再適用できます。

注：この機能は、setPath関数の一部として自動的にトリガーされるため、この関数が必要なのは、トラッキング対象ページURLを更新することなく、コンテンツを更新する場合に限られます。

// Reapply event handlers after updating the page content _hsq.push(['refreshPageHandlers']);

カスタム行動イベントのトラッキング（Marketing Hub Enterpriseのみ）

カスタム行動イベントを使用すると、イベントの完了をコンタクトレコードに結び付けて、イベントに関するメタデータをイベントプロパティーに入力することができます。カスタム行動イベントを取得するには、ウェブアナリティクスAPIを使用します。

このAPIにより、イベントの内部名を使用してイベントをトリガーできます。内部名は、イベントを作成したときに自動的に割り当てられます。イベントの内部名はHubSpot上で、またはイベントAPIを使用（英語）して、確認できます。詳しくはイベントの内部名を調べる方法をご確認ください。 

カスタムイベント内部名

HubSpot上で作成できるイベントには、次の3つのタイプがあります。

  • 要素クリックイベント：ウェブサイトページ上のクリック可能な要素に結び付けられたイベント。トラッキングコードを介して、既定の一連のHubSpotイベントプロパティーが自動入力されます。このタイプのイベントは、trackCustomBehavioralEvent関数で詳細をさらにカスタマイズできます。
  • URL訪問イベント：指定されたURLのページ読み込みに結び付けられたイベント。トラッキングコードを介して、既定の一連のHubSpotイベントプロパティーが自動入力されます。このタイプのイベントは、trackCustomBehavioralEvent関数で詳細をさらにカスタマイズできます。
  • 手動で追跡される行動イベント：貴社に固有のカスタムイベントと、HubSpotまたは連携によって自動的に取り込まれないイベント。HTTP APIを介して、手動でHubSpotイベントにデータを送信します。

HubSpotの各イベントタイプには、UTMパラメーターや、デバイスとオペレーティングシステムのメタデータを含む特定のメタデータを完了時に取り込むことが可能な、標準プロパティーのセットが用意されています。

 この関数はHubSpotのアナリティクストラッキングと連動しているため、JavaScript APIによってトリガーされたイベントが訪問者の「hubspotutk」Cookieに自動的に関連付けられます。これにより、イベントをユーザートークンに関連付けられたコンタクトへと自動的に結び付けることができます。

trackCustomBehavioralEvent

_hsq.push(["trackCustomBehavioralEvent", { {event details} }]);

JavaScriptおよびHubSpotのトラッキングコードを使用してイベントを追跡するには、この関数を使用します。イベントを使用して、ウェブサイトの訪問者が完了した特定のアクティビティーを追跡することができます。トラッキング対象のイベントは、コンタクトのタイムラインに表示されることがあります。

/* Example code to fire a custom behavioral event using the name "clicked Buy Now button" when a visitor clicks an element with the 'buyNow' id. */ document.getElementById("buyNow").onclick = function() {_hsq.push(["trackCustomBehavioralEvent", { name: "pe123456_course_registration", properties: { course_id: "Math101" } }]);
Use this table to describe parameters / fields
引数使い方説明
Name
name:"internal_name"

HubSpotで作成したイベントのevent_idまたは内部名。

Properties
property_name: "property_value"

キーと値のペアのリスト。プロパティーごとにキーと値のペアがあります。

property_nameはイベントについて作成したイベントプロパティーの内部名で、property_valueはプロパティーに追加する値です。 

また、未定義のプロパティーを追跡し、イベントの追跡後にこうしたプロパティーの作成に戻ることもできます。

カスタム行動イベントデータが送信されるようにトラッキングコードをカスタマイズする

既定では、作成するイベントごとに、HubSpotによって一連のプロパティーが作成されます。要素クリックイベントまたはURL訪問イベントの場合、HubSpotによってこうしたプロパティーの一部にデータが自動入力されます。しかし、イベントのプロパティーにデータが送信されるようにトラッキングコードをカスタマイズすることもできます。

  • HubSpotアカウントにて、［レポート］>［アナリティクスツール］の順に進みます。
  • ［カスタム行動イベント］をクリックします。
  • 追跡するイベントの名前をクリックします。
  • ［プロパティー］のイベントの内部名をコピーします。カスタム要素クリックイベント-内部名0
  • 次に、プロパティーの表で、データの送信先となるイベントプロパティーの名前をクリックします。
  • 右側のパネルで</>ソースアイコンをクリックして、プロパティーの内部名を表示します。この名前は、トラッキングコードをカスタマイズする際に使用します。
    カスタム行動イベントプロパティー-内部名0
  • イベントとイベント プロパティー データが用意できたら、設定アイコンをクリックしてアカウント設定に進みます。次に、左のサイドバーメニューで、［トラッキングとアナリティクス］>［トラッキングコード］の順に進みます。
  • ［JavaScriptのカスタマイズ］をクリックします。
    トラッキングコード-JavaScriptのカスタマイズ0
  • 右上の［カスタムJavaScriptを追加］をクリックします。
  • 右側のサイドバーでカスタムJavaScriptの名前を入力し、次にtrackCustomBehavioralEvent関数が含まれるJavaScriptを入力します。このJavaScriptは、ページのトラッキングコードの読み込み後に実行されます。
// example usage _hsq.push(['trackCustomBehavioralEvent',{ name: '((behavioral_event_internal_name))”, properties: { internal_property_name: property_value} } ]);

例えば、HTML ID「register_for_econ101」のボタンがクリックされたときに、イベントによってコースの登録を追跡する場合、次のようなJavaScriptを記述します。トラッキングコードのカスタマイズ0-1

  • ［保存］をクリックして、JavaScriptを保存します。これで、トラッキングコードの読み込みがカスタムJavaScriptと共に行われるようになりました。
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。