Googleスプレッドシートでの、訪問者レポートとアカウントレポートのエクスポートおよび自動化

最終更新日: 2024年04月09日 01:17

この記事では、Pendoの訪問者レポートおよびアカウントレポートのコンテンツを、APIを使ってGoogleスプレッドシートに抽出する自動プロセスを設定する方法について説明します。これにより、Pendoへのアクセス権のない他のユーザーやチームメンバーにも、プロダクトの使用に関するデータを簡単に共有できるようになります。

注意：この記事で紹介されている方法を参考にして、APIコールをカスタマイズし、Googleスプレッドシートで詳細なレポートを作成することは可能ですが、これはカスタムコードに該当するため、Pendoのテクニカルサポートの対象外となります。対象外のサポートが必要な場合は、まずPendoのアカウント担当者がその評価を実施し、そのうえで可能性としては、Pendoのプロフェッショナルサービスチームが有償で対応することになります。

要件

以下のガイドラインに進む前に、次のことを確認してください。

APIアクセスがPendoの契約に含まれていること。ご不明な点があれば、Pendoのアカウント担当者までお問い合わせください。
インテグレーションキーを保有していること。これはPendoスニペットに表示されるキーではありません。また、管理者のみがインテグレーションキーを作成できます。Pendo Engageでインテグレーションキーを作成するには、［設定（Settings）］>［インテグレーション（Integrations）］>［インテグレーションキー（Integration Keys）］に移動し、［インテグレーションキーを追加（Add Integration Key）］を選択します。
GoogleスプレッドシートとGoogle Apps Scriptの拡張機能へのアクセス権があること。

Googleスクリプトの作成

以下の手順に従って、訪問者またはアカウントレポートの内容をGoogleスプレッドシートに直接抽出します。

新しいGoogleスプレッドシートを作成します。
上部メニューバーから［Extensions（拡張機能）］を選択して、新しいタブで［Apps Script］開きます。

新しいタブでは、デフォルトでCode.gsファイルが表示されます。Googleがデフォルトで追加している空の関数を含め、すでにあるコンテンツをすべて削除し、次のテキストに置き換えます。

/**
* SHEET_NAME : シート上の全てのデータを置換するスプレッドシートの名前。
* REPORT_ID : 抽出するPendoの訪問者レポートまたはアカウントレポートのID。
* INTEGRATION_KEY : PIから取得しヘッダーとして渡す、x-pendo-integration-key。
* SPREADSHEET_ID : データのエクスポート先となる、「SHEET_NAME」という名前のシートのID。
* BASE_URL : USインスタンス（app.pendo.io）でPendoにアクセスしている場合は、デフォルトですでに正しい値が入力されているため、アクションは一切必要ありません。PendoサブスクリプションがEUインスタンスにある場合は、BASE_URLの値を「app.eu.pendo.io」に変更します。PendoサブスクリプションがUS1インスタンスにある場合は、BASE_URLの値を「app.us1.pendo.io」に変更します。お客様のPendoサブスクリプションがJPNインスタンスにある場合は、BASE_URLの値を「app.jpn.pendo.io」に変更します。
*/
const SHEET_NAME = "YOUR-SHEET-NAME";
const REPORT_ID = "YOUR-PENDO-REPORT-ID";
const INTEGRATION_KEY = "YOUR-INTEGRATION-KEY";
const SPREADSHEET_ID = "YOUR-SPREADSHEET-ID";
const BASE_URL = "app.pendo.io";



