Live ChatのトラッキングSDK People

PeopleトラッキングSDKは、People web SDK機能をLive Chatに統合します。これにより、Live Chat を使用して Web サイトでのユーザーアクティビティを追跡し、Live Chat セッション中に同じプロファイルを維持することで、統一された個人プロファイルを構築できます。

この SDK を使用すると、顧客についてより深い洞察が得られ、顧客のニーズをより深く理解できます。

主な用語

このドキュメントでは、次の用語が使用されています。

Live Chat ページ: Live Chat が統合されている Web サイト。
Live Chat ユーザー: Live Chat ページにアクセスするユーザー。
訪問者: チャットを開始していない、または認証されていない Live Chat ページの匿名訪問者。
ユーザー:チャットを開始した、または認証されたリードまたは認証済みユーザー。認証の詳細については、「ユーザーと認証」を参照してください。
ユーザーアクティビティ: ユーザーについて追跡されたイベントで、保存され、プロファイルに一覧表示されます。
個人プロフィール: 個人用に作成されたプロフィールで、表示できます。
訪問者プロファイル: 訪問者用に作成されたプロファイル。訪問者が人になるまでは閲覧できません。

People tracking SDK 機能

People tracking SDK を使用すると、次のことができます。

「セッション開始」、「セッション終了」、「ページビュー」などのユーザーのアクティビティイベントを追跡します。
定義したカスタムイベントを追跡します。
ユーザーのプロパティと属性を更新します。

「セッション開始」は、最初のユーザーアクティビティ(ページビューやカスタムイベントなど)が記録されたときにトリガーされます。セッションは、最後に記録されたユーザーアクティビティから 30 分後に期限切れになり、その時点で「セッション終了」イベントがトリガーされます。新しいセッションは、次に記録されたユーザーアクティビティから開始されます。

「ページビュー」イベントは、ユーザーが Live Chat ページを開いたときに SDK が初期化されたときにトリガーされます。詳細は People events を参照してください。

備考「セッション開始」イベントと「セッション終了」イベントは、ユーザーアクティビティセッションのみを追跡し、ユーザープロファイルに反映されます。これを Live Chat セッションと混同しないでください。

プロファイルの選択

ユーザーアクティビティの追跡に使用されるプロファイルは、Live Chat セッションに基づいて決定されます。Live Chat セッションは、ユーザーがチャットを開始するか認証したときに確立されます。

次の表は、さまざまな状況で選択されるプロファイルをまとめたものです。

状況	使用プロファイル
ユーザーがチャットを開始していない	来場者プロフィール
ユーザーがチャットを開始する	リードタイプの新しいユーザープロファイルが作成され、使用されます。訪問者フェーズで収集されたすべてのアクティビティは、リードプロファイルに自動的にマージされます。
ユーザーがチャットセッションを開始し、認証	対応する認証済みユーザープロファイルが使用されます。
ユーザーがチャットセッションを開始しておらず、認証されています	対応する認証済みユーザープロファイルが使用されます。訪問者フェーズで収集されたすべてのアクティビティは、この認証されたユーザープロファイルに自動的にマージされます。
Live Chat セッションが終了 (ログアウト、セッションの無効化、または有効期限)	新しい訪問者プロファイルが作成され、使用されます。

訪問者のライフサイクル

ユーザーが初めて Live Chat ページにアクセスすると、新しい訪問者プロファイル が作成されます。このプロファイルは、最後の訪問者アクティビティから 45 日間 アクティブのままです。プロファイルは、訪問者がチャットを開始するか認証するまで、ページに戻るたびに再利用されます。

45日以内にアクティビティ が発生しない場合、訪問者プロファイルは削除されます。新しいプロファイルは、次に追跡されるアクティビティ時に作成されます。

People 追跡 SDK の使用状況

まず、すべてのSDK関数へのアクセスを提供するSDKのインスタンス(SDKオブジェクトの取得)を作成します。

const sdk = new PeopleTrackingSDK();

提供する機能

SDKには、Live Chatのユーザープロファイルを構築および管理するための次の機能が含まれています。

