シングルページフレームワークのインストール

最終更新日:

Pendoのプロダクト分析機能は、シングルページのアプリケーションフレームワークに特に役立ちます。従来のウェブ分析ツールは、ページ閲覧数に合わせて作られているため、このような環境では苦労します。シングルページのフレームワークでは、単一のページ閲覧にさまざまなユーザー操作が発生します。

こういった問題は開発チームで回避できますが、分析ソリューションが適切に追跡されていることを確認するために、追加の作業負荷がかかります。Pendoは、ページ上のすべてのユーザー操作をキャプチャし、特定のユーザーに帰属させることで、これらの課題を回避します。これを実行するには、アプリケーションに小さなJavaScriptスニペットを挿入する必要があります。このスニペットは、当社のCDNからJavascriptファイルを安全かつ非同期に読み込みます。

インストールスクリプト(「スニペット」)

Pendoのインストールスニペットは、インストール設定 ページ(管理者のみアクセス可能)にあり、ほとんどのアプリでそのまま共通のHTMLテンプレートに挿入することが可能です。データがPendoに取り込まれるまでに、最大2時間かかることがあります。データの受信が開始されると、メールでお知らせが届きます。

インストールプロセス

インストール方法は、同じインストールスクリプト(一般に「スニペット」と呼ばれます)を使用するマルチページインストールと同様です。しかし、展開方法が若干異なります。シングルページフレームワークでは、Pendoインストールスクリプトの最初の部分であるfunction(p,e,n,d,o){}がアプリケーションライブラリに追加されます。後半のpendo.initialize({})は、アプリケーションがPendoと共有するユーザー識別情報を持った時点でページに読み込まれます。

Agent 2.0 FAQには、インストールスクリプトやPendoエージェントの更新方法に関する詳細情報が記載されています。

警告:ここに示すすべてのスニペットは、提供されたJavaScriptスニペットを必要に応じて調整する方法について説明するためのサンプルです。固有のAPIキーを使用してスニペットをコピーして変更する必要があるため、この記事から直接コピーしないようにしてください。

ここでは、インストール時にスニペットを分割する方法について、サンプルスニペットを使って説明します。

<script> 
(function(apiKey){
(function(p,e,n,d,o){var v,w,x,y,z;o=p[d]=p[d]||{};o._q=o._q||[];

v=['initialize','identify','updateOptions','pageLoad','track'];for(w=0,x=v.length;w<x;++w)(function(m){

o[m]=o[m]||function(){o._q[m===v[0]?'unshift':'push']([m].concat([].slice.call(arguments,0)));};})(v[w]);

y=e.createElement(n);y.async=!0;y.src='https://cdn.pendo.io/agent/static/'+apiKey+'/pendo.js';

z=e.getElementsByTagName(n)[0];z.parentNode.insertBefore(y,z);})(window,document,'script','pendo');

// この関数は、訪問者IDフィールドをアプリの値を使用するように変更しない限り、Pendoの匿名の訪問者IDを作成します
// この関数は、アカウントIDフィールドを変更してアプリの値を使用しない限り、アカウントIDのプレースホルダーである'ACCOUNT-UNIQUE-ID'の値を使用します
// ユーザーがアプリで認証され、訪問者とアカウントIDの値が利用可能になった後に、この関数を呼び出します
// 値の型には文字列、数値、またはブール値を使用してください。
pendo.initialize({
visitor: {
id:              'VISITOR-UNIQUE-ID'   // Required if user is logged in, default creates anonymous ID
// email:        // Recommended if using Pendo Feedback, or NPS Email
// full_name:    // Recommended if using Pendo Feedback
// role:         // Optional

// You can add any additional visitor level key-values here,
// as long as it's not one of the above reserved names.
},

account: {
id:           'ACCOUNT-UNIQUE-ID' // Required if using Pendo Feedback, default uses the value 'ACCOUNT-UNIQUE-ID'
// name:         // Optional
// is_paying:    // Recommended if using Pendo Feedback
// monthly_value:// Recommended if using Pendo Feedback
// planLevel:    // Optional
// planPrice:    // Optional
// creationDate: // Optional

// You can add any additional visitor level key-values here,
// as long as it's not one of the above reserved names.
}
});
})('ACTUAL_API_KEY_HERE');
</script>

インストールスクリプト(パート1)

たとえば、インストールスクリプトの次の部分をアプリケーションライブラリやインデックスページに追加します。

