# User Identity

When a user logs in or logs out of the application, please ensure the corresponding event is synchronized with AIHelp to confirm or reset the user's identity.

Note

Please make sure the userId you pass to AIHelp via the API is a unique and valid value.

Setting userId to invalid values such as an empty string (""), "null", 0, or -1 may cause malfunctions in the customer support functionality.

# API

When a user logs into the application, synchronize their user ID with AIHelp so that AIHelp can generate a valid identity token for them.

AIHelpSupport.login("THIS IS YOUR USER ID");

Or use LoginConfig for additional configuration:

LoginConfig loginConfig = new LoginConfig.Builder()
        .setUserId("THIS IS YOUR USER ID")
        .setUserConfig(...)
        .build();
AIHelpSupport.login(loginConfig);

# logout()

When a user logs out, call this method to clear the current user session information to ensure the accuracy of the guest identity after logout.

AIHelpSupport.logout();

# Events

You can listen for the USER_LOGIN event to monitor the user's login status:

AIHelpSupport.registerAsyncEventListener(EventType.USER_LOGIN,
        new AsyncEventListener() {
            @Override
            public void onAsyncEventReceived(String jsonData, Acknowledgment ignored) {
                // `jsonData`: { "code": 1, "message": "Success" }
            }
        }
);

The possible values for code in jsonData are:

1: Login successful;
-1: Invalid user ID;
-2: Login failed. See the message field for more details.

# Enterprise Authentication

When Enterprise Authentication is enabled in the AIHelp admin panel, calling the login API will trigger the ENTERPRISE_AUTH event.

You need to listen for this event and handle the user authentication logic yourself, then return the user identity information to AIHelp via the ack callback method.

AIHelpSupport.registerAsyncEventListener(EventType.ENTERPRISE_AUTH, (ignored, ack) -> {
    new AuthJobThread((authResult) -> {
        ack.acknowledge("{'token':'your async token'}");
    }).start();
});

For compatibility, return the data to AIHelp in JSON format. The user token must be stored in the token field.

# Parameter Explanation

# loginConfig

Type: LoginConfig
Description: Required. Configuration wrapper for optional login parameters.

# userId

Type: String
Default value: Random device-generated ID
Description: Required. Unique user identifier. Cannot be an empty string, 0, or -1.

# userConfig

Type: UserConfig
Default value: null
Description: Optional. User information configuration, including username, server ID, user tags, and other custom data. In addition to the login process, you can also call updateUserInfo API separately to update user information.

Example usage:

UserConfig userConfig = new UserConfig.Builder()
        .setUserName("AIHelper")
        .setServerId("s-101")
        .setUserTags("vip1,suggestion")
        .setCustomData("{'total_recharge': 10000, 'level': 34}")
        .build();

LoginConfig loginConfig = new LoginConfig.Builder()
        .setUserId("THIS IS YOUR USER ID")
        .setUserConfig(userConfig)
        .build();

AIHelpSupport.login(loginConfig);

# Others

# Enterprise Authentication Flow

To maximize security, you can handle user identity authentication logic on your own server — known as Enterprise Authentication.

Enterprise authentication is a server-side verification process; the SDK and game client do not hold any secret keys.

The sequence of enterprise authentication is as follows:

Enable enterprise authentication and obtain the secret key from the AIHelp admin panel:
The client calls the SDK login API;
The SDK triggers the Enterprise Authentication event, and the client receives a callback. Then it sends a request to the game server to verify the player's identity;
The client receives the server's response and returns the token issued by the server to the SDK via the ack callback inside the enterprise authentication event;
The SDK uses the received token to request the AIHelp server. The server will verify the token:
- For verified users, AIHelp will mark them as authenticated in the backend and allow normal login;
- For unverified users, depending on whether Force Authentication is enabled, AIHelp will:
  - Block the login request and return a failure response to prevent further unauthorized requests;
  - Mark the user as unauthenticated in the backend without affecting their ability to submit support tickets.

# Token Generation Rules

During the enterprise authentication process, you need to obtain the secret key from AIHelp and issue a token for the user on your server, based on the following rules:

Use the secret key provided by AIHelp, available in Backend Settings - App Settings - Auth Secret Key;
Use the HS256 signing algorithm; a recommended token validity period is 24 hours;
Generate a standard-format JWT, with the following claims:

{
    "exp": 1718868267, // Expiration timestamp (in seconds)
    "iat": 1718781867, // Issued-at timestamp (in seconds)
    "nbf": 1718781867, // Not-before timestamp (in seconds)
    "iss": "xxxx", // Custom issuer
    "jti": "947b3086-9aad-40d8-b5cf-752c9294f392" // UUID
}

sub (required): Unique user identifier, same as the userId used in the login API
iss (required): Recommended to use your company's English name or abbreviation
jti (required): Recommended to use a UUID
exp (required): Expiration timestamp (in seconds), recommended to set to current time + 24 hours
iat (optional): Issued-at timestamp (in seconds), set to current time
nbf (optional): Not-before timestamp (in seconds), recommended to set to current time

You can refer to the sample code we provide (opens new window) for token generation and validation.

← Help Center User Info →