メインコンテンツまでスキップ

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_ACTION
    • HelpshiftEvent.DATA_ACTION_TYPE
    • HelpshiftEvent.DATA_ACTION_TYPE_CALL
    • HelpshiftEvent.DATA_ACTION_TYPE_LINK
キー(定数)キー(生)データ型
HelpshiftEvent.ACTION_CLICKEDuserClickOnActionstring
HelpshiftEvent.DATA_ACTIONactionTypestring
HelpshiftEvent.DATA_ACTION_TYPEactionDatastring
HelpshiftEvent.DATA_ACTION_TYPE_CALLcallstring
HelpshiftEvent.DATA_ACTION_TYPE_LINKlinkstring
注意

キーの定数は、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_IDstring現在進行中の問題の会話ID
    HelpshiftEvent.DATA_MESSAGE_TYPEstringメッセージのメッセージ型
    HelpshiftEvent.DATA_MESSAGE_BODYstringエージェントが送信した実際のメッセージまたは空白
    HelpshiftEvent.DATA_CREATED_TIMElongミリ秒単位のUnixエポックのタイムスタンプ
    HelpshiftEvent.DATA_ATTACHMENTS辞書<string, object>>添付ファイル(存在する場合)
    HelpshiftEvent.DATA_URLstring添付ファイルのURL
    HelpshiftEvent.DATA_CONTENT_TYPEstring添付ファイルのMIMEタイプ
    HelpshiftEvent.DATA_FILE_NAMEstring添付ファイルのファイル名
    HelpshiftEvent.DATA_SIZEInteger添付ファイルのサイズ(バイト単位)
注意
  • このデリゲートは、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_TOKEN
  • HelpshiftAuthenticationFailureReason.AUTH_TOKEN_NOT_PROVIDED
  • HelpshiftAuthenticationFailureReason.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_DATANA

APP_ATTRIBUTES_LIMIT_EXCEEDED/MASTER_ATTRIBUTES_LIMIT_EXCEEDED

同期されていないアプリまたはマスター属性の数が許容上限を超えています

  • API - UpdateAppAttributesUpdateMasterAttributes
  • データ - null

APP_ATTRIBUTES_VALIDATION_FAILED/MASTER_ATTRIBUTES_VALIDATION_FAILED

属性辞書内の個々のエントリーの検証に失敗しました

  • API - UpdateAppAttributesUpdateMasterAttributes
  • データ -
キーリカバリー
渡された属性キーのいずれか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 - UpdateAppAttributesUpdateMasterAttributes
  • データ -
キーリカバリー
渡された属性キーのいずれか1つINVALID_DATANA

IDENTITY_FEATURE_NOT_ENABLED

ご利用のドメインでアイデンティティ機能が有効化されていません

  • API - AddUserIdentitiesUpdateAppAttributesUpdateMasterAttributes
  • データ - null

USER_SESSION_EXPIRED

SDKのユーザーセッションの期限が切れたときに送信されます。セッションの有効期限が切れると、SDKはフォアグラウンドになるたびにこのイベントをアプリに送信し続けます。 このイベントに応答して現在のユーザーのJWTを更新し、新しいJWTでもう一度ユーザーをログインさせる必要があります。

データ - null

REFRESH_USER_CREDENTIALS

SDKのユーザーセッションがまもなく期限切れになるタイミングで送信されます。これにより、現在のユーザーのJWTを前もって更新し、 新しいJWTを用いてSDKにログインすることによってセッションが中断されないようにすることができます。

データ - null