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

ユーザー（iOS）

注意

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

先に進む前に

このセクションでは、従来の方式でユーザーを統合する方法について説明します。新しいIDシステムUser Hubとの統合については、このページを参照してください。

より迅速なコンテキストの収集、より簡単なエージェントエクスペリエンス、より強化されたセキュリティおよびスパム対策が必要な場合には、新しいIDシステムの使用をお勧めします。

ユーザーの識別と管理​

ユーザーのログイン​

概要​

ログインユーザーとは、ユーザー名とパスワードを入力した後にのみサポートチームと連絡を取ることができるユーザーのことを指しています。ログインユーザーがいる場合には、エージェントがエンドユーザーの使用デバイスにかかわらずユーザーにパーソナライズされたサポート体験を提供できるように、Login APIを使用してユーザーの識別子（ユーザーIDおよび/またはメールアドレス）を渡すことを強くお勧めしています。また、Login APIを使用することでユーザーの会話はログイン時にのみ利用可能となります。

識別子として提供されるもの​

ユーザーの識別には、userIDおよび/またはuserEmailを提供することが可能です。弊社ではユーザーIDの使用を強く推奨しております。しかしながら、ユーザーを識別するためにメールアドレスを使用する場合には、HelpshiftSdk.GetInstance().Login(Dictionary<string, string> data) API内のマップとしてそれをuserEmailフィールドで渡す必要があります。userIDとuserEmailの両方を使用する場合、以下のロジックが適用されます。

  • ユーザーを検索する際、`userId`は `userEmail`よりも優先度が高くなっています
  • ユーザーIDが既存のユーザーに一致した場合、そのユーザーのメールアドレスは 更新されます（メールアドレスが提供されている場合）
  • メールアドレスが既存のユーザーに一致した場合、以下のロジックが適用されます。
    • メールアドレスが一致したユーザーにユーザーIDが存在しない場合、そのユーザー IDがそのユーザーに追加されます（ユーザーIDが提供されている場合）
    • もしもそのユーザーIDがメールアドレスが一致しているユーザーに対して既に存在する場合、新しい ユーザーが作成されます（異なるユーザーIDが提供されている場合）

使用方法​

