Application Insights JavaScript SDK 用のクリック分析自動収集プラグインClick Analytics Auto-collection plugin for Application Insights JavaScript SDK

このプラグインを使用すると、Web ページのクリック イベントが自動的に追跡され、HTML 要素の data-* 属性を使用してイベント テレメトリにデータが設定されます。This plugin automatically tracks click events on web pages and uses data-* attributes on HTML elements to populate event telemetry.

作業の開始Getting started

ユーザーは、npm を使用してクリック分析自動収集プラグインを設定できます。Users can set up the Click Analytics Auto-collection plugin via npm.

npm の設定npm setup

npm パッケージをインストールします。Install npm package:

npm install --save @microsoft/applicationinsights-clickanalytics-js @microsoft/applicationinsights-web

import { ApplicationInsights } from '@microsoft/applicationinsights-web';
import { ClickAnalyticsPlugin } from '@microsoft/applicationinsights-clickanalytics-js';

const clickPluginInstance = new ClickAnalyticsPlugin();
// Click Analytics configuration
const clickPluginConfig = {
  autoCapture: true
};
// Application Insights Configuration
const configObj = {
  instrumentationKey: "YOUR INSTRUMENTATION KEY",
  extensions: [clickPluginInstance],
  extensionConfig: {
    [clickPluginInstance.identifier]: clickPluginConfig
  },
};

const appInsights = new ApplicationInsights({ config: configObj });
appInsights.loadAppInsights();

このプラグインを効果的に使用する方法How to effectively use the plugin

  1. クリック イベントから生成されたテレメトリ データは、Azure portal の [Application Insights] セクションに customEvents として格納されます。Telemetry data generated from the click events are stored as customEvents in the Application Insights section of the Azure portal.

  2. customEvent の name は、次の規則に基づいて設定されます。The name of the customEvent is populated based on the following rules:

    1. data-*-id で指定された id は customEvent 名として使用されます。The id provided in the data-*-id will be used as the customEvent name. たとえば、クリックされた HTML 要素に属性 "data-sample-id"="button1" が含まれている場合は、"button1" が customEvent 名になります。For example, if the clicked HTML element has the attribute "data-sample-id"="button1", then "button1" will be the customEvent name.
    2. このような属性が存在せず、構成で useDefaultContentNameOrIdtrue に設定されている場合は、クリックされた要素の HTML 属性 id またはその要素のコンテンツ名が customEvent 名として使用されます。If no such attribute exists and if the useDefaultContentNameOrId is set to true in the configuration, then the clicked element's HTML attribute id or content name of the element will be used as the customEvent name.
    3. useDefaultContentNameOrId が false である場合、customEvent 名は "not_specified" になります。If useDefaultContentNameOrId is false, then the customEvent name will be "not_specified".

    ヒント

    意味のあるデータを生成するために、useDefaultContentNameOrId を true に設定することをお勧めします。Our recommendations is to set useDefaultContentNameOrId to true for generating meaningful data.

  3. parentDataTag は次の 2 つの処理を行います。parentDataTag does two things:

    1. このタグが存在する場合、このプラグインでは、クリックされた要素のすべての親 HTML 要素から data-* 属性と値をフェッチします。If this tag is present, the plugin will fetch the data-* attributes and values from all the parent HTML elements of the clicked element.
    2. 効率を向上させるために、このプラグインではこのタグをフラグとして使用し、これを検出すると、DOM (ドキュメント オブジェクト モデル) のそれ以上の上向きの処理を停止します。To improve efficiency, the plugin uses this tag as a flag, when encountered it will stop itself from further processing the DOM (Document Object Model) upwards.

    注意事項

    parentDataTag が使用されると、SDK により、使用した HTML 要素だけでなく、アプリケーション全体で親タグの検索が開始されます。Once parentDataTag is used, the SDK will begin looking for parent tags across your entire application and not just the HTML element where you used it.

  4. ユーザーによって指定される customDataPrefix は、常に data- (data-sample- など) で始まる必要があります。customDataPrefix provided by the user should always start with data-, for example data-sample-. HTML では、data-* グローバル属性によって、カスタム データ属性と呼ばれる属性のクラスが形成されます。これにより、HTML と、スクリプトによるその DOM 表現の間で機密情報を交換できるようになります。In HTML the data-* global attributes form a class of attributes called custom data attributes, that allow proprietary information to be exchanged between the HTML and its DOM representation by scripts. 以前のブラウザー (Internet Explorer、Safari) では、data- で始まっていない限り、認識できない属性を削除します。Older browsers (Internet Explorer, Safari) will drop attributes that it doesn't understand, unless they start with data-.

    data-** は、XML 名の生成規則に従った任意の名前で置き換えることができます。ただし、次の制限があります。The * in data-* may be replaced by any name following the production rule of XML names with the following restrictions:

    • この名前を "xml" で始めることはできません (大文字と小文字のどちらであっても)。The name must not start with "xml", whatever case is used for these letters.
    • この名前にセミコロン (U+003A) を含めることはできません。The name must not contain any semicolon (U+003A).
    • この名前に大文字を含めることはできません。The name must not contain capital letters.

