Helpshiftのデリゲート

Helpshift SDKでは、アプリの開発者がヘルプセクション内でのユーザーアクティビティを追跡できるようにデリゲートコールバックが提供されています。

注意

SDKに含まれているすべてのパブリックAPIは、Helpshift.install() APIを介してSDKを初期化した後に呼び出す必要があります

Helpshiftイベントリスナー/デリゲートの実装

Helpshift.setHelpshiftEventsListener()メソッドを呼び出すことで、HelpshiftEventsListenerを設定することができます。

注意

• Helpshift.setHelpshiftEventsListenerを設定する前に呼び出されたイベントは、再度受け取ることができません。
• SDKによって生成されたイベントを逃さないように、デリゲートはHelpshift Install APIを呼び出した直後に設定してください。

例:

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
 @Override
 public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
   switch(eventName){
     case HelpshiftEvent.CONVERSATION_START:
       //your code here
     break;
     // and so on...
     //the list of events is given below
   }
 }

 @Override
 public void onUserAuthenticationFailure(HelpshiftAuthenticationFailureReason reason) {
   // your code here
 }
});

クラスの実装: HelpshiftEventsListenerを実装するクラスを定義し、 Helpshift.setHelpshiftEventsListener()メソッドを使用してこのイベントリスナーのインスタンスを設定する必要があります。

class MyEventListener implements HelpshiftEventsListener {

  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName) {
      case HelpshiftEvent.CONVERSATION_START:
        //your code here
      break;
      // and so on...
      //the list of events is given below
    }
  }

  @Override
  public void onUserAuthenticationFailure(HelpshiftAuthenticationFailureReason reason) {
    // your code here
  }
}

MyEventListener listener = new MyEventListener();
Helpshift.setHelpshiftEventsListener(listener);

Helpshiftのイベント

会話の状態イベント

このイベントには、現在進行中の会話に関する情報が含まれています。

• イベントの名前: HelpshiftEvent.CONVERSATION_STATUS
• イベントのデータ:
  • HelpshiftEvent.DATA_LATEST_ISSUE_ID
  • HelpshiftEvent.DATA_LATEST_ISSUE_PUBLISH_ID
  • HelpshiftEvent.DATA_IS_ISSUE_OPEN

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_STATUS:
        Log.d(TAG, data.get(HelpshiftEvent.DATA_LATEST_ISSUE_PUBLISH_ID));
    }
  }
});

ウィジェットの切り替えイベント

このイベントは、ユーザーがチャット画面を開いたり閉じたりしたときにトリガーされます。このイベントは、"visible"キーのブーリアン値を用いてトリガーされます。

• イベントの名前: HelpshiftEvent.WIDGET_TOGGLE
• イベントのデータ: HelpshiftEvent.DATA_SDK_VISIBLE

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.WIDGET_TOGGLE:
        Log.d(TAG, data.get(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_CLICKED	userClickOnAction	文字列
HelpshiftEvent.DATA_ACTION	actionType	文字列
HelpshiftEvent.DATA_ACTION_TYPE	actionData	文字列
HelpshiftEvent.DATA_ACTION_TYPE_CALL	call	文字列
HelpshiftEvent.DATA_ACTION_TYPE_LINK	link	文字列

注意

キーの定数は、SDK X 10.3.0以降で利用可能です。古いバージョンのSDK Xでは、生のキーを代わりに使用してください。

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.ACTION_CLICKED:
          // With Key Constants
          String actionType = (String) data.get(HelpshiftEvent.DATA_ACTION_TYPE);
          String actionData = (String) data.get(HelpshiftEvent.DATA_ACTION);

          -------------------- OR --------------------

          // With Key Raw Values
          String actionType = (String) data.get("actionType");
          String actionData = (String) data.get("actionData");

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

          Log.d(TAG, "Event Received for " + eventName + " action type " + actionType + " actionData " + actionData);
    }
  }});

会話の開始イベント

このイベントは、ユーザーが会話の中で最初のメッセージを送信したときにトリガーされます。イベントのデータオブジェクトにはmessageキーが含まれており、これにはエンドユーザーが会話を始めるために送信したメッセージの文字列が含まれています。

• イベントの名前: HelpshiftEvent.CONVERSATION_START
• イベントのデータ: HelpshiftEvent.DATA_MESSAGE

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_START:
        Log.d(TAG, data.get(HelpshiftEvent.DATA_MESSAGE));
    }
  }
});

メッセージの追加イベント

このイベントは、ユーザーが会話内でメッセージを追加したときにトリガーされます。追加されるメッセージには、テキストメッセージ、ボットの入力を介した応答、添付ファイルなどが想定されています。イベントのデータオブジェクトにはtypeキーとbodyキーが含まれており、これらはユーザーが追加したメッセージの種類と本文を示しています。

