ユーザーアイデンティティと管理
SDKに含まれているすべてのパブリックAPIは、Helpshift installWithPlatformId APIを介してSDKを初期化した後に呼び出す必要があります
アイデンティティシステムによるユーザーの管理
アイデンティティシステムのセットアップにはある程度の開発労力が必要となりますが、コンテキスト収集の高速化、エージェントエクスペリエンスの簡素化、セキュリティの強化、スパムからの保護など、従来の方式に比べて多くのメリットがあります。
前提条件
- アイデンティティシステムがご利用のドメインで有効になっていることをご確認ください（有効化する場合には、Helpshiftのサポートまでお問い合わせください）
- Helpshift ダッシュボードで、秘密鍵があることを確認します。秘密鍵は、アプリの設定の「ユーザーアイデンティティ認証（新アイデンティティシステム）」セクションから生成することができます。
{" "}
- ユーザーJWTをオンデマンドで取得するためのエンドポイントが設定されていることをご確認ください。このエンドポイントは、上記の手順で生成した秘密鍵を使用してJWTに署名を行う必要があります。
エンドユーザーのログイン
新しいアイデンティティシステムを使用するには、以下の手順を実行する必要があります。
- 専用のエンドポイントから指定のユーザーのJWTを取得する
- JWTと全プライバシー情報を使用してユーザーをログインさせる
// Step 1: Get the JWT and and login config like full privacy flag.
String identitiesJWT = "<Your JWT token for identities>";
Map<String, Object> loginConfig = new HashMap<>();
loginConfig.put("full_privacy_enabled", false);
// Step 2: Call the loginWithIdentity API.
Helpshift.loginWithIdentity(identitiesJWT, loginConfig, new HelpshiftUserLoginEventsListener() {
@Override
public void onLoginSuccess() {
// Step 3: Handle login success.
Log.d(TAG, "onLoginSuccess: ");
}
@Override
public void onLoginFailure(String userLoginFailureReason, Map<String, String> map) {
// Step 4: Handle login failure. The reason and errors parameters
// provide more information on what exactly failed.
Log.d(TAG, "onLoginFailure: Login failed with reason " + userLoginFailureReason + ", errorData " + map);
}
});
Login APIのAPIシグネチャは、以下の通りです。
loginWithIdentity(
String identitiesJWT, (must be valid JWT)
Map<String, Object> loginConfig,
HelpshiftUserLoginEventsListener userLoginEventsListener
)
失敗の理由と利用可能な復旧手順については、ログイン失敗の理由セクションに記載されています。
アイデンティティトークンの形式
アイデンティティトークンは、ダッシュボードのアプリ設定にある共有シークレットを使用して署名されたJWTである必要があります。デコードする際は、以下のJSON形式を遵守してください。
{
"identities": [{
"identifier": "uid" | "email" | "phone_number" | "facebook_id" |
"discord_id"|"whatsapp_id"|"google_playstore_id"|
"apple_gamecenter_id" | "nintendo_id" | "psn_id" |
"xbox_live_id" | "steam_id"
"value": "string",
"metadata": {
"string": "string"
}
}],
"iat": // UNIX epoch time in seconds, generated in the last 24h or earlier
}
この契約ではidentitiesキーは配列の指定を想定しているため、アイデンティティオブジェクトを複数指定できることにご注意ください。
さらに、configのfull_privacy_enabledフラグの値に応じて以下のルールが適用されます。
- フルプライバシーフラグがfalseの場合、アイデンティティ配列にはuidかemailのいずれかが必須となります。
- フルプライバシーフラグがtrueの場合、アイデンティティキーは必須ではなくなります。ただし、uidキーの有無によって動作は変わります。
- uidが存在する場合 - SDKはユーザーの識別にuidを使用します。
- uidが存在しない場合 - SDKは匿名IDを生成し、このIDを使用してユーザーを識別します。
- 値が指定されていない場合、または渡された値がブール値のために解析できない場合、フルプライバシーはfalseとして見なされます。
JWTは常にサーバー側で生成し、共有シークレットは安全な場所で保管してください。
匿名ユーザーでのログイン
サポートエクスペリエンス全体の円滑化に役立つため、エンドユーザーはできる限り早期にHelpshiftにログインさせることをお勧めします。
しかしながら、匿名ユーザーがいる場合には空のJWT文字列を使用してログインするだけでHelpshiftが匿名UIDを生成し、エンドユーザーをログインさせます。
SDKは、空のJWTを渡す限り、複数回のログインにわたって同一の匿名ユーザーを維持するために最善を尽くします。一度空でないJWTを使用してログインすると既存の匿名ユーザーは失われ、次に空のJWTを使用してログインしたときに新しい匿名ユーザーが作成されます。
匿名ユーザーでログインした後、後からこのユーザーのアイデンティティをさらに追加することはできません。つまり、addUserIdentitiesAPIは現在のユーザーが匿名である場合には処理されません。
Login APIのベストプラクティス
- Login APIは、ユーザーがアプリにログインする際に一度呼び出します。アプリのフォアグラウンドや、アプリのサポートセクションを開く直前など、繰り返し発生するイベントに応じて呼び出すのは避けてください。
現在のログインユーザーに関連付けられるより多くの情報がある場合には、Login APIではなく
addUserIdentitiesAPIを使用します。Login APIを呼び出すと現在のユーザーはログアウトされ、新しいユーザーがログインします。 uidまたはemailは、すべてのアプリユーザーの間でユーザーを一意に識別する必要があります。2人以上の異なるユーザーが重複して使用するべきではありません。full_privacy_enabledをtrueに設定している場合、そのユーザーのLogin APIでemailを唯一の識別子として使うべきではありません。これを行うと、結果的に匿名ユーザーが作成されてしまいます。
ユーザーのログアウト
ユーザーがアプリからログアウトしたら、Logout APIを呼び出して他のユーザーがこのユーザーの会話を表示できないようにする必要があります。
Helpshift.logout();
セッションの期限切れによるログアウト
ユーザーのログアウトは、現在のユーザーのログインセッションが期限切れになったタイミングでSDK自体によりトリガーすることもできます。このログインセッションは、アプリのログインセッションから独立しています。このような場合、SDKはアプリがフォアグラウンドになるたびに即座にuserSessionExpiredイベントをアプリに送信します。このイベントに応じてバックエンドからアプリの現在のユーザーの新しいJWTを取得し、新しいJWTとログイン構成を使用してLogin APIを呼び出して、SDKの新しいログインセッションを開始する必要があります。ログインに成功すると、SDKはこのイベントの送信を停止します。
Helpshiftを使用してログインユーザーの認証情報を前もって更新し、セッションの有効期限が切れないようにする場合には、refreshUserCredentialsイベントをリッスンすることも可能です。このイベントは、セッションの期限が実際に切れるある程度前にSDKから送信されます。これにより、アプリに現在のユーザーを再ログインさせ、セッションを維持できるようになります。
これらのイベントの詳細については、デリゲートページをご参照ください。
ユーザーアイデンティティの更新
addUserIdentitiesAPIを使用して、ログインユーザーに関連付けられているアイデンティティを更新します。このAPIは、匿名でないログインユーザーのアイデンティティのみを更新します。現在のユーザーが空のJWTでログインしている場合（匿名ユーザー）、このAPIの処理は行われません。
Helpshift.addUserIdentities(identitiesJwt);
新しいアイデンティティのJWTは専用のエンドポイントから取得する必要があります。詳細については、このページの「前提条件」セクションをご確認ください。
このAPIは、既存のHelpshiftデリゲートシステムを活用してエラーが発生した際にアプリに通知を行います。このAPIでトリガーできるエラーイベントの詳細については、デリゲートページを参照してください。
ログイン失敗の理由
アイデンティティシステムのログインは、以下のいずれかの理由により失敗する場合があります。理由には、失敗の正確な原因を特定する際に役立つ関連エラーが含まれている場合があります。たとえば、アイデンティティJWTのキーが無効であることが失敗の原因である場合、エラー辞書には無効であることが明らかになった正確なキーが含まれます。このキーに対応する値は、失敗の原因を示しています（値が大きすぎる、値の型が対応していない、など）。
これらの失敗の理由の定数は、UserLoginFailureReasonファイルで定義されています。エラーの定数は、InvalidDataErrorReasonファイルで定義されています。
該当する場合、許容上限の最大値は以下のように定義されます。
- キーの長さ - 最大1000文字
- 値の長さ - 最大10,000文字
- コレクションのサイズ - 最大100エントリー
LOGIN_IN_PROGRESS
別のログイン要求がすでに進行中です
エラー - なし
LOGIN_CONFIG_INVALID
ログイン構成内の一部のキーまたは値が無効です
エラー -
| キー | 値 | リカバリー |
|---|---|---|
| 渡されたキーのいずれか1つ | EXCEEDED_KEY_LENGTH_LIMIT | キーの長さが許容範囲内であることをご確認ください |
| 渡されたキーのいずれか1つ | EXCEEDED_VALUE_LENGTH_LIMIT | 値の長さが許容範囲内であることをご確認ください |
| 渡されたキーのいずれか1つ | INVALID_VALUE_TYPE | 値が対応する型（文字列、ブール値、数値）のいずれかであることをご確認ください |
INVALID_IDENTITY_TOKEN
アイデンティティ JWTが有効な形式ではありません
エラー - なし
IDENTITIES_DATA_INVALID
JWTのペイロードのアイデンティティの一部が有効ではありません
エラー -
| キー | 値 | リカバリー |
|---|---|---|
| 渡されたアイデンティティキーのいずれか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 | メタデータのキーまたは値が空でない有効な値であることをご確認ください |
LOGIN_CONFIG_SIZE_LIMIT_EXCEEDED
ログイン構成のエントリーの数が許容上限を超えています
エラー - なし
IDENTITIES_SIZE_LIMIT_EXCEEDED
JWTのペイロードのアイデンティティの数が許容上限を超えています
エラー - なし
IDENTITY_FEATURE_NOT_ENABLED
ご利用のドメインでアイデンティティ機能が有効化されていません
エラー - なし
UID_OR_EMAIL_IS_MANDATORY
JWTのペイロードには、uidまたはemailのいずれかのアイデンティティが含まれている必要があります。両方のアイデンティティが含まれていても問題ありません。このルールの1つの例外は、ログイン構成でフルプライバシーがtrueに設定されている場合です。この場合、uidが含まれていなければSDKはユーザーに匿名IDを生成します。
エラー - なし
IAT_IS_MANDATORY
JWTにiatキーがありません。Issued At Timestampまたは"iat"は、JWTのペイロードの必須キーです。
エラー - なし
NETWORK_ERROR
ネットワークエラーによりログインに失敗しました
エラー - なし
UNKNOWN_ERROR
不明なエラーによりログインに失敗しました
エラー - なし