スニペットのインストール

概要

Pendoは、プロダクトの使用状況やユーザーからのフィードバックを把握し、アプリ内でユーザーとコミュニケーションをとりながら、ユーザーに参加を促したり、ユーザーを教育したり価値あるものに導いたりすることができます。

Pendoを使用する場合、アプリケーションのすべてのページに存在するテンプレートに小さなJavascriptスニペットを挿入する必要があります。このスニペットは、当社のCDNからJavascriptファイルを安全かつ非同期に読み込みます。1つのインストールスニペットですべてのアプリケーションをカバーし、すべてのフレームワークをサポートしています。

簡単な概要はこちらのビデオをご覧ください。

 

 

インストールプロセス

Pendoを利用する方が開発者である必要はありませんが、簡単なインストール作業が必要です。ほとんどのアプリでは、スニペットを一般的なHTMLテンプレートにそのまま挿入するだけです。この作業を行う間は、できるだけ早くお客様の技術担当者と連絡を取ることを強くお勧めします。そうすることで、技術者は迅速かつ適切な実装を行うために必要なことを理解できます。

次の3つのステップで、Pendoのインストールを行います。

  1. インストールタイプ(標準またはJWT)の決定
  2. 訪問者とアカウント情報(メタデータ)の識別
  3. Pendoスニペットのインストール
  4. インストールの検証

データが最初にPendoに取り込まれるまでに、最大2時間かかることがあります。データの受信が開始されると、メールでお知らせが届きます。メールを受信したら、管理者のみがアクセス可能な[サブスクリプション設定(Subscription Settings)]ページに移動して、受信したデータを確認してください。

注:JWTを使ったPendoスニペットのインストールの詳細については、こちらをクリックしてください。

ステップ1.インストールタイプの決定

スニペットをインストールする前に、お客様に最適なインストールのタイプ(標準またはJWT)を選択することが非常に重要です。簡単に言うと、標準インストールではデータを処理するためにJWT共有シークレットは必要ありませんが、JWTスニペットではデータを処理するために共有シークレットが必須です。お客様のステージとセキュリティポリシーに応じて、これらのオプションをできるだけ早く技術担当者に伝えることを強くお勧めします。JWTスニペットを選択する場合は、ステップ3の処理を完了するために追加のインストール要件が必要であることに注意してください。

ステップ2.訪問者とアカウントメタデータの識別

Pendoスニペットをインストールする前に、取得するべき情報またはメタデータを識別します。Pendoは、スニペットで定義した訪問者(またはユーザー)とアカウント(またはユーザーのグループ)に関するメタデータを保持しています。これらはJavaScriptスニペットで定義されるため、「エージェントメタデータ」と呼ばれます。

各訪問者とアカウントには、必要に応じてガイドを追跡し、ガイドに提供するために共通の一意のIDが付与されます。メタデータを追加すれば、Pendo内に追加のコンテキストを保持でき、NPSアンケートの対象者を適切にセグメント化したり、ターゲットに指定できたりします。メタデータの変数はアプリケーションごとに異なる可能性があるため、通常、お客様は使用するメタデータを識別し、技術者と連携します。

訪問者メタデータ

訪問者IDは必須のメタデータフィールドで、Pendoデータ内のユーザーを識別するためにスニペットで調整する必要があります。

訪問者IDは、分析を正確に追跡し、ガイドを提供するために、環境やプロダクトライン共通の一意の値である必要があります。

警告訪問者IDは、環境やプロダクトライン全体で一意の値であることが必須です。そうすれば、分析とガイドが重複することはありません。Pendoの分析とガイドは訪問者IDがベースとなっているため、IDを変更することはできません。訪問者IDの値を変更すると、変更後のユーザーは新しいユーザーとして表示され、データが重複します。

Pendoが提供するJavaScriptスニペットを使用する場合、お客様の開発者はVISITOR-UNIQUE-IDをお客様のプロダクトに関連付けられた一意の訪問者IDまたはユーザーIDに置き換える必要があります。

