User Identification & Management

Note

All the public APIs in the SDK should be called after initializing the SDK via install API

How to Identify and Manage Users

Logging in users

Overview

A logged-in user is someone who can contact your support team only after providing a username and password. If you have logged-in users, we highly recommend passing the user's identifiers (user ID and/or email) using the Login API so that your Agents can provide a personalized support experience to your users. Using the Login API also ensures that a user's conversations are available only to them when they log in.

Note

User's conversation will only be available on the device used to start the conversation. The conversation will not be available across devices.

What to provide as identifiers

You can provide either userId and/or userEmail to identify your users. We highly recommend using a user ID to identify your users. However, if you use emails to identify your users, then you should pass them in the userEmail field as a map in the HelpshiftCocos2dx::login(cocos2d::ValueMap userData) API. The following logic applies when you use both userId as well as userEmail:

• When looking up users, the priority of userId is higher than that of userEmail
• When the user ID matches an exisiting user, that user's email will be updated (if the email is provided)
• When the email matches an existing user, the following logic applies:
  • If the user ID does not exist for a user matched by email, then the user ID will be added for that user (if a user ID is provided)
  • If the user ID already exists on the user matched by email, then a new user will be created (if a different user ID is provided)

How to use

You should call Helpshift SDK's Login API whenever the user successfully logs into your app. The Login API takes the following parameters:

Parameter	Require/Optional	SDK Description	Important Considerations
userName	Optional	Provide the name you'd like your Agents to use when interacting with end users. If you don't know the user's name, you can leave it blank, and the Identity Bot (when enabled) will ask that user for their name. If you provide a value, the Identity Bot will not ask the user for their name again.	Max length: 255 characters. Values larger than this will be truncated. If the value of userName is empty string, after trimming spaces, then do not include this parameter in "login" call.
userId	Required as an identifier if email is not provided	A user's unique identifier. User IDs must be unique. You should not use the same user ID for different users.	Leading / trailing spaces are not allowed. Spaces in between are allowed. User IDs with leading / trailing spaces will result in the creation of an anonymous user. User ID is always case-sensitive (eg. '1abc' is different from '1ABC'). Do not provide the user's email address as 'userId'. If you use email addresses to identify users, provide them as 'userEmail'. If you are using the user ID as well as email, ensure that the User ID is present in subsequent calls - just providing email will return any profile if multiple profiles have the same email. If the value of "userId" is empty string, after trimming spaces, then do not include this parameter in "login" call.
userEmail	Required as an identifier if the user ID is not provided	A user's email address. If you don't know the user's email, you can leave it blank and the Identity Bot (when enabled) will ask the user for their email. If you provide a value, then the Identity Bot will not ask the user for their email again.	Email format should be valid (should be in the format "my@email.com"). Invalid emails will result in the creation of an anonymous user. Leading / trailing spaces are not allowed. Emails with leading / trailing spaces will result in the creation of an anonymous user. Email is always case insensitive (eg. 'MY@EMAIL.COM' is same as 'my@email.com'). If the value of "userEmail" is empty string, after trimming spaces, then do not include this parameter in "login" call.
userAuthToken	Optional	A user authentication token generated via Hash-Based Message Authentication Code (HMAC) using SHA256. You should provide an HMAC Digest if you want to ensure that 3rd parties cannot file issues on behalf of your users or update their properties. Details here.	A valid HMAC Digest should be provided in order to ensure your users can file issues. Details here. If the value of "userAuthToken" is empty string, after trimming spaces, then do not include this parameter in "login" call.

You need to be aware of some considerations when using the HelpshiftCocos2dx::login() API -

• In order to create a logged-in user in Helpshift, the use of either userId or userEmail is required.
• The userId or userEmail should uniquely identify the user across all users of your app. It should NOT be duplicated for two or more different users.
• If the login API is called with different user identifier, then it first logs out the currently logged-in user and then logs in with this user identifier.
• It is best to call login immediately when your app user logs in.
• If you are setting fullPrivacy to true, you shouldn't use email as the only identifier in the login API for that user. This will result in the creation of an anonymous user.

Note

• From 10.3.0, HelpshiftCocos2dx::login() API will return a boolean indicating whether login was successful or not. This change in existing API is to introduce mandatory validations for login parameters and hence this might affect code compilation.

Example:

cocos2d::ValueMap userData;

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

if (userId.empty() && userEmail.empty())
{
    cocos2d::log("userId and userEmail both are empty. Invalid login!");
    return;
}

if (!userId.empty())
{
    userData["userId"] = cocos2d::Value(userId);
}

if (!userEmail.empty())
{
    userData["userEmail"] = cocos2d::Value(userEmail);
}

if (!userName.empty())
{
    userData["userName"] = cocos2d::Value(userName);
}

std::string userAuthToken = generateUserAuthToken();
if (!userAuthToken.empty())
{
    userData["userAuthToken"] = cocos2d::Value(userAuthToken);
}

bool isLoginSuccess = HelpshiftCocos2dx::login(userData);

Logging out users

Overview

Once a user logs out from your app, you should call the Helpshift SDK logout API to ensure no one else can view this user's conversations.

Note

• The logout API is expected to be used in conjunction with the login API.

Example:

HelpshiftCocos2dx.logout();

Anonymous users

Overview

An anonymous user is someone who can access the app without a username and password. If a user identifier (user ID and/or email) is not passed via the login API, then Helpshift assumes that the user is an anonymous user and is not currently logged in.