<script> 
(function(apiKey){
(function(p,e,n,d,o){var v,w,x,y,z;o=p[d]=p[d]||{};o._q=o._q||[];

v=['initialize','identify','updateOptions','pageLoad','track'];for(w=0,x=v.length;w<x;++w)(function(m){

o[m]=o[m]||function(){o._q[m===v[0]?'unshift':'push']([m].concat([].slice.call(arguments,0)));};})(v[w]);

y=e.createElement(n);y.async=!0;y.src='https://cdn.pendo.io/agent/static/'+apiKey+'/pendo.js';

z=e.getElementsByTagName(n)[0];z.parentNode.insertBefore(y,z);})(window,document,'script','pendo');
})('ACTUAL_API_KEY_HERE');
</script>

インストールスクリプト(パート2)

アプリケーション内にユーザーのコンテキストができたら、インストールスクリプトの後半部分を使って、ユーザー、アカウント、その他の人口統計情報をPendoに渡します。

// この関数は、訪問者IDフィールドをアプリの値を使用するように変更しない限り、Pendoの匿名の訪問者IDを作成します
// この関数は、アカウントIDフィールドを変更してアプリの値を使用しない限り、アカウントIDのプレースホルダーである'ACCOUNT-UNIQUE-ID'の値を使用します
// ユーザーがアプリで認証され、訪問者とアカウントIDの値が利用可能になった後に、この関数を呼び出します
// 値の型には文字列、数値、またはブール値を使用してください。
pendo.initialize({
visitor: {
id:              'VISITOR-UNIQUE-ID'   // Required if user is logged in, default creates anonymous ID
// email:        // Recommended if using Pendo Feedback, or NPS Email
// full_name:    // Recommended if using Pendo Feedback
// role:         // Optional

// You can add any additional visitor level key-values here,
// as long as it's not one of the above reserved names.
},

account: {
id:           'ACCOUNT-UNIQUE-ID' // Required if using Pendo Feedback, default uses the value 'ACCOUNT-UNIQUE-ID'
// name:         // Optional
// is_paying:    // Recommended if using Pendo Feedback
// monthly_value:// Recommended if using Pendo Feedback
// planLevel:    // Optional
// planPrice:    // Optional
// creationDate: // Optional

// You can add any additional visitor level key-values here,
// as long as it's not one of the above reserved names.
}
});

TypeScriptを使用するアプリケーションの場合は、Pendoに問い合わせするのではなく、window.pendo.initialize()、または(window as any).pendo.initialize()を使用する必要があります。

よくある質問

インストールスクリプトはどこにインストールすればよいですか。すべての場所にインストールします。

インストールスクリプト(スニペット)は、すべてのページにインストールする必要があります。iframeを使用しているサイトでは、それぞれのフレームにPendoがインストールされていることを確認する必要があります。

なぜ全体で一意のIDが重要なのですか?

一意の訪問者IDやアカウントIDは、エンドユーザーと顧客をそれぞれ識別するものです。いずれかが重複している場合、複数のユーザーのデータが1つのIDに集約されてしまう可能性があります。詳細については、Pendoインストールの計画を参照してください。

なぜメタデータが重要なのですか?

Pendoに渡したメタデータをもとに、訪問者をセグメント化することができます。たとえば、各ユーザーの役割をPendoに渡して、特定の役割を対象としたガイドのターゲット設定やデータのフィルタリングができるようにすることも可能です。詳細については、Pendoインストールの計画を参照してください。

未知のユーザー、匿名のユーザーとは誰ですか?

未知のユーザーや匿名のユーザーとは、アプリにサインインしていない訪問者のことです。匿名の訪問者のデータを見たい場合や、匿名の訪問者にガイドを見てもらいたい場合は、未知のユーザーに対してアナリティクスを有効にすることができます。詳細については、匿名の訪問者を参照してください。

表示したくないデータを非表示にするにはどうすればよいですか?

テスト環境とステージング環境の間、社内ユーザーと訪問者の間で、データが乱雑になることがあります。含めたくないデータがある場合は、それを除外することができます。Pendoでは、サーバー/ホストドメイン、IPアドレス、訪問者ID、アカウントIDに基づいてデータを非表示にすることができます。

URLの場合はどうなりますか?

Pendoは、URLでアプリケーションの異なるページを区別しています。ユーザーがアプリケーション内を移動してもURLが変わらない場合は、ロケーションAPIを実装することをお勧めします。

ウィンドウの再読み込みなしに訪問者やアカウントのデータが変更された場合はどうしたらよいですか?

オプションフィールドを変更したり、新しいビジター(Visitor)IDやアカウント(Account)IDでセッションを再初期化したりする関数があります。

訪問者に関連する追加のメタデータを変更する場合は、pendo.updateOptions()を呼び出してください。

訪問者IDやアカウントIDを変更する必要がある場合は、pendo.identify()を呼び出し、初期化の時と同様に訪問者IDやアカウントIDを渡します。

初期化関数と識別関数の詳細は、開発者向けドキュメントをご覧ください。

検証とトラブルシューティング