/**
* Pendo APIのreportsエンドポイントにAPIリクエストを行い、CSVファイルを取得します。
* CSVのデータは前処理済みで、クリーニングおよび構造化され、シートでの置き換え用に渡されます。
* API呼び出しでコードが破損するエラーが発生した場合、そのエラーは調査のためにLoggerに記録されます。
* エンドポイントへのリクエストが何らかの問題で失敗した場合、そのエラーは応答エラーコードとともにLoggerに記録されます。
*/
function getReport() {
// オペレーション中の中間データを保存するためのローカル変数です。
let params, endpoint, response, responseCode, responseObjects, dataToBeReplaced, headers, rowEntries, lineContent;
// API呼び出しに必要なパラメータ定義です。
params = {
"headers": {
'x-pendo-integration-key': INTEGRATION_KEY,
'content-type': "application/json"
}
}


try {
// Pendo APIからレポートの内容を取得するためのエンドポイントURLです（REPORT_IDで特定します）。

endpoint = `https://${BASE_URL}/api/v1/report/${REPORT_ID}/results.json`;

// 必要なパラメータでAPIエンドポイントにリクエストを行い、レスポンスオブジェクトを保存します。

response = UrlFetchApp.fetch(endpoint, params);
// 最新の呼び出しからレスポンスコードを取得します。
responseCode = response.getResponseCode();
// レスポンスコードが200なら成功です。
if (responseCode == 200) {
// レスポンスの内容をjsonオブジェクトとして取得します。
responseObjects = JSON.parse(response.getContentText());
// 後でシートの最初の行を置き換える必要のあるヘッダーを取得します。
headers = Object.keys(responseObjects[0]);
// 置き換え配列（2D配列）の先頭にヘッダーを追加します。
dataToBeReplaced = [headers].


// レスポンスオブジェクト配列のすべてのオブジェクトで繰り返します。
responseObjects.forEach(function (object) {
// 1D array that holds intermediate operations results for current object
rowEntries = [];
// Iterate through all column values for current object
headers.forEach((header) => rowEntries.push(object[header]));
// add current row (object) details to the replacement array
dataToBeReplaced.push(rowEntries)
});


// データが抽出され、必要なフォーマットになったら、指定したシートで置き換えを実施します。
replaceSheetData_(dataToBeReplaced);
}
// それ以外の場合は、発生したエラーをユーザーにプロンプト表示します。
else {
Logger.log(`Something isn't right, call to endpoint failed. Status Code: ${responseCode}`)
}


// エラーが発生した場合は、Logger にログインしてユーザーにエラーを通知します。
} catch (error) { `Something went wrong in the API call and data extraction. Error: ${error}` }
}


/**
* @params {dataToBeReplaced} : Pendo Reportsエンドポイントから取得した構造化/クリーニング済みのデータの2D配列。
* 何か問題が発生し、プロセスが静かに終了した場合は、スプレッドシートおよび指定したシートへのハンドルを開きます。
* Loggerのメッセージです（エラーをさらに調査するために使用します）。
*
* 指定したシートのデータを、APIリクエストで取得したデータに置き換えます。
*/
function replaceSheetData_(dataToBeReplaced) {
let workbook, worksheet;


// スプレッドシートへのハンドルを開きます。これが見つからない場合は、親切なメッセージとともにこのプロセスを終了します。
workbook = SpreadsheetApp.openById(SPREADSHEET_ID)
if (!workbook) {
Logger.log("Workbook not found, the ID may not be correct");
return;
}


// シート名を使って指定したシートへのハンドルを開きます。これが見つからない場合は、親切なメッセージとともにこのプロセスを終了します。
worksheet = workbook.getSheetByName(SHEET_NAME);
if (!worksheet) {
Logger.log(`Sheet named ${SHEET_NAME} not found. Please double check the sheet name`);
return;
}


// その時点でシートに保存されている内容をすべて消去します（指定したシートの全データを消去します）。
worksheet.getDataRange().clear();
// API Responseから取得した新しいレポートデータを現在のシートに書き込みます。
worksheet.getRange(1, 1, dataToBeReplaced.length, dataToBeReplaced[0].length).setValues(dataToBeReplaced);
}

8行目から12行目にある定数を更新すると、さまざまなシート、スプレッドシート、レポート、アプリでスクリプトを使用できるようになります。