訪問者メタデータの例を次に示します。

  • 一意の訪問者ID
  • メールアドレス(注:NPSをユーザーに送信する場合は必要。機能のリリース時にスニペットを調整する必要がないように、ユーザーのメールアドレスをメタデータ値として追加してください)
  • ユーザー権限(管理者、ユーザー、読み取り専用など)
  • 役割または役職
  • 部署
注:提供されたスニペット内でVISITOR-UNIQUE-IDの値を調整しない場合、PendoはランダムなIDを割り当て、すべてのユーザーは匿名ユーザーとして識別されます。ただし、匿名化したい場合は、訪問者IDとして空の文字列を渡すことをお勧めします。

アカウントメタデータ

必須ではありませんが、ユーザーのグループに関連付けられたアカウント情報を渡すことを強くお勧めします。アカウントIDは、ユーザーのグループに関連付けられた共通の一意のIDでもあります。さらに、アカウント名(IDから特定できない場合)などのアカウントに関する追加情報や、業種、プラン価格、アカウント作成日など、ターゲットに設定する場合に役立つようなその他の情報を渡すことをお勧めします。

:PendoフィードバックにはアカウントIDが必須です。

PendoのJavaScriptスニペットでは、お客様の開発者はACCOUNT-UNIQUE-IDをアプリケーションに関連付けられた一意のアカウントIDに置き換える必要があります。

アカウントメタデータの例を次に示します。

  • 一意のアカウントID
  • アカウント名
  • 業界(会計、不動産、ヘルスケア、テクノロジーなど)
  • 市場セグメント(中小企業、大企業など)
  • アカウント作成日またはサインアップ日
  • 契約開始日
  • 契約更新日
  • プラン価格または契約金額
注:アカウントの概念がない場合は、ACCOUNT-UNIQUE-ID行をコメントアウトしてください。

ステップ3.PendoのJavaScriptスニペットのインストール

標準インストール

マルチページアプリケーションの場合

Pendoスニペットはどこに追加しますか。あらゆる場所に追加できます。

  • 一般的なHTMLテンプレートにスニペットを挿入します
  • すべてのページ
  • すべてのiframe

シングルページアプリケーションの場合

Pendoスニペットの最初の部分であるfunction(p,e,n,d,o){}がアプリケーションライブラリに追加され、次にアプリケーションがPendoと共有するユーザー識別情報を取得すると、後半部分であるpendo.initialize ({}) がページとともに読み込まれます。

すべてのユーザーのトラッキングがすぐに開始され、アプリケーション内の任意の場所にある特定のフィーチャーがPendoインターフェースにタグ付けされることで、過去にさかのぼって分析することができます。

ヒント:ベストプラクティスとして、PendoのJavaScriptスニペットをさまざまな場所にインストールして、過去にさかのぼって分析する利点を最大限に活用できます。

インストールが完了した後は、Pendoがアプリケーションから最初のデータを受信したときにメールで通知します。データの受信には、最大で2時間かかることがあります。

JWTインストール

JWTスニペットをインストールするには、JWTとともに共有シークレットを使用してリクエストに署名する必要があります。共有シークレットを確認するには、[インストール設定(Install Settings)]ページにログインします(管理者のみがアクセス可能)。

 

ステップ4.インストールの検証

インストールを検証するには2つの方法があります。

  1. Pendoデータマッピング(Data Mappings)とイベントの生データ(Raw Events)を[インストール設定(Install Settings)]で確認する
  2. ブラウザ開発者コンソールを使用する

Pendoデータマッピングとイベントの生データを[インストール設定]で確認する

  • ナビゲーションの左下にある[設定(Settings)]をクリックします
  • [サブスクリプション設定(Subscription Settings)]を選択します
    • アプリの上にカーソルを合わせて、[Appの詳細を表示(View App Details)]をクリックします
    • [インストール設定]タブを選択します

