User Identifier & Properties

User Identifier Management

User Identifiers are used to uniquely identify users. For information about the meaning and importance of User Identifiers, and how to choose them, refer to the Manage User Identifiers documentation.

For functions that change user information (setUser, setUserId, setDeviceId, updateUserProperties, resetUser, and so on), we recommend using the variants that take a callback.

The callback is invoked after the changed user information has been applied to the SDK.

User Identifier

Default Identifiers Provided by Hackle

The Android SDK includes functionality to manage the device's identifier. Therefore, users can be automatically identified without separately providing a User Identifier.

You can query the identifiers managed by the SDK as follows.

Kotlin

// Get the device ID
val deviceId = hackleApp.deviceId

// Get the session ID
val sessionId = hackleApp.sessionId

// Get all user information
val user = hackleApp.user

Java

// Get the device ID
String deviceId = hackleApp.getDeviceId();

// Get the session ID
String sessionId = hackleApp.getSessionId();

// Get all user information
User user = hackleApp.getUser();

Modify Device ID

You can inject a custom device ID instead of using the device ID provided by Hackle.

Kotlin

// Change the device ID
hackleApp.setDeviceId("CUSTOM_DEVICE_ID") {
    // Applied
}

// Using the builder pattern
val user = User.builder()
    .deviceId("CUSTOM_DEVICE_ID") // Device ID
    .build()

hackleApp.setUser(user) {
    // Applied
}

Java

// Change the device ID
hackleApp.setDeviceId("CUSTOM_DEVICE_ID", () -> {
    // Applied
});

Set User Identifier (User ID)

You can set the identifier for a logged-in user.

Kotlin

// Add the logged-in user ID
hackleApp.setUserId("LOGIN_ID") {
    // Applied
}

// Using the builder pattern
val user = User.builder()
    .userId("LOGIN_ID") // User ID
    .build()

hackleApp.setUser(user) {
    // Applied
}

Java

// Add the logged-in user ID
hackleApp.setUserId("LOGIN_ID", () -> {
    // Applied
});

Additional Identifiers

You can add identifier types other than the default identifiers (deviceId, userId) as follows.

Additional identifiers are not integrated with the Hackle ID.

Calling setUser overwrites the current device's user information.

• If you are currently using userId A and call setUser without passing userId A, the userId changes from A to null.

• If you are currently using a custom deviceId and call setUser without passing the current deviceId, the custom deviceId reverts to the Hackle deviceId.

• If you use additional identifiers and do not pass them when calling setUser, the additional identifiers are reset.

• For properties, the cached properties on the device may be retained or reset in the following cases:

  • If the userId and deviceId are the same before and after setUser, cached properties are retained.

  • If the userId or deviceId changes before and after setUser, cached properties are deleted.

Kotlin

import io.hackle.sdk.common.User

val user = User.builder()
    .userId("143")                   // User ID (Hackle ID can be used)
    .deviceId("ae2182e0")            // Device ID (Hackle ID can be used)
    .identifier("myCustomId", "42")  // Custom ID
    .build()

hackleApp.setUser(user) {
    // Applied
}

Java

import io.hackle.sdk.common.User

User user = User.builder()
    .userId("143")                   // User ID (Hackle ID can be used)
    .deviceId("ae2182e0")            // Device ID (Hackle ID can be used)
    .identifier("myCustomId", "42")  // Custom ID
    .build();

hackleApp.setUser(user, () -> {
    // Applied
});

User Property

The Hackle SDK supports adding user properties.

• Properties must be sent as key-value pairs (Property Key and Property Value).

• A maximum of 128 properties can be added.

Category	Type	Constraints
Property Key	string	Character limit is 128 characters. Case-insensitive. For example, AGE and age are recognized as the same Property Key.
Property Value	boolean, string, number, array	For string type, the character limit is 1024 characters. String type is case-sensitive. For example, APPLE and apple are recognized as different Property Values. For number type, up to 15 integer digits and up to 6 decimal places are supported.

Add User Property

You can add a user property simply by adding it with set on a PropertyOperations object and then calling updateUserProperties.

The setUserProperty function is deprecated as of Android SDK 4.0.0. Use updateUserProperties instead.

Kotlin

import io.hackle.sdk.common.PropertyOperations

// Set a property
val operations = PropertyOperations.builder()
    .set("gender", "female")
    .build()

hackleApp.updateUserProperties(operations) {
    // Applied
}

Java

import io.hackle.sdk.common.PropertyOperations;

// Set a property
PropertyOperations operations = PropertyOperations.builder()
    .set("gender", "female")
    .build();

hackleApp.updateUserProperties(operations, () -> {
    // Applied
});

Configure User Properties

You can add or remove user properties.

Supported Functions	Description
set	Sets a User Property. If a Property Value already exists for the Property Key, it is overwritten.
setOnce	Sets a User Property value only once. If a property already exists for the Property Key, it is ignored. For example, you can use this to set a user's registration date or initial sign-up location.
unset	Removes a User Property.
clearAll	Removes all User Properties.

Instantiate a PropertyOperations object with the user properties you want to configure. Then call updateUserProperties to update the user properties. You can configure multiple properties at once.

Kotlin

import io.hackle.sdk.common.PropertyOperations

// Set properties
val operations = PropertyOperations.builder()
    .set("age", 42)
    .set("grade", "GOLD")
    .setOnce("sign_up_date", "2020-07-03")
    .build()

hackleApp.updateUserProperties(operations) {
    // Applied
}

// Clear properties
val clearOperations = PropertyOperations.clearAll()

hackleApp.updateUserProperties(clearOperations) {
    // Applied
}

Java

import io.hackle.sdk.common.PropertyOperations;

// Set properties
PropertyOperations operations = PropertyOperations.builder()
    .set("age", 42)
    .set("grade", "GOLD")
    .setOnce("sign_up_date", "2020-07-03")
    .build();

hackleApp.updateUserProperties(operations, () -> {
    // Applied
});

// Clear properties
PropertyOperations clearOperations = PropertyOperations.clearAll();

hackleApp.updateUserProperties(clearOperations, () -> {
    // Applied
});

Reset User

You need to reset the previously configured information. When reset, all previously configured identifiers and properties are cleared.

Resetting the user also clears all user properties stored on the server. If you want to handle logout, use hackleApp.setUserId(null).

Setting null to userId handles logout on the client side.

hackleApp.resetUser {
    // Applied
}