• イベントの名前: HelpshiftEvent.MESSAGE_ADD
• イベントのデータ:
  • HelpshiftEvent.DATA_MESSAGE_TYPE
  • HelpshiftEvent.DATA_MESSAGE_BODY
  • HelpshiftEvent.DATA_MESSAGE_TYPE_ATTACHMENT
  • HelpshiftEvent.DATA_MESSAGE_TYPE_TEXT

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.MESSAGE_ADD:
        Log.d(TAG, data.get(HelpshiftEvent.DATA_MESSAGE_BODY));
        if(data.get(HelpshiftEvent.DATA_MESSAGE_TYPE).equals(HelpshiftEvent.DATA_MESSAGE_TYPE_ATTACHMENT)){
          Log.d(TAG, "user sent an attachment");
        }
    }
  }
});

エージェントメッセージの受信イベント

このイベントは、ユーザーが会話中にエージェントから何らかのメッセージを受信したときにトリガーされます。このデリゲートは、ボットによるメッセージや自動送信メッセージに対してはトリガーされません。

• イベントの名前: HelpshiftEvent.AGENT_MESSAGE_RECEIVED

• イベントのデータ:

  キー	データ型	値
  HelpshiftEvent.DATA_PUBLISH_ID	文字列	現在進行中の問題の会話ID
  HelpshiftEvent.DATA_MESSAGE_TYPE	文字列	メッセージのメッセージ型
  HelpshiftEvent.DATA_MESSAGE_BODY	文字列	エージェントが送信した実際のメッセージまたは空白
  HelpshiftEvent.DATA_CREATED_TIME	Long	ミリ秒単位の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

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> eventData) {
        switch (eventName) {
          case HelpshiftEvent.AGENT_MESSAGE_RECEIVED:
            Log.d(TAG,"Received Event for " + eventName);
            String publishId = (String) eventData.get(HelpshiftEvent.DATA_PUBLISH_ID);
            String type = (String) eventData.get(HelpshiftEvent.DATA_MESSAGE_TYPE);
            String body = (String) eventData.get(HelpshiftEvent.DATA_MESSAGE_BODY);
            Long createdTs = (Long) eventData.get(HelpshiftEvent.DATA_CREATED_TIME);

            // Utils.isEmpty() is null and empty Check

            if (Utils.isEmpty(publishId) && Utils.isEmpty(type) && Utils.isEmpty(body) && createdTs == null) {
              Log.d(TAG, "Received no data");
              return;
            }

            Log.d(TAG, "publishId " + publishId + " type " + type + " body " + body + " createdTs " + createdTs);
            List<Object> attachments = (List<Object>) eventData.get(HelpshiftEvent.DATA_ATTACHMENTS);

            if (Utils.isEmpty(attachments)) {
              Log.d(TAG, "No attachments received in message");
            } else {

              for (int i = 0; i < attachments.size(); i++) {
                Map<String, Object> attachment = (Map<String, Object>) attachments.get(i);

                String url = (String) attachment.get(HelpshiftEvent.DATA_URL);
                String contentType = (String) attachment.get(HelpshiftEvent.DATA_CONTENT_TYPE);
                String fileName = (String) attachment.get(HelpshiftEvent.DATA_FILE_NAME);
                Integer size = (Integer) attachment.get(HelpshiftEvent.DATA_SIZE);

                if (Utils.isEmpty(url) && Utils.isEmpty(fileName) && size == null) {
                  Log.d(TAG,"Received no data for attachment " + (i + 1));
                  continue;
                }

                if (Utils.isEmpty(url) || Utils.isEmpty(fileName) || size == null) {
                  Log.d(TAG,"Received incomplete data for attachment " + (i + 1));
                  continue;
                }

                Log.d(TAG, "Attachment No. : " + (i + 1) + ", url: " + url + ", contentType: " + contentType + ", fileName: " + fileName + ", size: " + size);
              }
            }
        }
  }});

CSATの送信イベント

このイベントは、会話の終了後にユーザーがCSAT（顧客満足度）評価を送信したときにトリガーされます。イベントのデータオブジェクトにはratingキーとadditionalFeedbackキーが含まれており、これらはユーザーがCSATフォームを介して提供した（星による）評価と追加のコメントを示しています。

• イベントの名前: HelpshiftEvent.CSAT_SUBMIT
• イベントのデータ:
  • HelpshiftEvent.DATA_CSAT_RATING
  • HelpshiftEvent.DATA_ADDITIONAL_FEEDBACK

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CSAT_SUBMIT:
        Log.d(TAG, data.get(HelpshiftEvent.DATA_CSAT_RATING));
        Log.d(TAG, data.get(HelpshiftEvent.DATA_ADDITIONAL_FEEDBACK));
    }
  }
});

会話の終了イベント

このイベントは会話が終了（解決または拒否）し、再開できない場合にトリガーされます。

• イベントの名前: HelpshiftEvent.CONVERSATION_END

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_END:
        //data will be empty
    }
  }
});

会話の拒否イベント

