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

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();
var configMap = new Dictionary<string, object>();
// add some config

help.Install(platformId, domainName, configMap);
}

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_CLICKEDuserClickOnAction文字列
HelpshiftEvent.DATA_ACTIONactionType文字列
HelpshiftEvent.DATA_ACTION_TYPEactionData文字列
HelpshiftEvent.DATA_ACTION_TYPE_CALLcall文字列
HelpshiftEvent.DATA_ACTION_TYPE_LINKlink文字列
注意

キーの定数は、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"];

// `Utils.isEmpty` is null and empty Check
if (Utils.isEmpty(actionType) || Utils.isEmpty(actionData)) {
Debug.Log("Event Received for " + eventName + " with actionType or action Data as empty");
return;
}

Debug.Log("Event Received for " + eventName + " action type " + actionType + " actionData " + 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文字列現在進行中の問題の会話ID
    HelpshiftEvent.DATA_MESSAGE_TYPE文字列メッセージのメッセージ型
    HelpshiftEvent.DATA_MESSAGE_BODY文字列エージェントが送信した実際のメッセージまたは空白
    HelpshiftEvent.DATA_CREATED_TIMELongミリ秒単位のUnixエポックのタイムスタンプ
    HelpshiftEvent.DATA_ATTACHMENTS辞書<String, Object>>添付ファイル(存在する場合)
    HelpshiftEvent.DATA_URL文字列添付ファイルのURL
    HelpshiftEvent.DATA_CONTENT_TYPE文字列添付ファイルのMIMEタイプ
    HelpshiftEvent.DATA_FILE_NAME文字列添付ファイルのファイル名
    HelpshiftEvent.DATA_SIZE整数添付ファイルのサイズ(バイト単位)
注意
  • このデリゲートは、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];

// Utils.isEmpty() is null and empty Check
if (Utils.isEmpty(publishId) && Utils.isEmpty(type) && Utils.isEmpty(body) && createdTs == 0) {
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.size(); i++) {
Dictionary<String, object> attachment = (Dictionary<String, object>) attachments.get(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 (Utils.isEmpty(url) && Utils.isEmpty(fileName) && size == 0) {
Debug.Log("Received no data for attachment " + (i + 1));
continue;
}

if (Utils.isEmpty(url) || Utils.isEmpty(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 submitted with rating: " + 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