開発者向けインストールガイド（Pendo Snippet）

Pendo AgentおよびAPI開発者向けドキュメントは、 https://engageapi.pendo.ioで入手可能です。

概要

Pendoは、製品の使用状況やユーザーからのフィードバックをキャプチャし、アプリ内でユーザーとコミュニケーションをとりながら、ユーザーに参加を促したり、ユーザーを教育したり価値あるものに導いたりすることができます。Pendoのタグ付けとガイドは完全にコードレスで、エンジニアリングリソースは不要です。ただし、エージェントのインストールとPendoの初期化にはエンジニアの力が必要です。PendoとPendoのインストールプロセスに関する情報は、導入計画文書（Installation Planning article）に掲載されています。Pendoチャンピオンには、Pendoインストールワークブック（Installation Workbook）に記入してもらい、インストールを完了するために必要な情報を共有することをお勧めします。準備をすれば、Pendoスニペットの技術的なインストールは簡単です。

Pendoを最初にインストールする際の技術的な部分はエージェントだけです。エージェントが正しくインストールされれば、誰でもPendoを使うことができます。エージェントは、ページの読み込みやフィーチャーのクリック数などの訪問者のイベントを追跡し、ガイドを読み込み、セッションのメタデータをキャプチャします。たとえば、タグ付けやトラックイベントのためのカスタムHTML属性を追加するなど、Pendoの使用を最適化および拡張するために、後から追加の開発を行うことができます。また、Pendoは、他の一般的なCRM、分析、およびコラボレーションツールとの統合を行っています。統合の範囲は、コードレスのインストールウィザードによるネイティブ統合から、カスタム開発まで多岐にわたりますが、この記事では説明しません。一般的な統合機能については、インテグレーション機能の記事をご覧ください。また、スニペットのインストールが完了した後のサブスクリプションの統合機能については、担当者にお問い合わせください。

ウェブインストールの概要とデモンストレーション - 動画時間：6:24

エージェント

Pendoエージェントのインストールは、スニペットと初期化の2つの要素で構成されています。スニペットは、Pendo.jsファイルをウィンドウに追加する短いJavascript関数です。初期化は、訪問者とアカウントのメタデータでユーザーを識別します。どちらもウェブサイトのすべてのページに必ず表示されますが、シングルページのアプリケーションの場合は、セッションごとに初期化する必要があります。複数ページのアプリケーションでは、ログイン後にページのハードリフレッシュがあった場合、ログインページだけでなく、すべてのページでPendoの初期化が必要になる場合があります。

通常、Pendoは訪問者が特定されてから初期化されます。意図的に匿名の訪問者を追跡する場合にのみ、訪問者IDなしでPendoを初期化してください。匿名の訪問者はCookieで追跡され、同じユーザーが複数のセッションで複数の訪問者としてカウントされることがあります。匿名の訪問者は、サブスクリプションのMAUの合計にカウントされます。匿名の訪問者がお客様のサブスクリプション料金に与える影響については、お客様の営業担当者またはアカウントマネージャーにお問い合わせください。

スニペット

スニペットのコードブロックは、Pendoをライブラリとして読み込み、ウィンドウレベルで機能を利用できるようにします。スクリプトは、アプリケーションキーも通過させます。アプリケーションキーは、インストールページで提供されるスニペットや、アプリの設定に含まれています。アプリケーションキーは、エージェントが収集したデータをPendoのサブスクリプションのアプリにマッピングします。

注：スニペットが存在しても、トラッキングが行われることにはなりません。トラッキングを行うためには、スニペットを初期化する必要があります。

初期化

利用状況を把握し、ガイドを配信するためには、Pendoエージェントの初期化が必要です。初期化では、お客様がPendoに提供するメタデータをカスタマイズします。Pendoのユーザーは、このメタデータを使って、分析で訪問者やアカウントをセグメント化し、ガイドをターゲットにすることができます。初期化は、訪問者が認証された後のウィンドウの再読み込みごと、またはサイトにiframeがある場合はフレームごとに実行する必要があります。

訪問者IDとアカウントIDの値は、インストール後も変更しないでください。イベントの生データには、訪問者とアカウントのIDのみが保存されます。その他のメタデータは、最初のインストール後に追加される可能性があり、Pendoの訪問者とアカウントの詳細が更新されます。インストール後に訪問者IDやアカウントIDのマッピングが変更された場合、Pendoでは新しい訪問者やアカウントの記録が作成されますが、製品の使用履歴やガイドの閲覧履歴は残りません。そうすると、分析やセグメント化に異常が生じ、ガイドエクスペリエンスを繰り返すことになります。