If your use case involves multiple logged-in/anonymous users using the same device and discussing info during support conversations (which you ideally wouldn't want to be shared across logins), you should use the HelpshiftCocos2dx::clearAnonymousUserOnLogin(bool clearAnonymousUser) API.

• If clearAnonymousUser is true – anonymous users are cleared whenever any user logs in. Once cleared, such users (and their conversations) cannot be fetched again.

• If clearAnonymousUser is false – anonymous user data will be saved and if a logged-in user is logged out, you will see anonymous user’s conversation history.

Note

The clearAnonymousUserOnLogin() API does not impact the logged-in user's experience at all.

Example:

HelpshiftCocos2dx::clearAnonymousUserOnLogin(bool clearAnonymousUser);

Verifying the identity of users

Configuring identity verification in your app

Overview

User Identity Verification is a security measure that verifies that all requests made from your app to Helpshift are coming from authentic end users. This prevents 3rd parties or hackers from impersonating your users. You can learn more about User Identity Verification and the steps to configure it here. In order to ensure your users are verified, you should provide a 'user authentication token' with the userData map in the HelpshiftCocos2dx::login(cocos2d::ValueMap userData) API at the time of initialization. You can find the steps to generate a 'user authentication token' here. The 'user authentication token' is an HMAC Digest, which is generated via HMAC using SHA256.

Sending the HMAC Digest to verify users' identity

You can send the 'user authentication token' with the Login API call. If Identity Verification is enabled on the Helpshift Dashboard (documentation here), Helpshift recalculates the unique 'user authentication token' using the shared secret key, and compares the 'user authentication token' sent by you to the recalculated value. If they're equal, then the user's identity is verified, and they are able to file Issues.

Note

• If the secret key is regenerated for an app on the Dashboard, you should ensure that you update your endpoint code as well, in order to generate a valid 'user authentication token'. After this, your Admins should delete the old secret key from the Dashboard in order to ensure requests using a 'user authentication token' generated using the old secret key become invalid.
• If you are setting fullPrivacy flag to true, the 'user authentication token' should be generated only on the user ID.

Example:

cocos2d::ValueMap userData;

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

if (userId.empty() && userEmail.empty())
{
    cocos2d::log("userId and userEmail both are empty. Invalid login!");
    return;
}

if (!userId.empty())
{
    userData["userId"] = cocos2d::Value(userId);
}

if (!userEmail.empty())
{
    userData["userEmail"] = cocos2d::Value(userEmail);
}

if (!userName.empty())
{
    userData["userName"] = cocos2d::Value(userName);
}

std::string userAuthToken = generateUserAuthToken();
if (!userAuthToken.empty())
{
    userData["userAuthToken"] = cocos2d::Value(userAuthToken);
}
HelpshiftCocos2dx::login(userData);

Identity Verification Failure

Overview

When Identity Verification is turned 'On' and a login request is made with no 'user authentication token' or with an invalid 'user authentication token', identity verification will fail. If identity verification fails, the following will hold true:

• Anonymous users (users for whom the developer is not providing any identifiers) are always able to file Issues.
• Logged-in users (users for whom the developer is providing an identifier such as user ID or email) will not be able to file Issues or see conversations if they are unverified. Unverified logged-in users will see an error on the form or conversational UI.

If the logged-in users are verified (i.e., a valid 'user authentication token' is provided), they are able to see the previous Issue or create a new Issue. The UI for verified, logged-in users looks & works exactly the same as it would if 'Identity verification' were turned off. Only unverified users get impacted as listed above.

How to use the failure delegates

If identity verification fails, the SDK will invoke the authenticationFailed delegate to notify the application of the failure:

Authentication failure reason	When is it called	When to use
HSAuthenticationFailureReason .HSAuthTokenNotProvided	When no 'user authentication token' is provided	If you do not plan on sending a 'user authentication token' when implementing SDK, but plan on implementing it in the future, you can use this failure delegate to show your own alerts to the user, such as a prompt to update the app. You may want to use this if you are using the login API without the 'user authentication token', since these users will be considered unverified once 'Identity Verification' is enabled on the Dashboard. Using this delegate is completely optional - Helpshift will prevent unverified users from being able to file Issues, as mentioned previously.
HSAuthenticationFailureReason .HSInvalidAuthToken	When the 'user authentication token' is invalid	If the HMAC Digest being provided via LoginAPI is invalid, then Helpshift will prevent the users from filing Issues. The 'user authentication token' can be invalid if: You made a programming error. Check how to generate HMAC Digest here. You regenerated the secret key on the Dashboard, but didn't update the 'user authentication token'. A 3rd party is trying to make requests. When the 'user authentication token' is invalid, end-users will not able to file Issues and an error is shown to them, as mentioned previously. You can use this delegate if you want to show your own alerts or re-fetch the correct auth token from your server.

The authentication failure reason is wrapped in an enum HSAuthenticationFailureReason.

Example:

void handleHelpshiftEvent(const char *eventName, cocos2d::ValueMap &eventData) {
    // handle Helpshift events
    ...
}
void handleAuthFailureEvent(HSAuthenticationFailureReason reason) {
    if (reason == HSAuthenticationFailureReason::HSAuthTokenNotProvided) {
        ...
    } else if (reason == HSAuthenticationFailureReason::HSInvalidAuthToken) {
        ...
    }
}
HelpshiftCocos2dx::setHelpshiftEventsListener(handleHelpshiftEvent,
                                                  handleAuthFailureEvent);

Testing & Troubleshooting

Steps to test that Identity Verification is correctly set up are available here.