データマッピング

[データマッピング(Data Mappings)]セクションを調べて、Pendoに格納されているデータ型が、スニペットで送信された実際のデータ型と一致していることを確認します。このメタデータは、ユーザーがアプリケーションのページを訪問したときに自動的に更新され、フィールドがPendoに受け渡されます。エージェントのメタデータフィールドが正しく入力されていない場合、ユーザーが次回アプリケーションにアクセスして正しい情報を受け渡したときにのみ更新することができます。これらのフィールドは、手動またはAPIを通じて変更することはできません。

イベントの生データ

インストールをさらに検証するための[イベントの生データ(Raw Events)]リストの確認は、これまでに取得したメタデータの確認を通して行います。

ブラウザ開発者コンソール

インストールは次の手順でも確認できます。

  1. Pendoがインストールされているアプリケーションを起動します
  2. ユーザーとしてサインインします
  3. ブラウザ開発者コンソールを開きます
  4. コンソールにpendo.validateInstall()と入力してEnterを押します
  5. 訪問者(Visitor)とアカウント(Account)のメタデータが返されます
注:データの受信には、最大で2時間かかることがあります。

インストールに関するFAQ

スニペットはどこにインストールすればよいですか?

あらゆる場所に追加できます。スニペットはすべてのページにインストールする必要があります。サイトではiframeを使用していますか?使用している場合、それぞれのiframeにインストールします。

なぜ共通の一意のIDが重要なのですか?

一意の訪問者IDとアカウントIDを渡していることを確認してください。これにより、訪問者とアカウントが識別されます。いずれかが重複している場合、複数のユーザーのデータが1つのIDに集約されてしまう可能性があります

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

メタデータを利用することで、豊富なインサイトをもたらし、ガイドをパーソナライズするための強力なセグメントを作成することができます。受け渡されたあらゆる情報に基づいて、訪問者をセグメント化することができます。メタデータについて詳しくはこちら。

未知のユーザー(Unknown users)とは誰ですか?

未知のユーザーや匿名のユーザーとは、アプリにログインしていないユーザーのことです。匿名の訪問者がいたとして、彼らのデータを見たい場合、彼らがガイドを見られるようにしたい場合、未知のユーザーに対する分析を有効にして、必要に応じてガイドの閲覧を許可することができます。

表示したくないデータがある場合

Pendoでは、サーバー/ホストドメイン、IPアドレス、訪問者ID、アカウントIDに基づいてデータを非表示にすることができます。除外リスト(Exclude List)について詳しくはこちら

エージェントをローカルでホストできますか?

インストールのスニペットは、Pendoのエージェントコードが含まれているpendo.jsを取り込みます。pendo.jsをPendoのCDNから取得したくない場合は、アプリケーションでダウンロードしてホストできます。管理者はこのコードを[サブスクリプション設定(Subscription Settings)]ページからダウンロードできます。対象のウェブアプリをクリックし、[エージェントの設定(Agent Settings)]タブ、[ステージング/本番設定の管理(Manage Staging/Production Settings)]の順にクリックし、現在選択している[ガイド配信設定(Guide Delivery Settings)]の下にある[ダウンロード(Download)]リンクをクリックしてください。インストールスニペット内の参照先は、ホストされているpendo.jsファイルを指すように更新する必要があります。

Pendoはオンプレミスにインストールできますか?

Pendoエージェントは、ローカルでホストして、オンプレミスのアプリケーションに取り込むことができます。Pendoは現在、ホストおよびデータ処理をクラウドでのみ行っています。そのため、インターネットへの接続が必要となり、Pendoのサーバーを包含リスト(Include Lists)に追加する必要があります。概して、ガイドはインバウンドトラフィックであり、分析はアウトバウンドです。

トラブルシューティング

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