このイベントは、エージェントが会話を拒否したときにトリガーされます。

• イベントの名前: HelpshiftEvent.CONVERSATION_REJECTED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_REJECTED:
        //data will be empty
    }
  }
});

会話の解決イベント

このイベントは、エージェントが会話を解決したときにトリガーされます。

• イベントの名前: HelpshiftEvent.CONVERSATION_RESOLVED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_RESOLVED:
        //data will be empty
    }
  }
});

会話の再開イベント

解決に関する質問が有効化されている場合、ユーザーに対して解決の内容に満足しているかどうかが質問されます。ユーザーがそれを拒否し、新しいメッセージを送信すると会話が再開され、会話の再開イベントがトリガーされます。

• イベントの名前: HelpshiftEvent.CONVERSATION_REOPENED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.CONVERSATION_REOPENED:
        //data will be empty
    }
  }
});

ユーザー認証の失敗イベント

ダッシュボードでUser Authentication機能が有効化された状態でHelpshift.login(userDataMap)で無効なトークンを渡すと、理由に関する文字列とともにこのイベントを受け取ります。詳細については、こちらを参照してください。

理由の種類:

• HelpshiftAuthenticationFailureReason.REASON_INVALID_AUTH_TOKEN
• HelpshiftAuthenticationFailureReason.REASON_AUTH_TOKEN_NOT_PROVIDED
• HelpshiftAuthenticationFailureReason.UNKNOWN

     // ...
    Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
       @Override
      public void onUserAuthenticationFailure(HelpshiftAuthenticationFailureReason reason) {
        Log.e(TAG, reason);
      }
      // ...
    });

Helpshiftセッションのデリゲート

Helpshiftセッションの開始

Helpshiftセッションがアプリ内でいつ開始したかを追跡する場合は、このデリゲートコールバックを実装します。このデリゲートは、Helpshiftセッションが開始するたびに発動します。

• イベントの名前: HelpshiftEvent.SDK_SESSION_STARTED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.SDK_SESSION_STARTED:
        //sdk session started
    }
  }
});

Helpshiftセッションの終了

Helpshiftセッションがアプリ内でいつ終了したかを追跡する場合は、このデリゲートコールバックを実装します。このデリゲートは、Helpshiftセッションが終了するたびに発動します。

• イベントの名前: HelpshiftEvent.SDK_SESSION_ENDED

Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.SDK_SESSION_ENDED:
        //sdk session ended
    }
  }
});

未読メッセージ数の計測

既存の会話で受信した新規メッセージの数を計測する場合は、このrequestUnreadMessageCount(final boolean shouldFetchFromServer) APIを呼び出します。

未読メッセージの数は、このイベントを介してアプリに伝達されます。また、このイベントを使用してバッジの表示数を更新し続けることもできます。

• イベントの名前: HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT
• イベントのデータ: HelpshiftEvent.DATA_MESSAGE_COUNTHelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE

// call requestUnreadMessageCount() api first
Helpshift.requestUnreadMessageCount(true);

// ...
Helpshift.setHelpshiftEventsListener(new HelpshiftEventsListener() {
  @Override
  public void onEventOccurred(@NonNull String eventName, Map<String, Object> data) {
    switch(eventName){
      case HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT:
        int count = (int) data.get(HelpshiftEvent.DATA_MESSAGE_COUNT);
        boolean fromCache = (boolean) data.get(HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE);
        Log.d(TAG, "Message Count : " + count + ", From Cache: " + fromCache);
    }
  }
});

Helpshift.requestUnreadMessageCount(true)メソッドを呼び出すと、上記のデリゲートメソッド内のサーバーから通知の数が非同期で返されます。この通知の数は、キャッシュまたはHelpshiftサーバーのいずれかから取得されます。Helpshiftサーバーから取得する場合の通知数についてはレートが制限されており、タイムアウトのリセット後またはユーザーがチャット画面を閉じた後（いずれかの早い方）にAPIに対する次の呼び出しが行われた場合にのみ最新の値が返されます。レート制限の期間内にAPIが呼び出された場合には、ローカルキャッシュから値が返されます。タイムアウトのリセット時間は、アクティブな問題の場合は1分、そして非アクティブな問題の場合には5分に設定されています。

ローカルに保存されている現在の通知数を取得する場合、パラメータをfalseに設定した同じHelpshift.requestUnreadMessageCount(false)メソッドを呼び出します。この場合、SDKはローカルで利用可能な未読メッセージの数をこのデリゲートメソッド内で返します。

ローカルに保存されている未読メッセージの数は、追加のネットワーク呼び出しを節約するのに役立ちます。

ユーザーアイデンティティシステムイベント

アイデンティティシステム関連のAPIを使用する場合、このセクションで説明するイベントを使用して関連するイベントがアプリに伝達されます。イベントには、対応するイベントの詳細情報を提供する関連データを持たせることができます。 データの値の定数は、InvalidDataErrorReasonファイル内にあります。

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