ユーザーがアプリへのログインに成功するたびに、Helpshift SDKのLogin APIを呼び出す必要があります。Login APIは、以下のパラメーターを持っています。

  • "userEmail"の値が空白を取り除いた後の空の文字列である場合、このパラメーターを"login"呼び出しに含めないでください。
    • パラメーター必須/オプションSDKの説明重要事項
    userNameオプションエージェントがエンドユーザーとやり取りをする際に使用する名前を入力します。ユーザーの名前が分からない場合には空白のままにすることができ、（有効化されている場合には）アイデンティティボットがそのユーザーに名前を尋ねます。値を指定すると、アイデンティティボットはユーザーに再度名前を尋ねなくなります。最大長は255文字です。これよりも長い値は切り捨てられます。
  • userNameの値から空白を取り除くと空の文字列となった場合、このパラメーターを"login"の呼び出しに含めないでください。
    • userIdメールアドレスが提供されていない場合には必須の識別子となりますユーザー固有の識別子です。ユーザーIDは一意である必要があります。異なるユーザーに同一のユーザーIDを使用させるべきではありません。
    • 最大長は750文字です。これよりも長い値を許可すると、結果的に匿名ユーザーが作成されてしまいます。
    • 先頭および末尾のスペースは許可されません。中間にスペースを入れることは可能です。先頭および末尾にスペースが含まれているユーザーIDを許可すると、結果的に匿名ユーザーが作成されてしまいます。
    • ユーザーIDは常に大文字と小文字を区別します（たとえば、1abcと1ABCは別のIDとなります）。
    • ユーザーのメールアドレスを"userID"として使用しないでください。ユーザーの識別にメールアドレスを利用する場合には、"userEmail"として使用してください。
    • メールアドレスだけでなくユーザーIDも使用する場合には、その後の呼び出しでユーザーIDが存在することを確認してください。複数のプロファイルが同じメールアドレスを使用している場合、メールアドレスを使用するだけではすべてのプロファイルが返されてしまいます。
    • "userId"の値から空白を取り除くと空の文字列となった場合、このパラメーターを"login"の呼び出しに含めないでください。
    userEmailユーザーIDが提供されていない場合には必須の識別子となりますユーザーのメールアドレスです。ユーザーのメールアドレスが分からない場合には空白のままにすることができ、（有効化されている場合には）アイデンティティボットがそのユーザーにメールアドレスを尋ねます。値を指定すると、アイデンティティボットはユーザーに再度メールアドレスを尋ねなくなります。
    • メールアドレスの形式は、有効なものである必要があります（"my@email.com"の形式を使用する必要があります）無効なメールアドレスを許可すると、結果的に匿名ユーザーが作成されてしまいます。
    • 先頭および末尾のスペースは許可されません。先頭および末尾にスペースが含まれているメールアドレスを許可すると、結果的に匿名ユーザーが作成されてしまいます。
    • メールアドレスでは、大文字と小文字は常に区別されません（たとえば、MY@EMAIL.COMとmy@email.comは同じメールアドレスです）。
    /n
    userAuthTokenオプションSHA256を使用したハッシュベースのメッセージ認証コード（HMAC）を介して生成されたユーザー認証トークンです。第三者がユーザーに代わって問題を提出したり、ユーザーのプロパティを更新したりできないようにする場合には、HMACダイジェストを使用する必要があります。 詳細はこちら。
    • ユーザーが確実に問題を提出できるようにするために、有効なHMACダイジェストを使用する必要があります。詳細はこちら。
    • "userAuthToken"の値が空白を取り除いた後の空の文字列である場合、このパラメーターを"login"呼び出しに含めないでください。

    Helpshiftでログインユーザーを作成するには、userIdまたはuserEmailのいずれかを使用する必要があります。

    using Helpshift;
    // ..

     HelpshiftSdk _support = HelpshiftSdk.GetInstance();

     void Awake(){
      // install call here
     }

     void Login(){
      Dictionary<string, string> userDetails = new Dictionary<string, string>();

      string userId = generateUserId();
      string userEmail = fetchUserEmail();
      string userName = fetchUserName();

      if (strings.IsNullOrEmpty(userId) && strings.IsNullOrEmpty(userEmail)) {
        throw new Exception("userId and userEmail both are empty. Invalid login! ");
      }

      if (!strings.IsNullOrEmpty(userId)) {
        userDetails["userId"] = userId;
      }

      if (!strings.IsNullOrEmpty(userEmail)) {
        userDetails["userEmail"] = userEmail;
      }

      if (!strings.IsNullOrEmpty(userName)) {
        userDetails["userName"] = userName;
      }

      bool loginSuccess = _support.Login(userDetails);
      Debug.Log("Helpshift - loginSucccess : " + loginSuccess);
    }

    ユーザーのログアウト​

    概要​

    ユーザーがアプリからログアウトしたら、Helpshift SDKのLogout APIを呼び出し、他のユーザーがこのユーザーの会話を表示できないようにする必要があります。

    注意

    Logout APIは、Login APIと組み合わせて使用することが期待されています。

    使用方法​

    _support.Logout();

    匿名ユーザー​

    概要​

    匿名ユーザーとは、ユーザー名とパスワードなしでアプリにアクセスできるユーザーのことを指します。Login API経由でユーザー識別子（ユーザーIDおよび/またはメールアドレス）が渡されていない場合、Helpshiftはそのユーザーが匿名ユーザーであり、現在ログインしていないものとみなします。

    複数のログインユーザー/匿名ユーザーが同じデバイスを使用してサポート会話中に情報のやり取りを行う（理想としてはログインをまたいだ共有を許可したくないない）ユースケースの場合には、ClearAnonymousUserOnLogin(shouldClear) APIを使用する必要があります。

    • shouldClearがtrueの場合 – 匿名ユーザーは、どのユーザーがログインしても消去されます。一度消去されると、そういったユーザー（およびその会話）は二度と取得できなくなります。
    • shouldClearがfalseの場合 – 匿名ユーザーのデータは保存され、ログインユーザーがログアウトすると、匿名ユーザーの会話履歴が表示されます。
    help = HelpshiftSdk.GetInstance();
    help.ClearAnonymousUserOnLogin(shouldClear);
    注意
    • clearAnonymousUserOnLogin(shouldClear)機能は、ログインユーザーのエクスペリエンスには一切影響を与えません。

    ユーザーの同一性の確認​

    アプリ内で同一性の確認を構成する​

    概要​

    ユーザーの同一性の確認は、お客様のアプリからHelpshiftへのすべてのリクエストが正当なエンドユーザーからのものであることを確認するためのセキュリティ施策です。これにより、第三者やハッカーによるユーザーのなりすましを防止することができます。ユーザーの同一性の確認に関する詳細情報と設定の手順については、こちらをご参照ください。ユーザーを確実に認証するためには、初期化の際に_support.Login(Dictionary<string, string> userData)とともにユーザー認証トークンを提供する必要があります。ユーザー認証トークンの生成手順については、こちらをご参照ください。ユーザー認証トークンはHMACダイジェストであり、SHA256を使用したHMACを介して生成されます。

    HMACダイジェストを送信してユーザーの同一性を確認する​

    Login API呼び出しでユーザー認証トークンを送信することができます。 Helpshiftダッシュボード（ドキュメントはこちら）で本人確認が有効になっている場合、Helpshiftは共有秘密鍵を使用して固有のユーザー認証トークンを再計算し、お客様から送信されたユーザー認証トークンと再計算された値を比較します。それらが一致していればユーザーの同一性が確認されたことになり、ユーザーは問題を提出することができます。

    using Helpshift;
    // ..

     HelpshiftSdk _support = HelpshiftSdk.GetInstance();

     void Awake(){
      // install call here
     }

     void Login(){
      Dictionary<string, string> userDetails = new Dictionary<string, string>();

      string userId = generateUserId();
      string userEmail = fetchUserEmail();
      string userName = fetchUserName();

      if (strings.IsNullOrEmpty(userId) && strings.IsNullOrEmpty(userEmail)) {
        throw new Exception("userId and userEmail both are empty. Invalid login! ");
      }

      if (!strings.IsNullOrEmpty(userId)) {
        userDetails["userId"] = userId;
      }

      if (!strings.IsNullOrEmpty(userEmail)) {
        userDetails["userEmail"] = userEmail;
      }

      if (!strings.IsNullOrEmpty(userName)) {
        userDetails["userName"] = userName;
      }

      string userAuthToken = generateUserAuthToken();

      if (!strings.IsNullOrEmpty(userAuthToken)) {
        userDetails["userAuthToken"] = userAuthToken;
      }

      bool loginSuccess = _support.Login(userDetails);
      Debug.Log("Helpshift - loginSucccess : " + loginSuccess);
     }
    注意

    • ダッシュボードでアプリの秘密鍵が再生成された場合、有効なユーザー認証トークンを生成するために、エンドポイントのコードも確実に更新する必要があります。続いて、古い秘密鍵を使用して生成されたユーザー認証トークンを使用したリクエストが無効になるように、管理者はダッシュボードから古い秘密鍵を削除する必要があります。

    • EnableFullPrivacyがオンになっている場合には、ユーザー認証トークンはユーザーIDに対してのみ生成されます。

    本人確認の失敗​

    概要​

    本人確認がオンになっている場合、ユーザー認証トークンがない、もしくは無効なユーザー認証トークンを用いた状態でログインリクエストが行われると、本人確認が失敗となります。本人確認に失敗すると、以下のようになります。

    • 匿名ユーザー（開発者が識別子を提供していないユーザー）は、常に問題を提出することができます。
    • ログインユーザー（開発者がユーザーIDやメールアドレスなどの識別子を提供しているユーザー）は、認証されていない場合には問題を提出したり会話を確認したりすることができません。未認証のログインユーザーに対しては、フォームまたは対話型UIでエラーが表示されます。

    ログインユーザーが認証されると（つまり、有効なユーザー認証トークンが提供されると）、前回の問題を確認したり、新しい課題を作成したりすることができるようになります。認証が完了したログインユーザーのUIは本人確認がオフになっている場合とまったく同じように表示され、動作します。上記のような影響を受けるのは、認証が完了していないユーザーのみです。

    失敗デリゲートの使用方法​

    本人確認に失敗した場合、SDKはAuthenticationFailedForUser(...)デリゲートを呼び出し、アプリケーションに失敗を通知します。

    認証失敗の理由呼び出されるタイミング使用するタイミング
    HelpshiftAuthenticationFailureReason
    .AUTH_TOKEN_NOT_PROVIDED    		ユーザー認証トークンが提供されなかったときユーザー認証トークンを送信する予定はないものの将来的に実装する予定がある 場合には、この失敗デリゲートを使用してアプリのアップデートを促すような独自のアラートを ユーザーに対して表示することができます。ユーザー認証トークンを使用せずに Login APIを使用している場合には、ダッシュボードで本人確認を有効にするとこれらの ユーザーは未認証であるとみなされてしまうため、これを使用すると良いかもしれません。 このデリゲートの使用については、完全に任意となっております。前述の通り、 Helpshiftでは未認証のユーザー が問題を提出することはできません。
    HelpshiftAuthenticationFailureReason
    .INVALID_AUTH_TOKEN    		ユーザー認証トークンが無効だったときLogin APIを介して提供されるHMACダイジェストが無効な場合、Helpshift はユーザーによる問題の提出を阻止します。以下の場合、ユーザー認証トークン が無効である可能性があります。
    • プログラミングにミスがある場合。HMACダイジェストの生成方法については、 こちらをご参照ください。
    • ダッシュボードで秘密鍵を再生成したものの、 ユーザー認証トークンを更新していなかった場合。
    • 第三者がリクエストを試みている場合。
    ユーザー認証トークンが無効な場合、前述の通りエンドユーザーは問題を提出できず、 エラーが表示されます。独自のアラートを表示したり、サーバーから正しい認証トークンを 再取得したい場合には、 このデリゲートを使用します。
    HelpshiftAuthenticationFailureReason.UNKNOWN認証失敗の理由が不明なとき

    認証失敗の理由は、列挙型HelpshiftAuthenticationFailureReasonでラップされています。例:

    // ...
      public class HSEventsListener: IHelpshiftEventsListener
        {

            public void AuthenticationFailedForUser(HelpshiftAuthenticationFailureReason reason)
            {
                HelpshiftInternalLogger.d("Authentication Failed for reason " + reason.ToString());
            }

           // other methods
        }
    // ...
    // and register this event listener

    using Helpshift;
    // ..
    //..
    HelpshiftSdk _helpshiftX = HelpshiftSdk.GetInstance()
    _helpshiftX.SetHelpshiftEventsListener(new HSEventsListener());