インストールが正しく行われていることを確認するにはどうすればよいですか?

インストールの状況や、特定のユーザーにメタデータが設定されているかどうかを確認するには、次のようにします。

  1. Pendoをインストールしたら、ブラウザのタブでアプリケーションを開きます。
  2. ユーザーとしてサインインします。
  3. ブラウザ開発者コンソールを開きます。
  4. コンソールにpendo.validateInstall()と入力してEnterを押します。

これにより、訪問者の識別可能なメタデータの情報が返されます。

Pendoにデータが表示されないのはなぜですか?

インストールスクリプトにAPIキーが含まれていることを確認してください。インストール設定ページからコードブロックをコピーした場合は、APIキーはすでに含まれています。他の場所からコードブロックを取得した場合は、APIキーが存在することを確認してください。

Pendoですべてのデータを受信するには、以下のデータ構文のルールに従う必要があります。どのフィールドにもNULL値を送信しないでください。データがないフィールドは、そのフィールドを送信しないでください。インストールスクリプトで追加されたカスタムフィールドに、スペースを含めないでください。フィールドは、アルファベットもしくはアンダースコアで始まり、その後にアルファベットもしくは数字、アンダースコアを組み合わせることができます詳しくは、訪問者やアカウントのメタデータを参照してください。

注: データはすぐには表示されません。毎時0分に一括集計され、PendoのUIに完全に表示されるまでに、毎時0分を過ぎてから最大15分かかることがあります。

pendo.jsおよびpendo-staging.js

Pendoインストールスクリプトは、まずpendo.jsエージェントを読み込みます。このエージェントは、サーバーのホスト名がステージングサーバーのルールに一致するかどうかをチェックし、一致した場合はpendo.jsではなくpendo-staging.jsからPendoオブジェクトを読み込みます。

ログインしているユーザーがいない

セットアップ中に「ログインしているユーザーがいません(No Logged In Users)」というメッセージが表示されますが、これはPendoがアプリケーションから基本データを受信している(具体的には、アプリで当該のページやフィーチャーが使用されている)が、ユーザーの識別情報がないことを通知しています。このデータがなくてもPendoを使用することはできますが、機能は大幅に低下します。

インストールスクリプトには、今回の問題の対象となる、訪問者ブロックとアカウントブロックという2つのブロックがあります。データが渡されていないか、構造が間違っているかのどちらかです。

このコードのテンプレートをご紹介します。

visitor: {
  id:              'VISITOR-UNIQUE-ID'   // Required if user is logged in
  // email:        // Recommended if using Pendo Feedback, or NPS Email
  // full_name:    // Recommended if using Pendo Feedback
  // role:         // Optional

  // You can add any additional visitor level key-values here,
  // as long as it's not one of the above reserved names.
},

account: {
  // id:           'ACCOUNT-UNIQUE-ID' // Highly recommended
  // name:         // Optional
  // is_paying:    // Recommended if using Pendo Feedback
  // monthly_value:// Recommended if using Pendo Feedback
  // planLevel:    // Optional
  // planPrice:    // Optional
  // creationDate: // Optional

  // You can add any additional account level key-values here,
  // as long as it's not one of the above reserved names.
}

これは、コードでデータがどのように見えるかのです。

visitor: {
  id:              $user.ID,
  email:           '$user.email',
  full_name:       '$user.full_name',
  role:            '$user.accessLevel',
  creationDate:    $user.creationDate
},

account: {
  id:           '$account.ID',
  name:         '$account.name',
  is_paying:    $account.is_paying,
  monthly_value:'$account.monthly_value',
  planLevel:    $account.subscriptionCost,
  isFoo:        $account.isFoo
}

これは、コードが処理され、Pendoに送信された後にどのように見えるかのです。

visitor: {
  id:              62343,
  email:           'john@doe.com',
  full_name:       'John Doe',
  role:            'admin',
  creationDate:    1404326949156
},

account: {
  id:           17,
  name:         'Acme, inc',
  is_paying:    true,
  monthly_value:'99.99',
  planLevel:    995,
  isFoo:        false
}

Pendoのパフォーマンス

PendoのJavascriptファイルは、AmazonのCloudfront CDNでホストされ、最先端のエッジキャッシングを利用して提供されています。javascriptのファイルは、わずか54Kバイトに縮小されており、非同期に読み込まれます。

データは2分ごと、およびページがアンロードされたときに、各ユーザーのブラウザから当社のサーバーにTLSで安全に送信されます。データは送信前に圧縮され、1回の送信は2KB以下になります。

詳細については、セキュリティとプライバシーの記事を参照してください。

オプションフラグ

JavaScriptのコードブロックにオプションのフラグを追加できます。詳細については、追加のFAQも含まれた開発者のためのPendoインストールガイドを参照してください。