pendo.initialize({
    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' // Required if using Pendo Feedback
        // 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.
    }
});

初期化コードブロックを提供します。訪問者ID、アカウントID、および追加のメタデータとして渡す適切な値を決定する必要があります。訪問者IDは、ウェブやモバイルアプリなど、一人の人間がさまざまな製品を利用するカスタマージャーニー全体を表すものでなければなりません。このIDについては、製品チームとエンジニアリングチームの間でコンセンサスを得ることが重要です。開発やステージングなどの環境間でIDが競合することが心配な場合は、プレフィックスやサフィックスを使って環境の識別子をIDに追加することができます。異なる環境で訪問者を識別する方法は、記事「開発およびテストにおけるPendo（Pendo in Development and Testing）」に記載されています。異なる環境で訪問者を識別することは、後でデータを除外するときに役立ちます。

上記の追加フィールドは、訪問者やアカウントについてお客様が送信できるその他のメタデータの例です。日付、整数、浮動小数点、ブール値、リストを送ることができます。Pendoは、オブジェクトをサポートしていません。詳しくはデータマッピング（Data Mappings）の記事をご覧ください。

Pendoチャンピオンがインストールワークブックを記入している場合は、チームがキャプチャする予定のフィールドを「基本的なインストール（Basic Installation）」で確認してください。

注：初期化時に渡されるメタデータの合計サイズは64kb未満でなければなりません。サイズを決めるには、pendo.initialize()に渡されたパラメータをJSONに変換し、そのJSONファイルは64kbより小さくなければなりません。このデータはエージェントによって圧縮され、Pendoに送信されます。圧縮されたJSONデータが64kbより大きい場合は、エージェントによってドロップされます。

インストールの検証

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

1. イベントの生データ（Raw Events）とデータマッピング（Data Mappings）を［アプリの設定（App Settings）］で確認する
2. ブラウザ開発者コンソールのpendo.validateInstall()で確認する

イベントの生データ（Raw Events）とデータマッピング（Data Mappings）を［設定（Settings）］で確認する

［設定（Settings）］の［サブスクリプション設定（Subscription Settings）］を開いて［イベントの生データ（Raw Events）］にアクセスします。

［設定（Settings）］の［データマッピング（Data Mappings）］を開いて［データマッピング（Data Mappings）］にアクセスします。

イベントの生データ（Raw Events）

［アプリの詳細（App Details）］を開き、［イベントの生データ（Raw Events）］をクリックします。

注：アプリの詳細（App Details）では、アプリがインストールされていることを確認する必要があります。

イベントの生データのページには、エージェントによってキャプチャされた未処理イベントのリストが表示されます。イベントをクリックすると、そのイベントで収集されたコードやメタデータが表示されます。イベントには、そのイベントを生成したユーザーの訪問者IDとアカウントIDが表示されます。また、ブラウザのセッションメタデータを示すこともあります。スニペットに含まれる追加のメタデータは、イベントの生データには保存されません。

注：初期データの受信には、最大で2時間かかることがあります。

データマッピング

［データマッピング（Data Mappings）］を確認し、Pendoに登録されているデータとエージェントで送信されたデータが一致しているかどうかを確認します。このメタデータは、ユーザーがアプリケーションでPendoを初期化する際に、新しい訪問者を作成したり、既存の訪問者を更新したりします。エージェントのメタデータフィールドが正しく入力されていない場合は、次回のPendoの初期化時にのみ更新されます。これらのフィールドは、手動で変更することはできません。これらを変更するには、スニペットを修正するか、update visitor関数を渡す必要があります。

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

ブラウザコンソールでpendo.validateInstall()コマンドを入力することで、インストールを検証することができます。これは、匿名ユーザーを使用している場合を除き、スニペットと初期化がインストールされ、ユーザーが認証されている場合に行う必要があります。

1. アプリにサインインします
2. ブラウザ開発者コンソール（Browser Developer Console）を開きます
3. コンソールにpendo.validateInstall()と入力します
4. 訪問者とアカウントのメタデータが返されます

追加の設定

特定の状況下でPendoが実行されないようにするにはどうしたらいいですか？

