サイト設定

目的

暗号化 URL、スクリプト、ブラウザーエミュレーション、プロキシ、リクエスト/レスポンスヘッダーの記録、ページ制御、アクセス動作など、サイトの高度な設定を管理します。

前提条件

• 対象サイトが作成済みであること。
• スクリプトを公開する前に、サイトでテストしておくこと。

手順

1. 「サイト管理 > サイト一覧」に移動します。
2. 対象サイトを見つけ、「設定」をクリックします。
3. 必要に応じて暗号化 URL を有効にし、ユーザー画面に元サイトのアドレスが直接表示されないようにします。
4. ブラウザーエミュレーション、プロキシ、リクエストヘッダー、レスポンスヘッダー、ページ制御、スクリプトを設定します。
5. サイト設定を保存します。
6. テストアカウントで対象サイトにアクセスし、表示、ログイン、遷移、API データ、SSE イベント処理が期待どおりか確認します。
7. アカウント分類ごとに動作をカスタマイズする場合は、サイト一覧に戻り、「アカウント分類設定」を開きます。

設定項目

項目	用途	注意事項
暗号化 URL	ユーザー画面に表示される元サイトのアドレスを隠す	対象サイト自体の認証を代替するものではありません
ブラウザーエミュレーション	ブラウザーブランド、モバイル端末モデル、タイムゾーンなどの識別情報を調整する	変更後は対象サイトの互換性を再確認してください
プロキシ設定	このサイトに対して直接接続、システムプロキシ、PAC、固定プロキシサーバーを設定する	プロキシ設定の誤りによりサイトが開けない、またはログイン異常が発生することがあります
リクエストヘッダー	指定したリクエストヘッダーを記録し、ページスクリプトが api.header(name, true) で読み取れるようにする	設定済みで、実際にリモートブラウザーを通過したヘッダーのみ記録されます
レスポンスヘッダー	指定したレスポンスヘッダーを記録し、ページスクリプトが api.header(name, false) で読み取れるようにする	読み取り時、ヘッダー名は小文字に変換されます
ページスクリプト	DOM、フォーム、ボタン、ページ遷移、ページ拡張を処理する	誤動作を避けるため、マッチ URL を限定してください
SSE スクリプト	Server-Sent Events のストリームデータを書き換える	高度な用途向けです。先にテストすることを推奨します
通常 API インターセプトスクリプト	非 SSE API のレスポンス body を書き換える	スクリプトは新しいレスポンス body 文字列を返す必要があります
ページ制御	URL とセレクターに基づいてページ要素を非表示または削除する	対象サイトの改修後、セレクターが失効する可能性があります
アカウント分類設定	アカウント分類ごとに異なるログインロジックを設定する	サイトのブラウザーアカウントと組み合わせて使用します

スクリプト設定

サイト設定ページの「スクリプト設定」では、対象サイト向けのスクリプトルールを追加できます。各スクリプトは、マッチ URL とスクリプト種別に従って、リモートブラウザーが対象サイトへアクセスしたときに実行されます。

フィールド	型	説明
name	string	スクリプト名。crm-login-v1 のように「サイト-用途-バージョン」形式を推奨します。
url	string	マッチ URL。空の場合は通常 * と解釈されます。本番環境ではできるだけ正確に指定してください。
pageScript	boolean	ページスクリプトかどうか。有効にするとページ環境で実行され、window.api を使用できます。
sseScript	boolean	SSE インターセプトスクリプトかどうか。pageScript = false の場合のみ表示され、有効になります。
selector	string	ページスクリプトの実行条件。入力すると、その CSS または XPath セレクターに一致する要素がある場合のみ実行されます。
content	string	JavaScript スクリプト内容。スクリプト種別により引数と戻り値が異なります。

ページスクリプト

pageScript = true の場合、スクリプトはページスクリプトとして実行されます。DOM、フォーム、ボタンクリック、ページ遷移、オーバーレイ、ユーザーデータの読み書き、ページ拡張に適しています。

実行動作:

1. リモートブラウザーが対象ページにアクセスします。
2. システムがページとアクセス可能な iframe に window.api を初期化します。
3. selector が設定されている場合、セレクターが要素に一致したときだけスクリプトを実行します。
4. スクリプトは api.config、api.user、api.dom、api.utils、api.header() を直接使用できます。完全な API はスクリプト API 付録を参照してください。

例: 要素の出現を待ち、広告領域を非表示にして、製品設定を読み取ります。

await api.utils.wait(
  () => !!api.dom.querySelector(document, '.main-panel'),
  10000,
  200
);

const envName = api.config.envName || 'default';
console.log('current env:', envName);

const banner = api.dom.querySelector(document, '.ad-banner');
if (banner) {
  banner.style.display = 'none';
}

SSE スクリプト

pageScript = false かつ sseScript = true の場合、スクリプトは Server-Sent Events データのインターセプトに使用されます。システムはページ内の EventSource と fetch をラップし、URL が一致し、コンテンツタイプが text/event-stream のデータストリームを処理します。

実行形式:

