analytics.jsのexception hitはdescriptionとfatalを分け、送信失敗と例外発生を混同しない

analytics.jsでJavaScriptの例外を計測するには、例外処理の中からexception hitを送ります。exDescriptionには例外の分類、exFatalには利用者が目的の処理を続けられるかという判断を入れます。

ただし、ga('send', 'exception')を呼んだことは、Google Analyticsのレポートへhitが反映された証明ではありません。例外の発生、送信commandの実行、通信処理、レポート反映は別々に確認します。

exception hitはJavaScriptの例外を自動収集しない

Google Analyticsのanalytics.js Exception Trackingは、send commandへexception hit typeを渡す方法を示しています。

ga('send', 'exception', {
    'exDescription': 'OrderFormInitialization',
    'exFatal': true
});

これは説明用の分類名です。analytics.jsがページ内のすべてのJavaScript errorを探して送るのではありません。例外を捕捉する場所と、送信する条件をサイト側のコードで決めます。

try {
    initializeOrderForm();
} catch (error) {
    ga('send', 'exception', {
        'exDescription': 'OrderFormInitialization',
        'exFatal': true
    });

    showOrderFormUnavailableMessage();
}

initializeOrderForm()とshowOrderFormUnavailableMessage()は仮の関数です。例外を送るだけで画面を止めず、利用者へ代わりの案内を出す処理まで分けています。

exDescriptionは集計できる短い分類名にする

exDescriptionは任意の文字列で、Field Referenceでは最大150 bytesです。例外objectの全文、URL、入力内容をそのまま送るより、機能と失敗箇所が分かる固定の分類名を決めます。

たとえば、同じ注文formでも次は別の原因です。

分類名へ利用者の氏名、mail address、入力内容を入れません。また、毎回異なるerror message全文を入れると、同じ原因を一つの群として比較しにくくなります。詳細なstackや入力条件が必要なら、アクセスを制限した開発用logへ分けます。

exFatalは処理を続けられるかで決める

exFatalはbooleanで、trueはfatalな例外を表します。Field Referenceの初期値はtrueに相当するため、省略せず明示します。

fatalかどうかは、JavaScriptの例外名だけでは決まりません。利用者がその機能の目的を達成できるかで分類します。

• 注文formを開けず、ほかの送信手段も示せないならtrue
• 補助的なpreviewだけが失敗し、入力と送信を続けられるならfalse
• 一部の表示が崩れても主要操作を続けられるなら、復旧処理を確認してからfalse

同じ例外でも、ページの役割と代替手段によって判断は変わります。実装者だけで決めず、運用担当者と「何ができなければfatalか」を先にそろえます。

hitCallbackは送信成功だけを知らせるものではない

analytics.js Field Referenceの保存版では、hitCallbackはhitを正常に送った後だけでなく、送れない、または送信に失敗したと判断した場合にも呼ばれます。

したがって、callbackが実行された回数を、Google Analyticsへ届いたexception数として使えません。analytics.jsの読込失敗などではcallback自体が呼ばれない場合もあります。

確認は次の四段階に分けます。

1. 意図した操作で例外処理へ入ったか。
2. ga()へexception、exDescription、exFatalを渡したか。
3. browserの通信記録でGoogle Analyticsへのrequestが発生したか。
4. レポートで対象期間とプロパティをそろえ、分類別の件数を確認できるか。

exception hitがない場合、「例外が起きなかった」と「例外は起きたが送れなかった」を分けます。逆に、同じ例外処理から何度も送る実装では、例外件数を利用者数や障害人数と同一視できません。

最初の一手は、主要な操作を一つ選び、その操作を続けられない条件を一つだけexception hitへします。固定したexDescriptionと明示的なexFatalを送り、例外処理、通信、レポートを別々に確認してください。