Pendoでは、ガイドテスト用のステージングドメインを指定することができますが、特定の条件下で初期化を防ぐための設定は用意されていません。pendo.initialize()が呼ばれた場合、エージェントは動作を追跡し、ガイドの表示を試みます。

条件付きでPendoを初期化したい場合は、Pendoを初期化すべきかを判断するために、フィーチャーフラグを立てたり、初期化を「if」ステートメントで囲んだりするなど、何らかのロジックを使用することをお勧めします。 

URLに機密情報が含まれていますが、Pendoに見られないようにするにはどうしたらいいですか？

Pendoは、イベントの生データとページタグ付けに訪問者の現在のURLをプルします。ある訪問者のURLに含まれる情報の具体的な詳細は、イベントの生データやタグ付けされていないページを見ないとアクセスできません。タグ付けされたページのページルールに、機密データがワイルドカードとして組み込まれている場合、それらのページビューは自動的にタグ付けされたページの下にグループ化され、タグ付けされていないページでは見ることができません。

このデータがPendoに渡らないようにするには、URLサニタイズ機能を使うことをお勧めします。詳細はサポートまでお問い合わせください。

Pendoがテキストを収集するのを防ぐにはどうしたらいいですか？

Pendoは、クリックイベント属性を使ってPendoユーザーが設定しない限り、入力フィールドやテキストボックスのようなユーザー入力テキストを収集しません。　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　 　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　 　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　しかし、タグ付けを容易にするために、DOMからテキストを収集します。たとえば、フィーチャーやガイドは、element:contains("UI Text")をターゲットとした要素をUIでタグ付けすることができます。　　機密情報がDOMに表示されている場合は、要素の階層を記録する際に、イベントの生データによって完全にまたは部分的に収集されます。

テキストを収集できないようにする必要がある場合は、excludeAllText: trueという行を初期化に追加してください。

その他のエージェントのカスタマイズについては、開発者向けのドキュメントをご参照ください。

修正スニペットの例

pendo.initialize({
    visitor: {
        id:              'VISITOR-UNIQUE-ID'
    },
    account: {
        id:           'ACCOUNT-UNIQUE-ID'
    },
    excludeAllText: true 
 });

Pendoガイドを使用しない場合、スニペットでブロックできますか？

ガイドをまったく使用しないことがわかっている場合は、disableGuides:trueフラグを設定すると、Pendo エージェントは利用可能なガイドがあるかどうかを確認するための送信要求を行わなくなります。Pendoユーザーがガイドをビルドして公開しても、アプリには読み込まれません。

修正スニペットの例

pendo.initialize({
    visitor: {
        id:              'VISITOR-UNIQUE-ID'
    },
    account: {
        id:           'ACCOUNT-UNIQUE-ID'
    },
    disableGuides: true 
 });

ユーザーがこの設定を変更し、初期化後にコンソールでガイドを読み込むことは技術的に可能です。この作業を手動で行うには、Pendoとアプリケーションに関するかなりの技術的知識が必要です。このような状況では、ユーザーおよびアプリケーション固有のターゲット基準をすべて満たしたアプリ内の公開ガイドのみが読み込まれる可能性があります。

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

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

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

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

初期化関数と識別関数の詳細については、こちらをご覧ください。

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

インストールのスニペットは、Pendoのエージェントコードが含まれているpendo.jsをプルします。pendo.jsをPendoのCDNからプルしたくない場合は、アプリケーションでダウンロードしてホストすることができます。

エージェントのホスティング方法については、「Pendo Agentのセルフホスト（Self-hosting the Pendo Agent）」を参照してください。

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

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

トラブルシューティング

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

スニペットにアプリケーションキーが含まれていることを確認してください。［インストール設定（Install Settings）］ページからスニペットをコピーした場合、アプリケーションキーはすでに含まれています。他の場所からスニペットをコピーした場合は、アプリケーションキーがスニペットに含まれていることを確認してください。

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を使用することはできますが、機能は大幅に低下します。

スニペットの訪問者またはアカウントIDパラメータのどちらかが問題を引き起こしている可能性があります。データが渡されていないか、データの構造が間違っています。

コードテンプレート

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
  // 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',
  monthly_value:'99.99',
  is_paying:true,
  planLevel:995,
  isFoo:false}

オートタグ（Auto-Tag）がPendoフィードバックに表示されないのはなぜですか？

フィードバックは、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
}