async (data) => {
  // content に入力したスクリプト内容
}

引数	型	説明
data	string	現在の SSE message またはストリーミング chunk テキスト。

戻り値は新しい SSE テキストである必要があります。文字列を返さない場合、ページが受け取るデータが異常になることがあります。

例: SSE データ内のテキストを置換します。

return data.replace('old text', 'new text');

通常 API インターセプトスクリプト

pageScript = false かつ sseScript = false の場合、スクリプトは通常 API レスポンスのインターセプトに使用されます。システムは API URL をマッチし、レスポンス body を読み取り、スクリプトに渡して書き換えます。

実行形式:

async (data, api, url) => {
  // content に入力したスクリプト内容
}

引数	型	説明
data	string	元のレスポンス body。
api	object	スクリプト API。詳細はスクリプト API 付録を参照してください。
url	string	現在インターセプトされている API URL。

戻り値は新しいレスポンス body 文字列である必要があります。

例: JSON API レスポンスを書き換えます。

const obj = JSON.parse(data);
obj.debug = true;
obj.fromScript = url.includes('/api/');
return JSON.stringify(obj);

マッチ URL ルール

url フィールドは次のルールをサポートします。

書式	説明	例
*	すべての URL に一致	*
regex:<式>	正規表現で URL に一致	regex:/api/chat
exact:<完全なURL>	完全な URL に厳密一致	exact:https://example.com/api/user
script:<式>	現在の URL を変数 url として式を実行	script:url.includes('/api/')
通常文字列	対象 URL がこの文字列で始まるか判定	https://example.com/api/

本番用スクリプトでは、無関係なページや API への影響を減らすため、できるだけ正確なパスまたは安定したプレフィックスを使用してください。

リクエストヘッダーとレスポンスヘッダー

サイト設定のリクエストヘッダーとレスポンスヘッダーは、指定した header を記録するために使用されます。ページスクリプトは api.header() で読み取れます。完全なパラメーターはスクリプト API 付録を参照してください。

使用手順:

1. 「リクエストヘッダー」に記録したいリクエストヘッダー名を追加します。例: authorization、cookie。
2. 「レスポンスヘッダー」に記録したいレスポンスヘッダー名を追加します。例: content-type、set-cookie。
3. 設定を保存し、リモートブラウザーで対象サイトにアクセスします。
4. ページスクリプトで読み取ります。

const authorization = await api.header('authorization', true);
const contentType = await api.header('content-type', false);

注意:

• Header 名は読み取り時に小文字へ変換されます。
• 設定済みで、実際にリモートブラウザーを通過した header のみ読み取れます。
• レスポンスヘッダーは文字列配列の場合があります。スクリプトは配列と空値に対応してください。

セレクター構文

スクリプトセレクターとページ制御セレクターは CSS と XPath をサポートします。

書式	説明
.button.primary	CSS セレクター。
xpath://div[@id="app"]	XPath セレクター。
.dialog:p	一致した要素の親要素を返します。
.dialog:p2	一致した要素の 2 階層上の親要素を返します。
.header:bottom	オーバーレイ境界メソッドで対象要素の下端を使用します。
.sidebar:right	オーバーレイ境界メソッドで対象要素の右端を使用します。

設定変更プロセス

1. 現在の設定とスクリプト内容を記録します。
2. テストサイトまたはテストアカウントで変更します。
3. 表示、ログイン、遷移、ログアウト、API レスポンス、SSE イベントを確認します。
4. ページ制御ルールが正しい要素を非表示または削除しているか確認します。
5. 設定を本番サイトへ同期します。
6. 関連ユーザーにサイトへ再入場して確認してもらいます。

結果確認

• ユーザー画面のサイトカードが設定どおりに表示される。
• 暗号化 URL を有効にすると、ユーザー画面に元サイト URL が直接表示されない。
• リモートブラウザーが対象サイトへアクセスすると、カスタムスクリプトがマッチルールに従って有効になる。
• ページスクリプトが設定を正しく読み取り、要素を特定し、ページ動作を処理できる。
• SSE スクリプトは対象イベントストリームのみを書き換え、通常 API に影響しない。
• 通常 API インターセプトスクリプトが有効なレスポンス body を返す。
• 対象サイトの改修後も、スクリプトとセレクターが正常に一致する。

よくある質問

• スクリプトは本番サイトで使用する前に、テストサイトで検証してください。
• 暗号化 URL はフロントエンド表示とアクセス経路にのみ影響し、対象サイト自体のセキュリティポリシーを回避するものではありません。
• ページスクリプトは DOM、フォーム、ページ動作の処理に適しています。
• SSE スクリプトは Server-Sent Events ストリーム専用であり、通常の JSON API 処理には使わないでください。
• 通常 API インターセプトスクリプトは文字列を返す必要があります。そうしないと対象ページがレスポンスを解析できないことがあります。
• 使用可能なスクリプト API の完全なパラメーターと例はスクリプト API 付録を参照してください。
• アカウント分類設定は、同じサイトの異なるログイン方式に対して差分動作を定義する場合に適しています。