ユーザー
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は、以下のパラメーターを持っています。
| パラメーター | 必須/オプション | SDKの説明 | 重要事項 |
|---|---|---|---|
| userName | オプション | エージェントがエンドユーザーとやり取りをする際に使用する名前を入力します。ユーザーの名前が分からない場合には空白のままにすることができ、（有効化されている場合には）アイデンティティボットがそのユーザーに名前を尋ねます。値を指定すると、アイデンティティボットはユーザーに再度名前を尋ねなくなります。 | 最大長は255文字です。これよりも長い値は切り捨てられます。 |
| userId | メールアドレスが提供されていない場合には必須の識別子となります | ユーザー固有の識別子です。ユーザーIDは一意である必要があります。異なるユーザーに同一のユーザーIDを使用させるべきではありません。 |
|
| userEmail | ユーザーIDが提供されていない場合には必須の識別子となります | ユーザーのメールアドレスです。ユーザーのメールアドレスが分からない場合には空白のままにすることができ、（有効化されている場合には）アイデンティティボットがそのユーザーにメールアドレスを尋ねます。値を指定すると、アイデンティティボットはユーザーに再度メールアドレスを尋ねなくなります。 |
|
| userAuthToken | オプション | SHA256を使用したハッシュベースのメッセージ認証コード（HMAC）を介して生成されたユーザー認証トークンです。第三者がユーザーに代わって問題を提出したり、ユーザーのプロパティを更新したりできないようにする場合には、HMACダイジェストを使用する必要があります。 詳細はこちら。 |
|
HelpshiftSdk.Login() APIを使用する際は、以下の点に注意する必要があります。-
- Helpshiftでログインユーザーを作成するには、
userIdまたはuserEmailのいずれかを使用する必要があります。 userIdまたはuserEmailは、すべてのアプリユーザーの間でユーザーを一意に識別する必要があります。2人以上の異なるユーザーが重複して使用するべきではありません。- Login APIが異なるユーザー識別子を用いて呼び出された場合には、最初に現在のログインユーザーをログアウトし、次にこのユーザー識別子を用いてログインを行います。
- アプリのユーザーがログインしたら、すぐにloginの呼び出しを行うのがベストです。
fullPrivacyをtrueに設定している場合、そのユーザーのLogin APIでメールアドレスを唯一の識別子として使うべきではありません。これを行うと、結果的に匿名ユーザーが作成されてしまいます。
10.3.0以降では、HelpshiftSdk.Login() APIはログインが成功したかどうかを示すブーリアン値を返します。この変更は既存のAPIにログインパラメーターに対する強制的な検証を導入するためのものであるため、コードのコンパイルに影響を与える可能性があります。
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はそのユーザーが匿名ユーザーであり、現在ログインしていないものとみなします。
複数のログインユーザー/匿名ユーザーが同じデバイスを使用してサポート会話中に情報のやり取りを行う（理想としてはログインをまたいだ共有を許可したくないない）ユースケースの場合には、_support.ClearAnonymousUserOnLogin(shouldClear)機能を使用する必要があります。
shouldClearが
trueの場合 – 匿名ユーザーは、どのユーザーがログインしても消去されます。一度消去されると、そういったユーザー（およびその会話）は二度と取得できなくなります。shouldClearが
falseの場合 – 匿名ユーザーのデータは保存され、ログインユーザーがログアウトすると、匿名ユーザーの会話履歴が表示されます。
help = HelpshiftSdk.GetInstance();
help.ClearAnonymousUserOnLogin(shouldClear);
ClearAnonymousUserOnLogin()機能は、ログインユーザーのエクスペリエンスには一切影響を与えません
ユーザーの同一性の確認
アプリ内で同一性の確認を構成する
概要
ユーザーの同一性の確認は、お客様のアプリから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 はユーザーによる問題の提出を阻止します。以下の場合、ユーザー認証トークン が無効である可能性があります。
|
| 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());