APIキーがスニペットに含まれていることを確認してくださいインストール設定ページからスニペットをコピーした場合、APIキーはすでに含まれています。他の場所からスニペットをコピーした場合は、APIキーがスニペットに含まれていることを確認してください。Pendoですべてのデータを受信するには、特定のデータ構文のルールに従う必要があります。null値はどのフィールドにも送信しないでください。データがないフィールドは、送信を省略してください。スニペットに追加したカスタムフィールドには、スペースを含めることができません。フィールドは、アルファベットまたはアンダースコアで始まり、その後にアルファベットまたは数字、アンダースコアを組み合わせることができます訪問者とアカウントのメタデータについて、詳しくはこちらをご覧ください。

注:データは毎正時にバッチで集約され、Pendo UIに表示されるまでには正時から最大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
  // monthly_value:// Recommended if using Pendo Feedback
  // is_paying:    // Recommended if using Pendo Feedback
  // planLevel:    // Optional
  // planPrice:    // 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.name',
  role:          '$user.accessLevel',
  creationDate:  $user.creationDate
},
account: {
  id:            $account.ID,
  name:          '$account.name',
  monthly_value: $account.monthly_value,
  is_paying:     $account.is_paying,
  planLevel:     $account.subscriptionCost
}

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

visitor: {
  id:            62343,
  email:         'john@doe.com',
  full_name:     'John Doe',
  role:          'admin',
  creationDate:  1404326949156
},
account: {
  id:            17,
  name:          'Acme, inc',
  monthly_value: 99.99,
  is_paying:     true,
  planLevel:     995
}
 

フィードバックに自動タグが表示されないのはなぜですか?

フィードバックは、Pendoスニペットに埋め込まれた訪問者タグとアカウントタグの値を受け取ります。Pendoスニペットから収集したメタデータの値をフィードバックUIに表示するには、訪問者タグとアカウントタグのキー値ペアを配列形式で追加します。フィードバックの自動タグ付けの詳細については、こちらをクリックしてください。

このコードのテンプレートは次のとおりです。

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
// tags: // Recommended if using Pendo Feedback // 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 // monthly_value:// Recommended if using Pendo Feedback // is_paying: // Recommended if using Pendo Feedback // planLevel: // Optional // planPrice: // Optional // creationDate: // Optional
// tags: // Recommended if using Pendo Feedback // 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,
tags: ['$user.accessLevel','$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,
tags: ['$account.subscriptionCost','$account.isFoo'] }
 

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

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

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

オプションフラグ

JSスニペットには、次の2つのオプションフラグを配置できます。

excludeAllText: true

デフォルトでは、Pendoエージェントは訪問者がクリックしたDOM要素からテキストの値を収集します(ただし、テキストエリアや入力フィールドからはテキストを収集しません)。これは、どのようなHTMLがフィーチャーの一部であるかをより正確に表すために行われます(たとえば、ボタンテキストを使って[検索(Search)]ボタンと[ログアウト(Log out)]ボタンの違いを判別し、ユーザーがどちらを多く使用しているかを知ることができます)。

これらのテキストをPendoに収集させたくない場合は、スニペットのpendo_optionsオブジェクト内でexcludeAllTextフラグをtrueに設定します。注:これにより、プロダクトのフィーチャーを追跡することが難しくなります。

実際にクリックされた要素(およびその親から本文まで)のみが処理されることに注意してください。Pendoエージェントが勝手にウェブアプリケーションのデータを収集することはありません。

disableGuides: true

ガイドプロダクトをまったく使用しない(エンドユーザーに対してアプリ内メッセージを表示しない)ことがわかっている場合は、disableGuides:trueフラグを設定すると、Pendoスニペットは利用可能なガイドがあるかどうかを確認するための送信要求を行わなくなります。

 

Pendoパフォーマンス

ウェブアプリケーションにPendoのJavascriptスニペットを追加することによって、パフォーマンスにどのような影響がありますか?

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

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

その他の情報については、セキュリティおよびプライバシーに関する記事をご覧ください。