Web 埋め込み可能グローバルコードとコンポーネントコードで利用可能な関数

リリースバージョン: Australia

更新日 2026年03月12日

所要時間：6分

ServiceNow Embeddables API を使用すると、 ServiceNow コンポーネントを外部 Web サイトに統合できます。これらの関数は、初期化、認証、コンポーネント管理、およびイベント処理に不可欠な機能を提供します。

グローバルコード

埋め込みスクリプトには、グローバルコードの一部として次のメソッドが含まれています。次の詳細は、それらがどのように機能するかを理解するのに役立ちます。

Init メソッド

目的: 構成設定を使用して埋め込み可能フレームワークを初期化します。

使用パターン:

await init({
	theme: 'fad87d2ca304121029a4d1aed31e610f', //sys_id of theme,
	baseURL: 'https://demo.servicenow.com',
	authCallback: getTokenCallBack, // Authentication callback function 
       locale: 'ja', // Language/locale for components
       interceptSessionTimeout: true, // Handle session timeouts (default: true)
	// cacheComponents: [ //Pre-cache component for performance  "sn-embedx-case-form", "sn-embedx-case-list", "sn-embedx-case-view" ]
});

パラメーター：
- authCallback (関数):現在のユーザーの認証トークンを返します。
- baseURL (文字列): ServiceNow インスタンスのベース URL。
- locale (文字列、オプション):認証されたユーザーの言語設定を ServiceNow で更新する言語/ロケール設定 (「en」、「es」など)。
- theme (文字列):適用するテーマのsys_id。
- interceptSessionTimeout (ブール値、オプション):セッションタイムアウト処理を有効にします。デフォルトでは true に設定されています。
- cacheComponents (Array、オプション):事前キャッシュするコンポーネントタグ名のリスト。
主な動作:
- 他の埋め込み可能関数の前に呼び出す必要があります。
- 必要なリソースをロードし、接続を確立します。
- オプションでセッション管理用のインターセプターを設定します。
- ロケールが指定されている場合、認証されたユーザーの言語設定を更新します。
- パフォーマンスを向上させるために、指定されたコンポーネントを事前にキャッシュします。

ログイン()

目的: ServiceNow インスタンスでユーザーを認証します。
使用パターン:
```
await login();
```
主な動作:
- 初期化中に指定された authCallback 関数を呼び出します。
- 返されたトークンで認証:成功時に SN_EMBEDDABLES_LOGIN_SUCCESS イベントをディスパッチします。
前提条件:init () は、最初に有効な authCallback で呼び出す必要があります - authCallback 関数は有効な認証トークンを返す必要があります。

ログアウト()

目的:ユーザーをセッションからログアウト ServiceNow 。
使用パターン:
```
await logout();
```
主な動作:成功時にイベントをディスパッチ SN_EMBEDDABLES_LOGOUT_SUCCESS 。
前提条件:最初に有効な baseURL を使用して init() を呼び出す必要があります - ユーザーがログインしている必要があります。

コンポーネントコード

埋め込みスクリプトには、コンポーネントコードの一部として次のメソッドが含まれています。次の詳細は、それらがどのように機能するかを理解するのに役立ちます。

getEmbeddables

目的: 指定された埋込み可能なコンポーネントをロードして初期化します。

使用パターン:

// Load components by providing array of component tag names
getEmbeddables(["sn-embedx-case-view", "sn-embedx-case-form"]);

パラメーター: components (Array):ロードするコンポーネントタグ名のアレイ

setProperties(componentElement, properties)

目的:埋め込み可能なコンポーネントインスタンスのプロパティを設定します。

使用パターン:

const caseViewComponent = document.querySelector('sn-embedx-case-view');
setProperties(snEmbedxCaseView,{
		table:sn_customerservice_case,
		sysId:221a69cd3b411300b5c42479b3efc480,
		playbookExperience:playbookExperience,
		selectedPlaybookContextId:85d9f349ff766210e9d3ffffffffffce,
		selectedStageContextId:9da56770ff7a2210e9d3ffffffffffd9,
		selectedActivityContextId:5d8bf1805d8bf8205d8b54d05d8be070 });

パラメーター: componentElm (HTMLElement): コンポーネントの DOM 要素 - properties (Object): 設定するプロパティのキーと値のペア。

setEvents (componentElement、eventHandlers)

目的: イベントリスナーを埋込み可能なコンポーネントにアタッチします。

使用パターン:

const caseViewComponent = document.querySelector('sn-embedx-case-view');
const eventHandlers = {'
'SN_EMBEDX_CASE_VIEW#COMPONENT_READY': (e) => { 
console.log('Component is ready and usable'); }, 
'SN_EMBEDX_CASE_VIEW#COMPONENT_ERROR': (e) => { const 
{ errorMessage, errorType } = e.detail.payload;
console.log('Component error:', errorMessage, errorType); },
};
setEvents(caseViewComponent, eventHandlers);

パラメーター: componentElm (HTML 要素): コンポーネント DOM 要素 - eventHandlers (オブジェクト): キーと値のペア。キーはイベント名で、値はハンドラー関数です。

主な考慮事項

これを効果的に実装するための重要な考慮事項を次に示します。

最初に init() を呼び出すようにしてください。他のすべての機能の基礎を設定します。
コンポーネントライフサイクルのイベントハンドラーを使用します。また、コンポーネントの準備状況とエラーも監視します。
頻繁に使用するコンポーネントをキャッシュします。パフォーマンスを向上させるには、init() で cacheComponents を使用します。
実装