init() [#init-provided-functions]

機能	`init()`
目的	SDK を初期化します。ユーザーアクティビティを追跡する前に必要です。
使用法	'sdk.init(apiKey:文字列);'
パラメータ	`apiKey` - 必要なスコープで作成されたAPIキー

例

sdk.init('725f7...55b9');

初期化後、新しい Live Chat ユーザー (存在しない場合) の訪問者プロファイルが作成され、ページビューイベントが追跡されます。既存の Live Chat セッションがある場合、対応するユーザープロファイルがアクティビティ追跡用に自動的に選択されます。

大事なAPIキーには、スコープweb:tracking:sdkが割り当てられている必要があります。APIキーは、常に単一のスコープweb:tracking:sdkのみで使用してください。これにより、最小特権の原則が適用され、悪用や不正アクセスのリスクが最小限に抑えられます。

トラック() [#track-provided-functions]

機能	'トラック()'
目的	カスタム定義のイベントを追跡します。Events は、追跡する前に定義する必要があります。詳細はカスタムイベントを参照してください。
使用法	`pe.track(eventId: string, properties?: object);`
パラメータ	`eventId` - カスタムイベント ID (definitionId) `properties` - イベント定義に一致するキーと値のペア。 • 指定する場合は、少なくとも 1 つのプロパティを含める必要があります。すべてのイベントプロパティを使用する必要はありません • 省略すると、イベントはプロパティなしで追跡されます

例

pe.track('action', { name: 'Button clicked', label: 'add-to-favorites' });

備考訪問者イベントは、訪問者がチャットの開始または認証によって個人になると、それぞれのユーザープロファイルに自動的にマージされます。

updatePerson() [#updateperson-provided-functions]

機能	`updatePerson()`
目的	ユーザープロファイルのプロパティを更新します。更新できるのは、タイプリードのプロファイルのみです。
使用法	`pe.updatePerson(personDto: object);`
パラメータ	`personDto` - 更新するpersonプロパティを含むオブジェクト。

例

javascript

1sdk.updatePerson({

2 address: 'Kirchmayer street 97',

3 birthDate: '1993-01-01',

4 city: 'Prague',

5 contactInformation: {

6 email: [{ address: 'email@infobip.com' }],

7 phone: [{ number: '421905123450' }]

8 },

9 country: 'Czech Republic',

10 customAttributes: { car: 'Mercedes' },

11 firstName: 'Semi',

12 gender: 'male',

13 lastName: 'Holsen',

14 middleName: 'Gabcik',

15 preferredLanguage: 'it-it',

16 profilePicture: 'https://profile.com',

17 tags: ['reading', 'technology']

18});

備考SDK を介して更新できるのは、例に示されているプロパティのみです。プロパティの説明については、「ユーザー API エンドポイントの更新」を参照してください。無効または認識されないプロパティ名は無視されます。

appendToList() [#appendtolist-provided-functions]

機能	`appendToList()`
目的	list 型のカスタム属性に新しい項目を追加します。リードタイプのプロファイルでのみ使用できます。カスタム属性の詳細については、属性を参照してください。
使用法	`sdk.appendToList(attributeName: string, value: object);`
パラメータ	`attributeName` - カスタムリスト属性の名前。 `value` - 追加するリスト項目オブジェクト。

例

javascript

pe.appendToList('category', { name: 'special' });

応答

各関数は、オブジェクトに解決される Promise を返します。キープロパティはsuccessで、操作の結果を示します。success が true の場合、警告などの追加の詳細が data プロパティに提供される場合があります。success が false の場合、追加の詳細が error プロパティに提供されます。

解決された Promise の例

json

2 "success": true,

3 "data": null

解決に失敗した Promise の例

json

2 "success": false,

3 "error": {

4 "code": 2015,

5 "name": "NotInitializedPeopleTrackingError",

6 "message": "People tracking SDK is not initialized. Call init() first",

7 "origin": "fe-snippet",

8 "platform": "fe-snippet"

9 }

10}

エラーのプロパティ

originプロパティはシステム内でエラーが発生した場所を指定し、platformプロパティはエラーが表面化した場所または報告された場所を示します。

エラーの解釈に役立つように、最も重要なプロパティは code、name、特にエラーの原因に関する詳細情報を提供する message です。

一般的な SDK エラー [#common-sdk-errors-error-properties]

次の表は、SDK の使用中に発生する可能性のあるエラーの一覧です。

コード	名前	メッセージ
4001	`InitRequiredError`	Live Chatが初期化されていない
2015年	`NotInitializedPeopleTrackingError`	People tracking SDK は初期化されません。最初に `init()` を呼び出す
2016年	`SdkTrackError`	`track()` を呼び出すときにエラーが発生しました。原因: `${reason}`
2017年	`PeopleUpdateError`	`updatePerson()` を呼び出すときにエラーが発生しました。原因: `${reason}`
2018年	`MissingAuthorizationTokenError`	認証トークンがありません。登録が存在することを確認します。
2019年	`AppendToListError`	`appendToList()` を呼び出すときにエラーが発生しました。原因: `${reason}`
2020年	`PersonStateError`	ユーザーの同期に失敗しました。原因: `${reason}`

備考${reason}プレースホルダーには、それぞれのエラーの具体的な原因が含まれています。