インストールスクリプトを使用したPendoの実装に関する開発者ガイド

この記事は開発者向けです。Pendoのインストールと設定に関する技術的な手順をまとめています。

• IDとメタデータの選択からユーザーの追加、Pendoの使用開始までの、Pendoの実装についての全体的な手順に関するガイダンスについては、Pendoのアプリへの直接実装を計画するを参照してください。
• インストールスクリプトのコンポーネントの概要と、その動作についての技術概要については、インストールスクリプトのコンポーネントを参照してください。

インストールスクリプトによるインストールと設定は、Pendoをアプリケーションに統合するうえで唯一技術的な側面が必要な作業です。他のエンジニアリングリソースは不要です。セットアップが完了すると、エージェントがアプリケーションのユーザーにPendoを提供します。PendoエージェントとAPI開発者に関するドキュメントは、Engage APIを参照してください。

データ要件

Pendoを効果的に動作させるには、情報を特定の形式で提供する必要があります。このセクションでは、インストールスクリプトを使用してPendoをアプリに直接実装するために必要なデータをまとめています。

Feedbackもご利用の場合は、グローバルに一意の訪問者ID、メールのメタデータ、アカウントIDなど、Pendo Feedbackのデータニーズに合わせてコードを最適化することをお勧めします。Pendo Feedbackに必要なものについては、Feedbackの設定を参照してください。

一意の訪問者ID

Pendoが環境やプロダクトライン全体で個々のユーザーを追跡し、分析を追跡して正しくガイドを提供できるようにするには、グローバルに一意の訪問者IDが必要です。

訪問者IDの値は、サイズが128バイトに制限されています。これより大きい値は切り捨てられます。これらのIDについては、プロダクトチームとエンジニアリングチームの間でコンセンサスを得る必要があります。詳細については、IDとメタデータを選択するを参照してください。

カスタムメタデータの値用の構文

メタデータ値でサポートされている構文には、文字、数字、アンダースコア (_) が含まれます。

カスタムキーの値は文字またはアンダースコアで始める必要があります。開始文字が他のタイプの構文はサポートされていません。たとえば、「300」というキーがある場合、これを「_300」に変更する必要があります。この構文に従わないと、これらのカスタムフィールドを使用してセグメントを作成したり、レポートを実行したりすることができません。

カスタム言語メタデータ

Pendoのデフォルトの言語メタデータフィールドは、Pendoエージェントによって訪問者のブラウザ設定から収集されます。カスタムの訪問者メタデータは、エージェントまたはSalesforceなどとのインテグレーションを通じて受け渡すことができます。カスタム言語のメタデータフィールドでは、言語以外の名前を使用する必要があります。この名前は、ブラウザの言語メタデータ用であり、変更することはできません。

［設定］>［サブスクリプション設定（Subscription Settings）］>［ローカライズ設定（Localization Settings）］の順に移動すると、新たに別のメタデータフィールドを指定できます。

詳しくはこちら

Pendoをアプリに直接実装するには、アプリケーションからインストールスクリプトコードを実行してPendoエージェント（pendo.js）を呼び出す必要があります。これにより、アプリケーションでPendoを起動し、pendo.jsファイルのインストールスクリプトの初期化メソッドを実行して、Pendoエージェントを起動させることができます。アプリケーションでエージェントが実行されると、Pendoは分析を収集し、過去に保存されたデータに遡ってアクセスできるようになります。

Feedbackもご利用中のお客様の場合は、インストール中にPendoプロフェッショナルサービスがFeedbackを有効にします。サブスクリプションにFeedbackが表示されない場合は、Pendoサポートにお問い合わせください。すでにPendoをご利用のお客様が初めてFeedbackに切り替える場合は、Feedbackを新規にご利用になる方向けの手順として、 Feedbackの設定を参照してください。

まずは、お客様のサブスクリプションタイプに合わせてインストールスクリプトを調整する必要があります。Pendoでインストールスクリプトを見つけるには、次の操作を行います。

1. 左側のメニューの一番下から［設定（Settings）］>［サブスクリプション設定（Subscription Settings）］を選択します。
2. ［アプリケーション（Applications）］ タブを開き、［インストール設定（Install Settings）］を選択します。
3. インストールスクリプトコードをテキストエディタにコピーして、調整を行います。
4. プロセス概要で説明されているPendoのインストールと構成のステップを完了します。

何らかの問題が発生した場合は、Pendoのインストールに関するトラブルシューティングを参照してください。

プロセス概要