構成Configuration

名前Name TypeType DefaultDefault 説明Description
autoCaptureautoCapture booleanboolean truetrue 自動キャプチャの構成。Automatic capture configuration.
コールバック (callback)callback IValueCallbackIValueCallback nullnull コールバックの構成。Callbacks configuration.
pageTagspageTags stringstring nullnull ページ タグ。Page tags.
dataTagsdataTags ICustomDataTagsICustomDataTags nullnull クリック データのキャプチャに使用される既定のタグをオーバーライドするために指定されるカスタム データ タグ。Custom Data Tags provided to override default tags used to capture click data.
urlCollectHashurlCollectHash booleanboolean falsefalse URL の "#" 文字の後の値のログ記録を有効にします。Enables the logging of values after a "#" character of the URL.
urlCollectQueryurlCollectQuery booleanboolean falsefalse URL のクエリ文字列のログ記録を有効にします。Enables the logging of the query string of the URL.
behaviorValidatorbehaviorValidator 機能Function nullnull data-*-bhvr 値の検証に使用するコールバック関数。Callback function to use for the data-*-bhvr value validation. 詳細については、behaviorValidator のセクションに移動してください。For more information, go to behaviorValidator section.
defaultRightClickBhvrdefaultRightClickBhvr 文字列 (または) 数値string (or) number '''' [右クリック] イベントが発生したときの [既定の動作] 値。Default Behavior value when Right Click event has occurred. この値は、要素に data-*-bhvr 属性が含まれている場合にオーバーライドされます。This value will be overridden if the element has the data-*-bhvr attribute.
dropInvalidEventsdropInvalidEvents booleanboolean falsefalse 有効なクリック データがないイベントを削除するためのフラグ。Flag to drop events that do not have useful click data.

IValueCallbackIValueCallback

名前Name TypeType DefaultDefault 説明Description
pageNamepageName 機能Function nullnull 既定の pageName キャプチャ動作をオーバーライドするための関数。Function to override the default pageName capturing behavior.
pageActionPageTagspageActionPageTags 機能Function nullnull pageAction イベント中に収集される既定の pageTags を拡張するためのコールバック関数。A callback function to augment the default pageTags collected during pageAction event.
contentNamecontentName 機能Function nullnull カスタマイズされた contentName を設定するためのコールバック関数。A callback function to populate customized contentName.

ICustomDataTagsICustomDataTags

名前Name TypeType DefaultDefault HTML で使用する既定のタグDefault Tag to Use in HTML 説明Description
useDefaultContentNameOrIduseDefaultContentNameOrId booleanboolean falsefalse 該当なしN/A 特定の要素が既定の customDataPrefix でタグ付けされていない場合、または customDataPrefix がユーザーによって指定されていない場合、contentName の標準の HTML 属性を収集します。Collects standard HTML attribute for contentName when a particular element is not tagged with default customDataPrefix or when customDataPrefix is not provided by user.
customDataPrefixcustomDataPrefix stringstring data- data-* 指定されたプレフィックスでタグ付けされている要素のコンテンツ名と値を自動キャプチャします。Automatic capture content name and value of elements that are tagged with provided prefix. たとえば、HTML タグ内で data-*-iddata-<yourcustomattribute> を使用できます。For example, data-*-id, data-<yourcustomattribute> can be used in the HTML tags.
aiBlobAttributeTagaiBlobAttributeTag stringstring ai-blob data-ai-blob プラグインでは、個々の data-* 属性ではなく JSON BLOB 属性がサポートされています。Plugin supports a JSON blob attribute instead of individual data-* attributes.
metaDataPrefixmetaDataPrefix stringstring nullnull N/AN/A キャプチャ時に指定されたプレフィックスを持つ HTML 見出しのメタ要素名とコンテンツを自動キャプチャします。Automatic capture HTML Head's meta element name and content with provided prefix when capture. たとえば、HTML メタ タグ内で custom- を使用できます。For example, custom- can be used in the HTML meta tag.
captureAllMetaDataContentcaptureAllMetaDataContent booleanboolean falsefalse 該当なしN/A すべての HTML 見出しのメタ要素名とコンテンツを自動キャプチャします。Automatic capture all HTML Head's meta element names and content. 既定値は false です。Default is false. 有効になっている場合は、指定された metaDataPrefix がオーバーライドされます。If enabled this will override provided metaDataPrefix.
parentDataTagparentDataTag stringstring nullnull N/AN/A このタグが検出されると、要素のコンテンツ名と値をキャプチャするための DOM の走査を停止します。Stops traversing up the DOM to capture content name and value of elements when encountered with this tag. たとえば、HTML タグ内で data-<yourparentDataTag> を使用できます。For example, data-<yourparentDataTag> can be used in the HTML tags.
dntDataTagdntDataTag stringstring ai-dnt data-ai-dnt この属性を含む HTML 要素は、テレメトリ データをキャプチャするためにこのプラグインによって無視されます。HTML elements with this attribute will be ignored by the plugin for capturing telemetry data.

behaviorValidatorbehaviorValidator

behaviorValidator 関数を使用すると、コード内のタグ付けされた動作が、事前に定義された一覧に準拠しているかどうかを自動的に確認できます。The behaviorValidator functions automatically checks that tagged behaviors in code conform to a pre-defined list. これにより、タグ付けされた動作を、企業が設定した分類と確実に一致させることができます。This ensures tagged behaviors are consistent with your enterprise's established taxonomy. Azure Monitor のほとんどの顧客がこれを使用することは求められておらず、それは予測されていませんが、これは高度なシナリオに使用できます。It is not required or expected that most Azure Monitor customers will use this, but it's available for advanced scenarios. この拡張機能の一部として公開されている behaviorValidator のコールバック関数には 3 種類あります。There are three different behaviorValidator callback functions exposed as part of this extension. ただし、公開されている関数によって要件が解決されない場合、ユーザーは独自のコールバック関数を使用できます。However, users can use their own callback functions if the exposed functions do not solve your requirement. その意図はユーザー独自の動作のデータ構造を定義することにあり、このプラグインでは、データ タグから動作を抽出するときにこの検証関数を使用します。The intent is to bring your own behaviors data structure, the plugin uses this validator function while extracting the behaviors from the data tags.

名前Name [説明]Description
BehaviorValueValidatorBehaviorValueValidator このコールバック関数は、動作のデータ構造が文字列の配列である場合に使用します。Use this callback function if your behaviors data structure is an array of strings.
BehaviorMapValidatorBehaviorMapValidator このコールバック関数は、動作のデータ構造がディクショナリである場合に使用します。Use this callback function if your behaviors data structure is a dictionary.
BehaviorEnumValidatorBehaviorEnumValidator このコールバック関数は、動作のデータ構造が列挙型である場合に使用します。Use this callback function if your behaviors data structure is an Enum.

behaviorValidator の使用例Sample usage with behaviorValidator

var clickPlugin = Microsoft.ApplicationInsights.ClickAnalyticsPlugin;
var clickPluginInstance = new clickPlugin();

// Behavior enum values
var behaviorMap = {
  UNDEFINED: 0, // default, Undefined

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Page Experience [1-19]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  NAVIGATIONBACK: 1, // Advancing to the previous index position within a webpage
  NAVIGATION: 2, // Advancing to a specific index position within a webpage
  NAVIGATIONFORWARD: 3, // Advancing to the next index position within a webpage
  APPLY: 4, // Applying filter(s) or making selections
  REMOVE: 5, // Applying filter(s) or removing selections
  SORT: 6, // Sorting content
  EXPAND: 7, // Expanding content or content container
  REDUCE: 8, // Sorting content
  CONTEXTMENU: 9, // Context Menu
  TAB: 10, // Tab control
  COPY: 11, // Copy the contents of a page
  EXPERIMENTATION: 12, // Used to identify a third party experimentation event
  PRINT: 13, // User printed page
  SHOW: 14, //  Displaying an overlay
  HIDE: 15, //  Hiding an overlay
  MAXIMIZE: 16, //  Maximizing an overlay
  MINIMIZE: 17, // Minimizing an overlay
  BACKBUTTON: 18, //  Clicking the back button

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Scenario Process [20-39]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  STARTPROCESS: 20, // Initiate a web process unique to adopter
  PROCESSCHECKPOINT: 21, // Represents a checkpoint in a web process unique to adopter
  COMPLETEPROCESS: 22, // Page Actions that complete a web process unique to adopter
  SCENARIOCANCEL: 23, // Actions resulting from cancelling a process/scenario

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Download [40-59]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  DOWNLOADCOMMIT: 40, // Initiating an unmeasurable off-network download
  DOWNLOAD: 41, // Initiating a download

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Search [60-79]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  SEARCHAUTOCOMPLETE: 60, // Auto-completing a search query during user input
  SEARCH: 61, // Submitting a search query
  SEARCHINITIATE: 62, // Initiating a search query
  TEXTBOXINPUT: 63, // Typing or entering text in the text box

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Commerce [80-99]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  VIEWCART: 82, // Viewing the cart
  ADDWISHLIST: 83, // Adding a physical or digital good or services to a wishlist
  FINDSTORE: 84, // Finding a physical store
  CHECKOUT: 85, // Before you fill in credit card info
  REMOVEFROMCART: 86, // Remove an item from the cart
  PURCHASECOMPLETE: 87, // Used to track the pageView event that happens when the CongratsPage or Thank You page loads after a successful purchase
  VIEWCHECKOUTPAGE: 88, // View the checkout page
  VIEWCARTPAGE: 89, // View the cart page
  VIEWPDP: 90, // View a PDP
  UPDATEITEMQUANTITY: 91, // Update an item's quantity
  INTENTTOBUY: 92, // User has the intent to buy an item
  PUSHTOINSTALL: 93, // User has selected the push to install option

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Authentication [100-119]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  SIGNIN: 100, // User sign-in
  SIGNOUT: 101, // User sign-out

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Social [120-139]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  SOCIALSHARE: 120, // "Sharing" content for a specific social channel
  SOCIALLIKE: 121, // "Liking" content for a specific social channel
  SOCIALREPLY: 122, // "Replying" content for a specific social channel
  CALL: 123, // Click on a "call" link
  EMAIL: 124, // Click on an "email" link
  COMMUNITY: 125, // Click on a "community" link

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Feedback [140-159]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  VOTE: 140, // Rating content or voting for content
  SURVEYCHECKPOINT: 145, // reaching the survey page/form

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Registration, Contact [160-179]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  REGISTRATIONINITIATE: 161, // Initiating a registration process
  REGISTRATIONCOMPLETE: 162, // Completing a registration process
  CANCELSUBSCRIPTION: 163, // Canceling a subscription
  RENEWSUBSCRIPTION: 164, // Renewing a subscription
  CHANGESUBSCRIPTION: 165, // Changing a subscription
  REGISTRATIONCHECKPOINT: 166, // Reaching the registration page/form

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Chat [180-199]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  CHATINITIATE: 180, // Initiating a chat experience
  CHATEND: 181, // Ending a chat experience

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Trial [200-209]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  TRIALSIGNUP: 200, // Signing-up for a trial
  TRIALINITIATE: 201, // Initiating a trial

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Signup [210-219]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  SIGNUP: 210, // Signing-up for a notification or service
  FREESIGNUP: 211, // Signing-up for a free service

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Referals [220-229]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  PARTNERREFERRAL: 220, // Navigating to a partner's web property

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Intents [230-239]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  LEARNLOWFUNNEL: 230, // Engaging in learning behavior on a commerce page (ex. "Learn more click")
  LEARNHIGHFUNNEL: 231, // Engaging in learning behavior on a non-commerce page (ex. "Learn more click")
  SHOPPINGINTENT: 232, // Shopping behavior prior to landing on a commerce page

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  // Video [240-259]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  VIDEOSTART: 240, // Initiating a video
  VIDEOPAUSE: 241, // Pausing a video
  VIDEOCONTINUE: 242, // Pausing or resuming a video.
  VIDEOCHECKPOINT: 243, // Capturing predetermined video percentage complete.
  VIDEOJUMP: 244, // Jumping to a new video location.
  VIDEOCOMPLETE: 245, // Completing a video (or % proxy)
  VIDEOBUFFERING: 246, // Capturing a video buffer event
  VIDEOERROR: 247, // Capturing a video error
  VIDEOMUTE: 248, // Muting a video
  VIDEOUNMUTE: 249, // Unmuting a video
  VIDEOFULLSCREEN: 250, // Making a video full screen
  VIDEOUNFULLSCREEN: 251, // Making a video return from full screen to original size
  VIDEOREPLAY: 252, // Making a video replay
  VIDEOPLAYERLOAD: 253, // Loading the video player
  VIDEOPLAYERCLICK: 254, //  Click on a button within the interactive player
  VIDEOVOLUMECONTROL: 255, //  Click on video volume control
  VIDEOAUDIOTRACKCONTROL: 256, // Click on audio control within a video
  VIDEOCLOSEDCAPTIONCONTROL: 257, //  Click on the closed caption control
  VIDEOCLOSEDCAPTIONSTYLE: 258, //  Click to change closed caption style
  VIDEORESOLUTIONCONTROL: 259, //  Click to change resolution

  ///////////////////////////////////////////////////////////////////////////////////////////////////
  //    Advertisement Engagement [280-299]
  ///////////////////////////////////////////////////////////////////////////////////////////////////
  ADBUFFERING: 283, // Ad is buffering
  ADERROR: 284, // Ad error
  ADSTART: 285, // Ad start
  ADCOMPLETE: 286, // Ad complete
  ADSKIP: 287, // Ad skipped
  ADTIMEOUT: 288, // Ad timed-out
  OTHER: 300 // Other
};

// Application Insights Configuration
var configObj = {
  instrumentationKey: "YOUR INSTRUMENTATION KEY",
  extensions: [clickPluginInstance],
  extensionConfig: {
    [clickPluginInstance.identifier]: {
      behaviorValidator: Microsoft.ApplicationInsights.BehaviorMapValidator(behaviorMap),
      defaultRightClickBhvr: 9
    },
  },
};
var appInsights = new Microsoft.ApplicationInsights.ApplicationInsights({
  config: configObj
});
appInsights.loadAppInsights();

サンプル アプリSample app

クリック分析自動収集プラグインが有効になっている単純な Web アプリSimple web app with Click Analytics Auto-collection Plugin enabled.

次の手順Next steps