Setting up User Identifiers and Properties

User Identifiers or User IDs

User identifiers or user IDs are used to accurately identify and track different unique users.
For information on the meaning, importance, and selection criteria of user identifiers, please refer to the previous Managing User Identifiers document.

How Hackle SDK assigns user IDs

There are two ways Hackle’s SDK processes different user IDs.
The first method is through using device identifiers used by users managed internally by the SDK. This method automatically identifies users through internally managed device identifiers. The second method is through using custom identifiers. This is a method of directly passing a user identifier as a parameter. The identifier delivered can be a directly managed primary key, device identifier, member ID, email, hash value, etc. The example code for creating custom identifiers is provided at the bottom of this page.

Using device identifiers managed internally by SDK

🚧

Available for client-side SDK only.

The client-side SDK includes the ability to manage device identifiers internally. Users are automatically identified through internally managed device identifiers.

Using (your own) custom identifiers

This is a method of directly passing a user identifier as a parameter. The identifier delivered can be a directly managed primary key, device identifier, member ID, email, hash value, etc.

  • Example code to create a custom identifier is provided at the bottom of this article.

Setting User IDs in Client-side SDK

There are two ways to create user IDs while using the Client-side SDK

1. Using device identifiers managed internally by the SDK

The client-side SDK includes functionality to manage device identifiers. Therefore, the user can be identified automatically without passing the user identifier separately.
For Android and iOS, you can get the user/device identifier managed by the SDK. Please refer to the example code below.

// Traffic distribution to different test groups
const experimentKey = 42
const variation = hackleClient.variation(experimentKey)

// Send user event
hackleClient.track("purchase")

// Retrieve device IDs managed internally 
const userId = Hackle.getUserId()
// Traffic distribution to different test groups
int experimentKey = 42;
Variation variation = hackleApp.variation(experimentKey);

// Send user event
hackleApp.track("purchase");

// Retrieve device IDs managed internally 
String deviceId = hackleApp.getDeviceId();
// Traffic distribution to different test groups
let variation = hackleApp.variation(experimentKey: 42)

// Send user event
hackleApp.track(eventKey: "purchase")

// Retrieve device IDs managed internally 
let deviceId = hackleApp.deviceId
<HackleProvider hackleClient={hackleClient}>
  <YourApp />
</HackleProvider>

2. Using customized identifiers

The SDK identifies the user through the identifier received through the parameter. Hence, the User Identifier is completely customizable depending on the key you send to Hackle. The identifier delivered can be a directly managed primary key, device identifier, member ID, email, hash value, etc.

// Traffic distribution to different test groups
const experimentKey = 42;
const user = { id: "ae2182e0" };
hackleClient.variation(experimentKey, user);

// Send user event 
hackleClient.track("purchase", user);
// Traffic distribution to different test groups
long experimentKey = 42L;
String userId = "ae2182e0";
Variation variation = hackleApp.variation(experimentKey, userId);

// Send user event 
hackleApp.track("purchase", userId);
// Traffic distribution to different test groups
let variation = hackleApp.variation(experimentKey: 42, userId: "ae2182e0")

// Send user event 
hackleApp.track(eventKey: "purchase", userId: "ae2182e0")
const user = { 
    id: "ae2182e0"
}

<HackleProvider hackleClient={hackleClient} user={user}>
  <YourApp />
</HackleProvider>

Setting User IDs in Server-side SDK

Server-side SDK cannot automatically identify specific users, which means that you will always need to manually set and send custom identifiers as different parameters to Hackle.

// Traffic distribution to different test groups
long experimentKey = 42L;
User user = User.of("ae2182e0");
Variation variation = hackleClient.variation(experimentKey, user);

// Send user event
hackleClient.track("purchase", user);
# Traffic distribution to different test groups
uesr = Hackle.user('ae2182e0')
variation = hackle_client.variation(experiment_key=42, user=user)

# Send user event
event = Hackle.event(key='purchase')
hackle_client.track(event=event, user=user)
// Traffic distribution to different test groups
const experimentKey = 42;
const user = { id: "ae2182e0" };
hackleClient.variation(experimentKey, user);

// Send user event
hackleClient.track("purchase", user);
// Traffic distribution to different test groups
$experimentKey = 42;
$userId = 'ae2182e0'
$variation = $hackleClient->variation($experimentKey, $userId);

// Send user event
$hackleClient->track('purchase', $userId);
# Traffic distribution to different test groups
user = Hackle.user(id: 'ae2182e0')
variation = hackle_client.variation(experiment_key: 42, user: user)

# Send user event
event = Hackle.event(key: 'purchase')
hackle_client.track(event: event, user: user)

Example: Creating a custom user ID

If you only need the data from your logged-in users, the member ID or email address used for login can be used as the identifier.

However, in cases where you need to include non-login users, it is recommended that you use a value that can be distinguishable based on the app, device, or browser. (UUID or ADID value for mobile app, cookie value for PC/Mobile web)

Below is an example of generating a user identifier based on a cookie.

import Cookies from "js-cookie"
import uuid4 from "uuid4"
function getUserId() {
  const key = "PCID" // Enter desired name
  const id = Cookies.get(key)
  if (id) {
    return id
  } else {
    const id = uuid4()
    const [top, second] = window.location.hostname.split(".").reverse()
    const domain = `.${second}.${top}`
    Cookies.set(key, id, { expires: 99999, domain: domain, path: "/" })
    return id
  }
}

Property

The SDK supports adding properties to user objects. By sending user-specific information as user properties, you can reduce repetitive code work while also leveraging them in A/B testing and data analytics in various ways.

A property must be sent as a pair of property name (key) and property value (value).
The maximum number of properties that can be added to a user object is 64.

Property name (key)

It is recommended to make it easy to identify like a general variable name. The character limit is 64 characters, and it is case-insensitive. For example, "AGE" and "age" are recognized as the same property name.

Property value (value)

Boolean, string, and number types are supported as property values. For string type, the character limit is 64 characters, and it is case-sensitive. For example, "APPLE" and "apple" are recognized as different property values. For the number type, it supports a maximum of 15 digits for integers and a maximum of 6 digits for decimals.

Example

The user object is used as a parameter in test group distribution, feature flag determination, and user event transmission. In the example below, you can see that three properties (age, grade, is_paying_user) have been added.

User user = User.builder(userId)
    .property("age", 30)
    .property("grade", "GOLD")
    .property("is_paying_user", false)
    .build();
    
// Traffic distribution to test groups 
Variation variation = hackleApp.variation(experimentKey, user);

// Feature flag determination
boolean featureOn = hackleApp.isFeatureOn(featureKey, user);

// Send user events 
hackleApp.track(event, user);
val user = Hackle.user(userId) {
    property("age", 30)
    property("grade", "GOLD")
    property("is_paying_user", false)
}
    
//  Traffic distribution to test groups 
val variation = hackleApp.variation(experimentKey, user)

// Feature flag determination
val featureOn = hackleApp.isFeatureOn(featureKey, user)

// Send user events 
hackleApp.track(event, user)