インストールスクリプトを使ったPendoの実装では、ウェブアプリケーションのフロントエンドにPendoのJavaScriptコードを挿入します。これは概ね次の3つのステップで行われます。

1. インストールスクリプトコードを編集して、訪問者とアカウントのメタデータを定義します。
   • インストールスニペットの訪問者オブジェクトとアカウントオブジェクト内のフィールド名を設定します。
   • アプリケーション内のメタデータとタグを使用して、インストールスクリプトの初期化メソッドを設定します。
2. 編集したインストールスクリプトコードをHTMLの共通領域にコピーしてPendoのインストールと初期化を実施します。これによりアプリケーションのすべてのページにPendoが自動的に追加されます。
3. インストールを確認します。これは、Pendo UIの［アプリの設定（App Settings）］ で、またはpendo.validateEnvironment()コマンド（［ブラウザ開発者コンソール（Browser Developer Console）］内）を使用して実施します。

 

注：インストールスクリプトは一般的に「スニペット」と呼ばれています。スニペットはPendoエージェントを参照するコードブロックであり、APIキーと初期化メソッドが含まれています。Pendoエージェントはpendo.jsファイルで、イベント収集、アプリ内ガイダンス、Feedbackモジュール（サブスクリプションによる）を提供します。コンポーネントの詳細については、インストールスクリプトのコンポーネントを参照してください。

ステップ1：訪問者ID、アカウントID、メタデータを定義する

このセクションでは、インストールスクリプトコードを調整してIDとメタデータを識別するプロセスと、それに関連して技術的に考慮すべき事項について説明します。定義する内容を決定するためのガイダンスについては、IDとメタデータを選択するを参照してください。

訪問者ID、アカウントID、およびメタデータはインストールスクリプトで定義されます。Pendoがガイドを提供したり、分析を収集したり、Feedbackモジュールを配信したりするために必要なコードブロックを含むインストールスクリプトのテンプレートは、サブスクリプションで提供されます。このテンプレートは、［設定］>［サブスクリプション設定］>［アプリケーション］>［インストール設定］にあります。

必要な操作は、そのコードの訪問者（プロダクトの一意のエンドユーザー）の値、アカウント（訪問者のグループ）の値、およびメタデータを調整することだけです。この情報は、アプリケーション内からPendoエージェントに送信されます。

Pendo Feedbackのお客様は、アプリからデータを取得してFeedbackの訪問者とアカウントにタグを自動的に追加する自動タグ付けを設定することもできます。Pendo Feedbackの使用開始後ではなく、今すぐ設定することをお勧めします。詳細については、Feedbackの設定を参照してください。

Feedbackをご利用のお客様は、特にメールのメタデータの使用とアカウントIDの必要性に関してさらに考慮が必要です。詳細については、Feedbackの設定を参照してください。

訪問者IDとアカウントID

訪問者IDとアカウントIDの両方をここで設定することを強くお勧めします。これらはIDとメタデータを選択するで説明しているガイドラインに基づいて定義する必要があります。以下に、IDの設定に関する重要な技術的考慮事項の一部を示します。

IDは変更できない

Pendoの実装後は、訪問者IDとアカウントIDは変更できません。実装後に訪問者IDとアカウントIDのマッピングが変更されると、Pendoにプロダクト使用履歴やガイド閲覧履歴のない新しい訪問者とアカウントのレコードが作成されるため、アナリティクスやセグメントに異常が発生し、ガイド体験が繰り返されます。

人間が判読できるIDである必要があります

訪問者IDとアカウントIDは、実装計画フェーズのIDとメタデータを選択するプロセスですでに定義されている必要があります。ガイドラインでは、訪問者のメールアドレスやアカウントの会社名など、認識可能なIDの必要性を強調しています。ランダムな文字列を使用した訪問者IDやアカウントIDは重複を避けることができますが、Pendoレポートの使用、セグメントの作成、他の技術スタックとの統合が難しくなります。また、訪問者IDやアカウントIDには\または"を使用しないでください。

全体で一意のIDである必要があります

訪問者IDはエンドユーザーごとに一意であり、アカウントIDはアカウントごとに一意である必要があります。訪問者IDとアカウントIDのいずれかが重複している場合、複数のソースからのデータが1つのIDに集約され、アナリティクスの精度が落ち、ガイドのターゲティングを効果的に行うことができなくなります。

訪問者IDは、カスタマージャーニー全体およびアプリケーション全体を通じて1人のエンドユーザーのみを表す必要があります。同じ訪問者IDを持つエンドユーザーが複数いるとIDの衝突を引き起こし、その1つのIDに対して複数のユーザーのアクティビティが追跡される可能性があります。これは、訪問者が同じPendoマルチアプリケーションサブスクリプションで異なるアプリまたはアプリのバージョンを使用している場合でも発生する可能性があります。