- const SHEET_NAME ="YOUR-SHEET-NAME"で、YOUR-SHEET-NAMEの部分をシートタブの名前に置き換えます。
- const REPORT_ID = "YOUR-PENDO-REPORT-ID"で、YOUR-PENDO-REPORT-IDの部分を抽出するレポートのIDに置き換えます。この値を取得するには、Pendoのレポートに移動し、次のURLの末尾にあるIDをコピーします。https://app.pendo.io/s/SUBSCRIPTION-ID/visitorlist/レポートのID
- const INTEGRATION_KEY = "YOUR-INTEGRATION-KEY"にで、YOUR-INTEGRATION-KEYの部分を、サポートされているインテグレーションキーに置き換えます。Pendoのインテグレーションキーで説明しているとおり、インテグレーションキーはPendoの管理者しか作成できません。Pendoからのデータ抽出については、閲覧者のアクセス権があれば実施できます。
- const SPREADSHEET_ID = "YOUR-SPREADSHEET-ID"で、YOUR-SPREADSHEET-IDの部分をスプレッドシートのIDに置き換えます。この値を取得するには、次のURLのIDをコピーします：https://docs.google.com/spreadsheets/d/スプレッドシートのID/edit#gid=0
- Const BASE_URL = "app.pendo.io"の場合、これがPendoへのアクセスに使用するURLであることを確認してください。
  - USインスタンス（app.pendo.io）経由でPendoにアクセスした場合、デフォルトですでに正しい値が入力されているため、アクションは一切必要ありません。
  - PendoサブスクリプションがEUインスタンスにある場合は、app.pendo.ioをapp.eu.pendo.ioに変更します。
  - PendoサブスクリプションがJPNインスタンスにある場合は、app.pendo.ioをapp.jpn.pendo.ioに変更します。
  - PendoサブスクリプションがUS1インスタンスにある場合は、app.pendo.ioをapp.us1.pendo.ioに変更します。
保存アイコンを選択し、［実行（Run）］を選択します。これにより、スクリプト内のデータへのGoogleアクセスを承認するためのダイアログが開きます。
［権限を確認（Review permissions）］を選択し、お使いのGoogleアカウントを選び、［許可（Allow）］を選択します。
Googleスプレッドシートがレポートの情報で更新され、Pendoのレポートと同じ内容が表示されていることを確認します。

Googleスプレッドシートのレポートには、ページまたはフィーチャーの名前ではなく、ページまたはフィーチャーのIDが表示されます。特定のページまたはフィーチャーのIDを見つけるには、Pendoのページまたはフィーチャーの詳細ページに移動し、URLを確認します。IDはURLの末尾にあります。

https://app.pendo.io/s/SUBSCRIPTION-ID/features/フィーチャーのID
https://app.pendo.io/s/SUBSCRIPTION-ID/visitorlist/ページのID

さらに、Pendoのレポートと比較すると列の順序が異なる場合がありますが、内容に変わりはありません。

ボタンを使用したレポート内容の更新

必要に応じて、スプレッドシートにボタンを追加すれば、そのボタンを選択するたびにコードが実行され、最新のレポートの内容でスプレッドシートが更新されるようになります。

Googleスプレッドシートで、［挿入］>［図形描画］の順に選択します。
図形を選択し、好みの形に整えてから、［保存して終了］を選択します。
スプレッドシートに図形を追加したら、その図形を右クリックして右上に表示される省略記号（3つの点）を選択し、［スクリプトを割り当て］を選びます。
getReport（コードに含まれる関数の名前）と入力し、［確定］を選択します。
ボタンを選択して、期待どおりにデータが更新されることを確認します。

スケジュールに沿ったレポート内容の更新

Pendoのレポート内容を定期的に抽出するように自動プロセスを設定することもできます。

Googleスプレッドシートで、［拡張機能］>［Apps Script］の順に選択します。
左のナビゲーションメニューから、［トリガー］（時計のアイコン）を選択します。
ページの右下にある［トリガーを追加］を選択します。
ニーズに合わせてトリガーを設定します。各フィールドの説明は以下のとおりです。
- 実行する機能を選択：これにより、前のセクションのステップ4でコードに追加されたgetReport関数が自動的に検出されます。この選択は変更しないでください。
- 実行するデプロイを選択：このオプションはデフォルトで［Head］が選択されています。この選択は変更しないでください。
- イベントのソースを選択：ドロップダウンメニューから［時間主導型］を選択します。これにより、次の2つのドロップダウンオプションが更新されます。
- 時間ベースのトリガーのタイプを選択：レポートを毎日更新したい場合は、［日付ベースのタイマー］を選択します。
- 時刻を選択：ニーズに最も適した時刻を選択します。ユーザーのタイムゾーンが自動的に検出されます。
- エラー通知設定：［今すぐ通知を受け取る］を選択することをお勧めしますが、選択肢は他にもあります。フィールド名の横にあるプラス（+）アイコンを選択すると、複数選択が可能になります。

［保存］を選択すると、スケジュールされた時刻にスクリプトを実行するトリガーが追加されます。

要件

Googleスクリプトの作成

ボタンを使用したレポート内容の更新

スケジュールに沿ったレポート内容の更新

このセクションの記事