Helpshiftのデリゲート
Helpshift SDKでは、アプリの開発者がヘルプセクション内でのユーザーアクティビティを追跡できるようにデリゲートコールバックが提供されています。
SDKに含まれているすべてのパブリックAPIは、HelpshiftSdk.install() APIを介してSDKを初期化した後に呼び出す必要があります。
Helpshift.SetHelpshiftEventsListenerを設定する前に呼び出されたイベントをもう一度受信することはできません。
Helpshiftイベントリスナー/デリゲートの実装
HelpshiftSdk.GetInstance().SetHelpshiftEventsListener()メソッドを呼び出すことで、IHelpshiftEventsListenerの実装を設定することができます。
ステップ1: IHelpshiftEventsListenerインターフェースを実装する
public class HSEventsListener: IHelpshiftEventsListener
{
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
// all events
}
public void AuthenticationFailedForUser(HelpshiftAuthenticationFailureReason reason)
{
//auth failure event
}
}
ステップ2: Helpshift APIを呼び出し、この実装クラスを設定する
using Helpshift;
//...
//...
private HelpshiftSdk help;
//..
void Awake(){
// install call here
help = HelpshiftSdk.GetInstance();
}
void Start(){
// set the listener
help.SetHelpshiftEventsListener(new HSEventsListener());
}
イベント
Helpshiftセッションの開始イベント
このイベントは、Helpshiftセッションが開始したときに発生します
- イベントの名前:
HelpshiftEvent.SDK_SESSION_STARTED - イベントのデータ:
null
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if(eventName.Equals(HelpshiftEvent.SDK_SESSION_STARTED))
{
Debug.Log("Helpshift session started.");
}
}
//...
}
Helpshiftセッションの終了イベント
このイベントは、Helpshiftセッションが終了したときに発生します
- イベントの名前:
HelpshiftEvent.SDK_SESSION_ENDED - イベントのデータ:
null
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if(eventName.Equals(HelpshiftEvent.SDK_SESSION_ENDED))
{
Debug.Log("Helpshift session ended.");
}
}
//...
}
未読メッセージ数の計測イベント
このイベントは、未読メッセージの数をリクエストするためにHelpshift.RequestUnreadMessageCount(shouldFetchFromServer) APIを呼び出したときに発生します。
- イベントの名前:
HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT - イベントのデータ:
- イベントのデータ:
HelpshiftEvent.DATA_MESSAGE_COUNT- 型:
int
- 型:
HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE- 型:
boolean
- 型:
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if(eventName.Equals(HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT))
{
if(eventData.ContainsKey(HelpshiftEvent.DATA_MESSAGE_COUNT)) {
Debug.Log("Unread count: " + eventData[HelpshiftEvent.DATA_MESSAGE_COUNT]);
}
if(eventData.ContainsKey(HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE)) {
Debug.Log("Is Unread count from cache: " + eventData[HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE]);
}
}
}
//...
}
会話の状態イベント
このイベントには、現在進行中の会話に関する情報が含まれています。
- イベントの名前:
HelpshiftEvent.CONVERSATION_STATUS - イベントのデータ:
- イベントのデータ:
HelpshiftEvent.DATA_LATEST_ISSUE_ID- 型:
string
- 型:
HelpshiftEvent.DATA_LATEST_ISSUE_PUBLISH_ID- 型:
string
- 型:
HelpshiftEvent.DATA_IS_ISSUE_OPEN- 型:
boolean
- 型:
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if(eventName.Equals(HelpshiftEvent.CONVERSATION_STATUS))
{
if(eventData.ContainsKey(HelpshiftEvent.DATA_LATEST_ISSUE_ID)) {
Debug.Log("Issue ID : " + eventData[HelpshiftEvent.DATA_LATEST_ISSUE_ID]);
}
if(eventData.ContainsKey(HelpshiftEvent.DATA_LATEST_ISSUE_PUBLISH_ID)) {
Debug.Log("Publish ID : " + eventData[HelpshiftEvent.DATA_LATEST_ISSUE_PUBLISH_ID]);
}
if(eventData.ContainsKey(HelpshiftEvent.DATA_IS_ISSUE_OPEN)) {
Debug.Log("Is issue open : " + eventData[HelpshiftEvent.DATA_IS_ISSUE_OPEN]);
}
}
}
//...
}
ウィジェットの切り替えイベント
このイベントは、ユーザーがチャット画面を開いたり閉じたりしたときにトリガーされます。このイベントは、"visible"キーのブーリアン値を用いてトリガーされます。ご参考までに、以下の例をご確認ください:
- イベントの名前:
HelpshiftEvent.WIDGET_TOGGLE - イベントのデータ:
HelpshiftEvent.DATA_SDK_VISIBLE- 型:
boolean
- 型:
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if(eventName.Equals(HelpshiftEvent.WIDGET_TOGGLE))
{
if(eventData.ContainsKey(HelpshiftEvent.DATA_SDK_VISIBLE)) {
Debug.Log("Is SDK Visible " + eventData[HelpshiftEvent.DATA_SDK_VISIBLE]);
}
}
}
//...
}
ユーザーによるアクションのクリック時のイベント
このイベントは、ユーザーがアクションカードメッセージのリンクやアクションの呼び出しをクリックした時にトリガーされます。
- イベントの名前:
HelpshiftEvent.ACTION_CLICKED - イベントのデータ:
HelpshiftEvent.DATA_ACTIONHelpshiftEvent.DATA_ACTION_TYPEHelpshiftEvent.DATA_ACTION_TYPE_CALLHelpshiftEvent.DATA_ACTION_TYPE_LINK
| キー(定数) | キー(生) | データ型 |
|---|---|---|
| HelpshiftEvent.ACTION_CLICKED | userClickOnAction | string |
| HelpshiftEvent.DATA_ACTION | actionType | string |
| HelpshiftEvent.DATA_ACTION_TYPE | actionData | string |
| HelpshiftEvent.DATA_ACTION_TYPE_CALL | call | string |
| HelpshiftEvent.DATA_ACTION_TYPE_LINK | link | string |
キーの定数は、SDK X 10.3.0以降で利用可能です。古いバージョンのSDK Xでは、生のキーを代わりに使用してください。
public class HSEventsListener : IHelpshiftEventsListener
{
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if (eventName.Equals(HelpshiftEvent.ACTION_CLICKED))
{
// With Key Constants
string actionType = (string) eventData[HelpshiftEvent.DATA_ACTION_TYPE];
string actionData = (string) eventData[HelpshiftEvent.DATA_ACTION];
-------------------- OR --------------------
// With Key Raw Values
string actionType = (string) eventData["actionType"];
string actionData = (string) eventData["actionData"];
if (string.IsNullOrEmpty(actionType) || string.IsNullOrEmpty(actionData))
{
Debug.Log($"Event Received for ${eventName} with actionType or action Data as empty");
return;
}
Debug.Log($"Event Received for ${eventName}. Action type - ${actionType}. Action data - ${actionData}");
}
}
}
会話の開始イベント
このイベントは、ユーザーが会話の中で最初のメッセージを送信したときにトリガーされます。イベントのデータオブジェクトにはmessageキーが含まれており、これにはエンドユーザーが会話を始めるために送信したメッセージの文字列が含まれています。ご参考までに、以下の例をご確認ください。
- イベントの名前:
HelpshiftEvent.CONVERSATION_START - イベントのデータ:
HelpshiftEvent.DATA_MESSAGE- 型:
string
- 型:
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if (eventName.Equals(HelpshiftEvent.CONVERSATION_START))
{
if(eventData.ContainsKey(HelpshiftEvent.DATA_MESSAGE)) {
Debug.Log("Conversation started with text: " + eventData[HelpshiftEvent.DATA_MESSAGE]);
}
}
}
//...
}
メッセージの追加イベント
このイベントは、ユーザーが会話内でメッセージを追加したときにトリガーされます。追加されるメッセージには、テキストメッセージ、ボットの入力を介した応答、添付ファイルなどが想定されています。イベントのデータオブジェクトにはtypeキーとbodyキーが含まれており、これらはユーザーが追加したメッセージの種類と本文を示しています。ご参考までに、以下の例をご確認ください。
- イベントの名前:
HelpshiftEvent.MESSAGE_ADD - イベントのデータ:
HelpshiftEvent.DATA_MESSAGE_TYPE- 値:
HelpshiftEvent.DATA_MESSAGE_TYPE_ATTACHMENT,HelpshiftEvent.DATA_MESSAGE_TYPE_TEXT
- 値:
HelpshiftEvent.DATA_MESSAGE_BODY- 型:
string
- 型:
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if (eventName.Equals(HelpshiftEvent.MESSAGE_ADD))
{
if(eventData.ContainsKey(HelpshiftEvent.DATA_MESSAGE_BODY)) {
Debug.Log("New message added with body: " + eventData[HelpshiftEvent.DATA_MESSAGE_BODY]);
}
if(eventData.ContainsKey(HelpshiftEvent.DATA_MESSAGE_TYPE)) {
Debug.Log("New message added with type: " + eventData[HelpshiftEvent.DATA_MESSAGE_TYPE]);
}
}
}
//...
}
エージェントメッセージの受信イベント
このイベントは、ユーザーが会話中にエージェントから何らかのメッセージを受信したときにトリガーされます。このデリゲートは、ボットによるメッセージや自動送信メッセージに対してはトリガーされません。
イベントの名前:
HelpshiftEvent.AGENT_MESSAGE_RECEIVEDイベントのデータ:
キー データ型 値 HelpshiftEvent.DATA_PUBLISH_ID string 現在進行中の問題の会話ID HelpshiftEvent.DATA_MESSAGE_TYPE string メッセージのメッセージ型 HelpshiftEvent.DATA_MESSAGE_BODY string エージェントが送信した実際のメッセージまたは空白 HelpshiftEvent.DATA_CREATED_TIME long ミリ秒単位のUnixエポックのタイムスタンプ HelpshiftEvent.DATA_ATTACHMENTS 辞書<string, object>> 添付ファイル(存在する場合) HelpshiftEvent.DATA_URL string 添付ファイルのURL HelpshiftEvent.DATA_CONTENT_TYPE string 添付ファイルのMIMEタイプ HelpshiftEvent.DATA_FILE_NAME string 添付ファイルのファイル名 HelpshiftEvent.DATA_SIZE Integer 添付ファイルのサイズ(バイト単位)
- このデリゲートは、10.3.0以降のバージョンで利用可能です
- 添付ファイルのキーは、エージェントが添付ファイルを送信した場合にのみ存在します。
- エージェントが送信した添付ファイルには必要なMIMEタイプや名前がない可能性があるため、ペイロードから
HelpshiftEvent.DATA_CONTENT_TYPEが欠落する可能性があります。 そういった場合には、ファイル名の拡張子からファイルの種類を推測することができます。 - HelpshiftEvent.DATA_MESSAGE_TYPEには、以下の種類があります。
- HelpshiftEvent.DATA_MESSAGE_TYPE_APP_REVIEW_REQUEST
- HelpshiftEvent.DATA_MESSAGE_TYPE_SCREENSHOT_REQUEST
- HelpshiftEvent.DATA_MESSAGE_TYPE_TEXT
public class HSEventsListener : IHelpshiftEventsListener
{
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if (eventName.Equals(HelpshiftEvent.AGENT_MESSAGE_RECEIVED))
{
string publishId = (string)eventData[HelpshiftEvent.DATA_PUBLISH_ID];
string type = (string)eventData[HelpshiftEvent.DATA_MESSAGE_TYPE];
string body = (string)eventData[HelpshiftEvent.DATA_MESSAGE_BODY];
long? createdTs = (long?)eventData[HelpshiftEvent.DATA_CREATED_TIME];
if (string.IsNullOrEmpty(publishId) && string.IsNullOrEmpty(type) && string.IsNullOrEmpty(body) && createdTs == null)
{
Debug.Log(TAG, "Received no data");
return;
}
Debug.Log($"publishId {publishId}, type {type}, body {body}, createdTs {createdTs}");
List<object> attachments = (List<object>)eventData[HelpshiftEvent.DATA_ATTACHMENTS];
if (Utils.isEmpty(attachments))
{
Debug.Log("No attachments received in message");
}
else
{
for (int i = 0; i < attachments.Count; i++)
{
Dictionary<string, object> attachment = (Dictionary<string, object>)attachments[i];
string url = (string)attachment[HelpshiftEvent.DATA_URL];
string contentType = (string)attachment[HelpshiftEvent.DATA_CONTENT_TYPE];
string fileName = (string)attachment[HelpshiftEvent.DATA_FILE_NAME];
int? size = (int?)attachment[HelpshiftEvent.DATA_SIZE];
if (string.IsNullOrEmpty(url) && string.IsNullOrEmpty(fileName) && size == null)
{
Debug.Log($"Received no data for attachment {i + 1}");
continue;
}
if (string.IsNullOrEmpty(url) || string.IsNullOrEmpty(fileName) || size == null)
{
Debug.Log($"Received incomplete data for attachment {i + 1}");
continue;
}
Debug.Log($"Attachment No. : {i + 1}, url: {url}, contentType: {contentType}, fileName: {fileName}, size: {size}");
}
}
}
}
}
CSATの送信イベント
このイベントは、会話の終了後にユーザーがCSAT(顧客満足度)評価を送信したときにトリガーされます。イベントのデータオブジェクトにはratingキーとadditionalFeedbackキーが含まれており、これらはユーザーがCSATフォームを介して提供した(星による)評価と追加のコメントを示しています。ご参考までに、以下の例をご確認ください。
- イベントの名前:
HelpshiftEvent.CSAT_SUBMIT - イベントのデータ:
HelpshiftEvent.DATA_CSAT_RATING- 型:
int
- 型:
HelpshiftEvent.DATA_ADDITIONAL_FEEDBACK- 型:
string
- 型:
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if (eventName.Equals(HelpshiftEvent.CSAT_SUBMIT))
{
if(eventData.ContainsKey(HelpshiftEvent.DATA_CSAT_RATING)) {
Debug.Log("CSAT submitted with rating: " + eventData[HelpshiftEvent.DATA_CSAT_RATING]);
}
if(eventData.ContainsKey(HelpshiftEvent.DATA_ADDITIONAL_FEEDBACK)) {
Debug.Log("CSAT feedback: " + eventData[HelpshiftEvent.DATA_ADDITIONAL_FEEDBACK]);
}
}
}
//...
}
会話の終了イベント
このイベントは会話が終了(解決または拒否)し、再開できない場合にトリガーされます。
- イベントの名前:
HelpshiftEvent.CONVERSATION_END - イベントのデータ:
null
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if (eventName.Equals(HelpshiftEvent.CONVERSATION_END))
{
Debug.Log("Conversation Ended");
}
}
//...
}
会話の拒否イベント
このイベントは、エージェントが会話を拒否したときにトリガーされます。
- イベントの名前:
HelpshiftEvent.CONVERSATION_REJECTED - イベントのデータ:
null
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if (eventName.Equals(HelpshiftEvent.CONVERSATION_REJECTED))
{
Debug.Log("Conversation Rejected");
}
}
//...
}
会話の解決イベント
このイベントは、エージェントが会話を解決したときにトリガーされます。
- イベントの名前:
HelpshiftEvent.CONVERSATION_RESOLVED - イベントのデータ:
null
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if (eventName.Equals(HelpshiftEvent.CONVERSATION_RESOLVED))
{
Debug.Log("Conversation Resolved");
}
}
//...
}
会話の再開イベント
解決に関する質問が有効化されている場合、ユーザーに対して解決の内容に満足しているかどうかが質問されます。ユーザーがそれを拒否し、新しいメッセージを送信すると会話が再開され、会話の再開イベントがトリガーされます。
イベントの名前: HelpshiftEvent.CONVERSATION_REOPENED
- イベントのデータ:
null
public class HSEventsListener : IHelpshiftEventsListener
{
// ...
public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
{
if (eventName.Equals(HelpshiftEvent.CONVERSATION_REOPENED))
{
Debug.Log("Conversation Reopened");
}
}
//...
}
ユーザー認証の失敗イベント
ダッシュボードでuser authentication featureが有効化された状態でHelpshiftSdk.GetInstance().Login(userDataMap)で無効なトークンを渡すと、理由に関する文字列とともにこのイベントを受け取ります。詳細については、こちらを参照してください。
理由の種類:
HelpshiftAuthenticationFailureReason.INVALID_AUTH_TOKENHelpshiftAuthenticationFailureReason.AUTH_TOKEN_NOT_PROVIDEDHelpshiftAuthenticationFailureReason.UNKNOWN
public class HSEventsListener: IHelpshiftEventsListener
{
// HandleHelpshiftEvent
public void AuthenticationFailedForUser(HelpshiftAuthenticationFailureReason reason)
{
Debug.Log("Authentication Failed for reason " + reason.ToString());
}
}
ユーザーアイデンティティシステムイベント
アイデンティティシステム関連のAPIを使用する場合、このセクションで説明するイベントを使用して関連するイベントがアプリに伝達されます。イベントには、対応するイベントの詳細情報を提供する関連データを持たせることができます。これらのイベントは、すべてHelpshiftEvent.csファイルにあります。
該当する場合、最大許容上限は以下のように定義されます。-
- キーの長さ - 最大255文字
- IDの値の長さ(
uidを除く) - 最大300文字 - ID
uidの値の長さ - 最大750文字 - CUFの値の長さ - 最大255文字
- マルチラインCUFの値の長さ - 最大100000文字
- ユーザータグの値の長さ - 最大100文字
- コレクションのサイズ - 最大30エントリ
INVALID_IDENTITY_TOKEN
アイデンティティJWTが有効な形式ではありません
- API -
AddUserIdentities - データ - null
IAT_IS_MANDATORY
JWTにiatキーがありません。Issued At Timestampまたはiatは、JWTペイロードの必須キーです。
- API -
AddUserIdentities - データ - null
IDENTITY_DATA_INVALID
JWTペイロードのアイデンティティの一部が有効ではありません
- API -
AddUserIdentities - データ -
| キー | 値 | リカバリー |
|---|---|---|
| 渡されたアイデンティティキーのいずれか1つ | EXCEEDED_KEY_LENGTH_LIMIT | キーの長さが許容範囲内であることをご確認ください |
| 渡されたアイデンティティキーのいずれか1つ | EXCEEDED_VALUE_LENGTH_LIMIT | 値の長さが許容範囲内であることをご確認ください |
| 渡されたアイデンティティキーのいずれか1つ | EMPTY_DATA | キーまたは値が空でない有効な値であることをご確認ください |
| 渡されたアイデンティティキーのいずれか1つ | META_DATA_EXCEEDED_COUNT_LIMIT | このアイデンティティのメタデータ辞書のエントリー総数が許容範囲内であることをご確認ください |
| 渡されたアイデンティティメタデータキーのいずれか1つ | META_DATA_EXCEEDED_KEY_LENGTH_LIMIT | メタデータキーの長さが許容範囲内であることをご確認ください |
| 渡されたアイデンティティメタデータキーのいずれか1つ | META_DATA_EXCEEDED_VALUE_LENGTH_LIMIT | メタデータの値の長さが許容範囲内であることをご確認ください |
| 渡されたアイデンティティメタデータキーのいずれか1つ | METADATA_EMPTY_KEY_OR_VALUE | メタデータのキーまたは値が空でない有効な値であることをご確認ください |
IDENTITY_DATA_LIMIT_EXCEEDED
JWTペイロードのアイデンティティの数が許容上限を超えています
- API -
AddUserIdentities - データ - null
IDENTITY_DATA_SYNC_FAILED
ユーザーアイデンティティをバックエンドと同期できませんでした
- API -
AddUserIdentities - データ -
| キー | 値 | リカバリー |
|---|---|---|
| 渡されたアイデンティティキーのいずれか1つ | INVALID_DATA | NA |
APP_ATTRIBUTES_LIMIT_EXCEEDED/MASTER_ATTRIBUTES_LIMIT_EXCEEDED
同期されていないアプリまたはマスター属性の数が許容上限を超えています
- API -
UpdateAppAttributes、UpdateMasterAttributes - データ - null
APP_ATTRIBUTES_VALIDATION_FAILED/MASTER_ATTRIBUTES_VALIDATION_FAILED
属性辞書内の個々のエントリーの検証に失敗しました
- API -
UpdateAppAttributes、UpdateMasterAttributes - データ -
| キー | 値 | リカバリー |
|---|---|---|
| 渡された属性キーのいずれか1つ | EXCEEDED_KEY_LENGTH_LIMIT | キーの長さが許容範囲内であることをご確認ください |
| 渡された属性キーのいずれか1つ | EXCEEDED_VALUE_LENGTH_LIMIT | 値の長さが許容範囲内であることをご確認ください |
| 渡された属性キーのいずれか1つ | EXCEEDED_COUNT_LIMIT | 指定したキーのコレクション内のエントリーの数を減らしてください |
| 渡された属性キーのいずれか1つ | INVALID_VALUE_TYPE | 値が対応する型(文字列、ブール値、数値、文字列配列、または文字列-文字列辞書のいずれか)であることをご確認ください |
APP_ATTRIBUTES_SYNC_FAILED/MASTER_ATTRIBUTES_SYNC_FAILED
バックエンドとの属性の同期に失敗しました
- API -
UpdateAppAttributes、UpdateMasterAttributes - データ -
| キー | 値 | リカバリー |
|---|---|---|
| 渡された属性キーのいずれか1つ | INVALID_DATA | NA |
IDENTITY_FEATURE_NOT_ENABLED
ご利用のドメインでアイデンティティ機能が有効化されていません
- API -
AddUserIdentities、UpdateAppAttributes、UpdateMasterAttributes - データ - null
USER_SESSION_EXPIRED
SDKのユーザーセッションの期限が切れたときに送信されます。セッションの有効期限が切れると、SDKはフォアグラウンドになるたびにこのイベントをアプリに送信し続けます。 このイベントに応答して現在のユーザーのJWTを更新し、新しいJWTでもう一度ユーザーをログインさせる必要があります。
データ - null
REFRESH_USER_CREDENTIALS
SDKのユーザーセッションがまもなく期限切れになるタイミングで送信されます。これにより、現在のユーザーのJWTを前もって更新し、 新しいJWTを用いてSDKにログインすることによってセッションが中断されないようにすることができます。
データ - null