IDの衝突は、次のものに影響を与える可能性があります。

• メタデータ。Pendoは後入れ値に基づいてメタデータを記録します。メタデータは、最新のアクティビティを持つユーザーに基づいて更新されます。そのため、正確なメタデータに依存するセグメントに影響を与える可能性があります。
• 分析。衝突するIDで収集されたアクティビティを分離できないため、分析に一貫性がなくなります。
• ガイドの配信。ガイドが一度しか見られないように設計されている場合、同じ訪問者IDを持つ2人目のユーザーにはそのガイドが表示されません。

環境間で訪問者IDの衝突が生じるおそれがある場合は、プレフィックスやサフィックスを使って環境の識別子をIDに追加することができます。異なる環境で訪問者を識別する方法は、開発やテストのために複数の環境でPendoを使用するに記載されています。

IDの衝突の回避および対応方法については、Pendo Academyに掲載している動画をご視聴ください。

異なる環境で訪問者を識別することは、後でデータを除外するときに役立ちます。データの除外については、リストの基本情報：除外/包含リストを参照してください。

メタデータ

訪問者レベルやアカウントレベルでメタデータを指定することで、アナリティクスでのセグメント化やグループ化、ガイドのターゲティング、およびフィードバックデータのフィルタリングのオプションを強化できます。Pendoをインストールして設定する前に、取得したいメタデータを選択することをお勧めします。また、初回インストール後にメタデータを追加すると、Pendoの訪問者とアカウントの詳細が更新されます。

上記のコードブロックに示されている追加フィールドは、訪問者やアカウントについてお客様が送信できるメタデータの例です。その他の例については、IDとメタデータを選択するを参照してください。日付、整数、浮動小数点数、ブール値、リスト、文字列を送信できます。Pendoは、オブジェクトをサポートしていません。詳細については、データマッピングの記事を参照してください。

Feedbackをご利用のお客様は、自動タグ付けを設定することもできます。詳細については、Feedbackの設定とFeedbackにおける自動タグ付けを参照してください。

業界固有のメタデータフィールドなど、アプリケーションですでに使用可能な変数から任意の値を渡すことができます。メタデータルールの組み合わせを使用して、Pendoでセグメントを作成し、状況に応じたガイドをターゲットユーザーに配信することもできます。Pendoインストールワークブックが完成している場合は、チームがキャプチャする予定のフィールドを「基本的なインストール」で確認してください。

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

Pendoのメタデータの詳細については、訪問者とアカウントのメタデータとIDとメタデータを選択するを参照してください。

ステップ2：アプリケーションにPendoをインストールして初期化する

インストールスクリプトのテンプレートを調整してIDとメタデータを定義したら、編集したコードをアプリケーションコードにコピーします。

コードは、ガイドを提供したり、分析を収集したり、フィードバックを収集したりするすべてのページに存在する必要があります。そのため、HTMLの共通領域にコードを配置して、アプリのすべてのページに自動的に含まれるようにすることをお勧めします。これは通常、アプリケーションのすべてのページに置かれるHTMLテンプレートのHeadタグです。また、Pendoがフィードバックを適切に収集し、分析を追跡し、ガイドを提供できるように、コードがすべてのiframeに含まれていることを確認する必要があります。

ステップ 3：インストールの確認

コードがインストールされた場所とエンドユーザーが認証された場所で検証が実行されます （匿名訪問者が使用されている場合を除く）。インストールのステータスと、メタデータが特定の訪問者に対して設定されていることを確認するには、次の2つの方法があります。

• ［アプリの設定］でPendoのイベントの生データとデータマッピングを確認する。
• ブラウザ開発者コンソールでpendo.validateEnvironment()コマンドを使用する。

アプリ設定で確認する

1. ［設定（Settings）］>［サブスクリプション設定（Subscription Settings）］に移動します。
2. ［アプリケーション（Applications）」タブを開きます。
3. アプリがインストール済みであることを示す［アプリケーション］リストから該当するアプリを見つけて開きます。
4. ［イベントの生データ（Raw Events）］タブを選択すると、エージェントが収集したイベントの生データのリストが表示されます。
5. イベントを選択して、そのイベントによって収集されたコードとメタデータを表示します。イベントには以下が表示されます。
   • それを生成したユーザーの訪問者IDとアカウントID。
   • ブラウザのセッションメタデータ （追加のメタデータはイベントの生データには保存されません）。
   • ［設定（Setting）］＞［ データマッピング（Data Mappings）］に移動します。
   • Pendoに登録されているデータと、エージェントが送信したデータが一致しているかどうか確認します。

