Note: Please note that this feature is available by default in SDK version 10.4.0 or higher. If you want your users to be identified, make sure to use this feature. Otherwise, issues will be created with users being anonymous.

User Identity Verification flow

Why Set Up User Identity Verification?

Configuring User Identity Verification in the new identity system (User Hub) provides a robust framework for managing user authentication and data integrity. Here’s why implementing this system is essential:

• Implement mandatory User Identity Verification to prevent unauthorized access and mass data modification using leaked email databases.
• Enforce a database check from the brand for identity verification to verify actual user identity against stored data and prevent exploitation through forged identity tokens.
• Implement full UID verification for all identities to verify and sign all identity types to prevent impersonation across multiple identities.
• Secure data transmission post-authentication to prevent modification of user data after login to ensure data integrity.

What does it look like to my end users?

Once this feature is enabled, your users will have the following experience based on their verification status:

• If a user isn’t verified, they won’t be logged in. Instead, they will be treated as an anonymous user, and no authentication failed screen will be shown.
• Verified logged-in users will see their previous Issues and have the ability to create new Issues. (This is applicable for both iOS, Android, and Web Chat).
   
• For Webchat, if a user isn’t verified, they won’t be logged in, and the authentication failed screen will be shown.
   

How to Setup User Identity Verification?

Step 1: Generate your Secret Key

Contact your Helpshift Admin to generate the Secret key as shown below.

Step 2: Retrieve your Secret Key

To access your secret key as generated by a “Helpshift Admin,” follow these steps:

1. Navigate to the settings ( ) page.
2. Scroll down to App Settings.
3. Select the app for which you’d like to configure User Identity Verification for the New ID system.
4. The secret key will be available on this page.
   
5. Click the Copy button to copy this secret key for use in your endpoint.

For security reasons, the secret key should not be placed anywhere an end user or third party can access it.

Note: Always generate the JWT on the server side and store your shared secret securely.

Step 3: Setup the Endpoint

Now that you have the secret key, you should use it in your endpoint to pass the JWT (JSON Web Token) to your iOS app, Android app, or Web Chat widget.

The identity token must be a JWT signed using the shared secret from your app settings in the dashboard. This secret key generation can be done as part of the normal login process.

The secret key should not be present on the user’s device to prevent disclosure.

Notes on generating the JWT:

• If the User ID and/or Email ID are available, the JWT must be generated with the User ID and/or Email ID.
• In addition to the User ID and/or Email ID, you may also include other identifiers such as Phone Number, Facebook ID, Discord ID, WhatsApp ID, Google Play Store ID, Apple Game Center ID, Nintendo ID, PlayStation ID, Xbox Live ID, and Steam ID as part of the Identities payload in the JWT.
• The following JSON format must be used to generate the JWT:
  

  {
    "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
  }

Note: User ID and/or Email ID must be passed.

Troubleshooting Tips

If you encounter errors while testing User Identity Verification, review the following troubleshooting tips:

• The JWT is generated using a shared secret key. If the JWT is absent, users will not be identified, and all interactions will be treated as anonymous.
• When a session expires, Helpshift SDK/ Webchat will programmatically prompt the brand to re-login the user with a new JWT. This typically occurs once a month or if Helpshift detects any suspicious activity.
• Ensure that your JWT endpoint:
  • Generates tokens in the accepted format
  • Signs tokens with the shared secret
  • Includes an iat (issued_at_time) value that is not older than 24 hours
• If you are caching the JWT, ensure you do not cache it for longer than 24 hours.

Code Samples

You can refer to the following code samples when configuring your endpoint:

Python

import jwt
import time

def generate_jwt(secret, user_email=None, user_id=None):
    iat = int(time.time())
    identities = []

    if user_id:
        identities.append({
            "identifier": "uid",
            "value": user_id
        })

    if user_email:
        identities.append({
            "identifier": "email",
            "value": user_email
        })

    payload = {
        "iat": iat,
        "identities": identities
    }

    # Generate the JWT token using HS256 algorithm
    token = jwt.encode(payload, secret, algorithm='HS256')
    return token

Javascript

const jwt = require('jsonwebtoken');

function generateJWT(secret, userEmail, userId) {

    // Issued At (current timestamp in seconds)
    const iat = Math.floor(Date.now() / 1000);
    const identities = [];

    if (userId) {
        identities.push({
            identifier: "uid",
            value: userId
        });
    }

    if (userEmail) {
        identities.push({
            identifier: "email",
            value: userEmail
        });
    }

    const payload = {
        iat,
        identities
    };
    const token = jwt.sign(payload, secret, { algorithm: 'HS256' });
    return token;
}

Java

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.Claims;

import java.util.ArrayList;
import java.util.List;
import java.util.HashMap;
import java.util.Map;

public class JAVA {

    public static String generateJWT(String secret, String userEmail, String userId) {
        // Issued At (current timestamp in seconds)
        long iat = System.currentTimeMillis() / 1000;
        List<Map<String, String>> identities = new ArrayList<>();

        // Add user information to the identities list if available
        if (userId != null) {
            Map<String, String> userIdInfo = new HashMap<>();
            userIdInfo.put("identifier", "uid");
            userIdInfo.put("value", userId);
            identities.add(userIdInfo);
        }

        if (userEmail != null) {
            Map<String, String> userEmailInfo = new HashMap<>();
            userEmailInfo.put("identifier", "email");
            userEmailInfo.put("value", userEmail);
            identities.add(userEmailInfo);
        }

        Map<String, Object> payload = new HashMap<>();
        payload.put("iat", iat);
        payload.put("identities", identities);

        // Generate the JWT token
        return Jwts.builder()
                .setClaims(payload)
                .signWith(SignatureAlgorithm.HS256, secret)
                .compact();
    }
}

Step 4: Configure your iOS App / Android App / Web Chat Widget

Once you’ve configured the endpoint to generate a JWT, you’ll need to configure Identity Verification in your iOS, Android, and Web Chat code. To complete this step, see our developer documentation on Identity Verification for iOS, Android, and Web Chat.

Steps to Test Your Implementation

Prerequisite: Ensure that the user is logged in using the Identities API and that JWT is implemented as described above.

1. Open the chat.
2. Start a conversation.
3. Confirm that the issue appears in the Helpshift dashboard.
4. Verify that the identities passed at the start of the conversation are correctly reflected on the Issue in the User Panel.

Now, you are ready to use User Identity Verification.