トラッキングコードAPIの概要

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

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がそのレコードに関連付けられるからです。その結果、全ての不明な訪問者がプレースホルダーコンタクトに関連付けられます。

訪問者を識別する

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

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

ウェブサイトの訪問者を識別するには、Eメールアドレスまたはカスタム外部IDを使用します。

  • EメールアドレスをIDとして使用し、そのEメールアドレスに対応するコンタクトレコードがある場合は、そのコンタクトが更新されます。ない場合は、新しいコンタクトレコードが作成されます。いずれの場合も、この訪問者について収集されるアナリティクスデータがコンタクトレコードに関連付けられます。
  • カスタム外部IDをIDとして使用した状態では、以前にIDとEメールアドレスの両方でレコードが識別された場合、または以前にIDでレコードが識別され訪問者によるHubSpotフォームの送信があった場合に限り、訪問者のアナリティクスデータがそのIDに関連付けられます。ただし、Eメールアドレスの場合とは異なり、IDを含めるだけではコンタクトは作成されません。

カスタム外部IDは、トラッキングコードAPIでのみ使用できます。他のHubSpotツールまたはAPIでのレコードの取得や更新には使用できません。

/* 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上で復元する必要があります。

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

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を設定する必要があります。

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
Use this table to describe parameters / fields
必須パラメーター構文説明
Path
'setPath', { path string }

現在のページのパス。指定したパスは、表示されている現在のドメインとの相対パスとして処理されます。パスの先頭は常にスラッシュでなければなりません。URLにパラメーターが含まれている場合、それらもパスに含める必要があります。詳しくは、サンプルを参照してください。
この関数を使用する場合は、次の点に留意してください。
  • setPath関数を使用してパスを設定するとRefererヘッダーのデータが変更されます。したがって、setPathを1度呼び出した後は、トラッキングを行うビューごとにsetPathを使用してパスを更新する必要があります。
  • setPathを繰り返し呼び出すと、リファラーが変更されます。これは、トラッキングリクエストがいつ送信されたかによって、コンタクトのオリジナルソースに影響することがあります。 
  • 単一ページアプリでは、トラッキングコードの読み込み前にsetPath呼び出しを_hsqに含めて、最初のページビューにおいて追跡されるURLを設定する必要があります。例については、トラッキングコードの概要を参照してください。
  • この関数で更新できるのは、URLのパス部分のみです。ドメインは、読み込み時のページのURLに基づいて自動的に設定されます。この関数を使用して設定するパスは常に、検出されたドメインに対する相対パスとして処理されます。

ページビューを追跡する

_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トラッキングコードはこれらのクエリーパラメーターを使用して、異なるドメインの別個のCookieを追跡された1人の訪問者にマージすることで、複数のドメイン間で特定の訪問者を識別します。クロスドメイン クエリー パラメーターは、トラッキングコードの読み込み後、ページに動的に追加されるリンク内でも使用できます。

クロスドメインリンクが必要になるのは、単一のHubSpotアカウント上で同様にトラッキング対象となっている別のドメイン（「domain-one.com」と「domain-two.com」など）にリンクする場合に限定されます。サブドメイン間（例：「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アカウントのアナリティクス設定にアナリティクス イベント ハンドラーがある場合に、再適用します。

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

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

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

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

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

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

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

custom-event-internal-name

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アカウントにて、［レポート］>［アナリティクスツール］の順に進みます。
  • ［カスタム行動イベント］をクリックします。
  • 追跡するイベントの名前をクリックします。
  • ［プロパティー］のイベントの内部名をコピーします。custom-clicked-element-event-internal-name0
  • 次に、プロパティーの表で、データの送信先となるイベントプロパティーの名前をクリックします。
  • 右側のパネルで</>ソースアイコンをクリックして、プロパティーの内部名を表示します。この名前は、トラッキングコードをカスタマイズする際に使用します。
    custom-behavioral-event-property-internal-name0
  • イベントとイベント プロパティー データが用意できたら、設定アイコンをクリックしてアカウント設定に進みます。次に、左のサイドバーメニューで、［トラッキングとアナリティクス］>［トラッキングコード］の順に進みます。
  • ［JavaScriptをカスタマイズ］をクリックします。
    tracking-code-customize-javascript0
  • 右上の［カスタム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を記述します。customize-tracking-code0-1

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