エージェントのメタデータフィールドが正しく入力されていない場合は、次回のPendoの初期化時にのみ更新されます。これらのフィールドは、手動で変更することはできません。これらを変更するには、インストールスクリプトを修正するか、update visitor関数を渡す必要があります。

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

ブラウザ開発者コンソールをを確認する

Pendoのインストールを確認する段階的な手順については、Pendo Academyに掲載している動画をご視聴ください。

Chromeブラウザ（推奨）でアプリケーションを開き、アプリにサインインします。

1. ページを右クリックして［検証（Inspect）］を選択し、ブラウザの開発者コンソールを開きます。
2. ［コンソール（Console）］タブを選択します。
3. コンソールにpendo.validateEnvironment()と入力します。
4. キーボードのEnterキーを押すと、スニペットで指定した値であるメタデータが返されます。
5. 訪問者とアカウントのメタデータが正確であることを確認します。

この情報によって、Pendoへのデータのマッピングが正常に成功したかどうかがわかります。

［Pendoが定義されていません（Pendo is not defined）］というエラーが表示された場合は、スニペットがコードに正しく含まれていないか、実行されていません。

Pendoのパフォーマンス

PendoのJavascriptファイルは、AmazonのCloudfront CDNでホストされ、最先端のエッジキャッシングを利用して提供されています。Javascriptファイルは約100KBに縮小、圧縮され、非同期で読み込まれます。

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

その他の構成

すでにPendoをご利用のお客様で、Pendo Feedbackをプロダクトに追加する場合は、Feedbackを新規にご利用になる方向けの手順を説明しているFeedbackの設定を参照してください。

その他の開発オプションもあります。イベントのタグ付けと追跡のためのカスタムHTML属性を追加することで、Pendoを最適化できます。詳しくは、カスタムHTML属性およびトラックイベントを参照してください。

他の一般的なCRM、アナリティクス、およびコラボレーションツールとのインテグレーションを追加して、Pendoを拡張することもできます。範囲は、コード不要のインストールウィザードによるネイティブインテグレーションからカスタム開発まで多岐にわたります。詳しくは、インテグレーションの記事をご覧ください。Pendoのインストールが完了した後のサブスクリプションのインテグレーション機能については、Pendoの担当者にお問い合わせください。

シナリオによっては、インストールのサポートが必要な場合があります。Pendoの担当者が、お客様の不安を解消し、導入のお手伝いをいたします。

以下の条件に当てはまる方は、導入の際に直接サポートが必要になる場合があります。

• 標準的でないウェブスニペットのインストール
• セキュリティへの懸念がある
• カスタムインテグレーション
• Segment.io、またはGoogle Tag Managerインストール
• APIインテグレーションまたはWebhook

よくある質問

インストールスクリプト（「スニペット」）はどこにインストールすればよいですか？

あらゆる場所です。Pendoはすべてのページにインストールする必要があります。アプリでiframeを使用している場合は、各iframe内にインストールします。

未知のユーザーとは誰ですか？

未知のユーザーや匿名のユーザーとは、アプリにサインインしていないユーザーのことです。［サブスクリプション設定］で未知のユーザーに対する分析を有効にして、ガイドの閲覧を許可できます。

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

Pendoでは、除外/包含リストを使用し、サーバーもしくはホストドメイン、IPアドレス、訪問者ID、アカウントIDに基づいてデータを非表示にできます。詳細については、除外/包含リストを参照してください。

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

インストールスクリプトは、Pendoのエージェントコードが含まれているpendo.jsをを取り込みます。pendo.jsをPendoのCDNから取得したくない場合は、アプリケーションでダウンロードしてホストできます。エージェントのホスティング方法については、Pendoエージェントのセルフホスティングを参照してください。

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

Pendoエージェントは、ローカルにホストして、オンプレミスのアプリケーションに含めることができます。Pendoは現在、ホストおよびデータ処理をクラウドでのみ行っています。そのため、インターネットへの接続が必要となり、お客様のネットワークからPendoのサーバーへのトラフィックを許可しなければならない場合があります。概して、ガイドはインバウンドのトラフィックであり、分析はアウトバウンドです。詳細については、制限されたネットワーク環境での訪問者のホスト名リストおよび制限されたネットワーク環境でのPendoサブスクリプションのホスト名リストを参照してください。