> For the complete documentation index, see [llms.txt](https://help.usejimo.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.usejimo.com/docs/for-developers/for-developers/sdk-guides/setup-the-segmentation.md).

# Setup the segmentation

## Understanding User Attributes

User segmentation in Jimo allows you to display experiences, publish posts or target analytics based on specific user data. You can push attributes dynamically to personalize interactions and optimize engagement.

> As an example, you can publish a post for only new users or paying customers or any other custom data you find relevant to segment with.

Jimo supports three types of attributes:

{% stepper %}
{% step %}

### User Identification (`identify`)

Used to differentiate users by assigning them a unique `userId`.

Ensures each user is uniquely recognized across sessions and devices.

```js
window.jimo.push(['do', 'identify', ["123456"]]);
```

{% endstep %}

{% step %}

### Default Jimo Attributes (`user:email`, `user:name`, etc.)

Used to populate predefined user data fields in Jimo.

Can only update existing fields (e.g., name, email, language).

```js
window.jimo.push(["set", "user:name", ["John Doe"]]);
window.jimo.push(["set", "user:email", ["john.doe@example.com"]]);
```

{% endstep %}

{% step %}

### Custom Attributes (`user:attributes`)

Allows you to create your own fields and values to enhance segmentation.

Can store **strings**, **numbers**, **arrays**, and **booleans** (up to 700 characters per attribute).

```js
window.jimo.push(["set", "user:attributes", [{ plan: "Pro", isSubscribed: true }]]);
```

{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Order matters: push your** `set` **commands first, then finish with** `do identify`**.**

All commands are queued in the Jimo command buffer. When `identify` runs, the profile is initialized first, then the queued `set` commands are applied in order to the right user. This guarantees your attributes are correctly linked to the intended user ID.

```javascript
window.jimo.push(['set', 'user:name', ['John Doe']]);
window.jimo.push(['set', 'user:email', ['john.doe@example.com']]);
window.jimo.push(['do', 'identify', ['123456']]);
```

The older pattern that wraps `set` calls inside the `identify` callback still works for backward compatibility, but it is no longer recommended: buffered commands are applied in a more predictable order. For more details and best practices on identifying users, refer to the [Identify Users Documentation](/docs/for-developers/for-developers/sdk-guides/identify-users.md).
{% endhint %}

## Setup Custom Attributes

To start using custom attributes in segmentation, follow these steps:

{% stepper %}
{% step %}

### Load the Snippet

Make sure the snippet is loaded to your website. [Installation Instructions](https://help.usejimo.com/help-center/v/get-started/quick-start#sign-up-to-jimo)
{% endstep %}

{% step %}

### Fetch User Data

Fetch your user data that you want to use as custom attributes.
{% endstep %}

{% step %}

### Set Custom Attributes

Pass the data to Jimo by using the `window.jimo.push(["set", "user:attributes", [object, boolean /* refetchBoosted */] ])` method.

Note: The objects allowed in the custom attributes are only strings, numbers, arrays and booleans.

For more details on how to use the `setAttributes` SDK method, refer to [How to Use the Set Attributes SDK Method](https://help.usejimo.com/help-center/v/for-developers/for-developers/sdk-methods#change-user-attributes).
{% endstep %}
{% endstepper %}

<details>

<summary>Setup Custom Attributes <strong>via Google Tag Manager (GTM)</strong></summary>

The recommended approach is to use:

* GTM Variables to read user data (from the dataLayer, cookies, DOM, etc.)
* A GTM Custom HTML tag to push attributes to `window.jimo`

This setup works even if the Jimo script has not fully loaded yet, thanks to command buffering.

***

#### Prerequisites

Before starting, make sure that:

* Jimo is installed on your website (directly or via GTM)
* User data is available in GTM (for example via `dataLayer`)
* You know when user data becomes available (on page load, after login, etc.)

***

### Step 1. Create GTM Variables

In Google Tag Manager, create **Variables** for each field you want to send to Jimo.

Examples:

* `DLV - plan` (Data Layer Variable: `plan`)
* `DLV - isPaying` (Data Layer Variable: `isPaying`)
* `DLV - language` (Data Layer Variable: `language`)
* etc.

> You can also use Cookie / URL / DOM variables, anything GTM can resolve into `{{Some Variable}}`.

***

### Step 2. Create a GTM Trigger (when to send)

Common choices:

* **On login / user identified** (best)
* **On pageview** (works, but you might send anonymous/empty values)
* **On a custom dataLayer event**, e.g. `jimo_user_ready` (most robust)

**Best practice** is a custom event, because you control the moment the user data is actually available.

The cleanest approach is to push user data into the `dataLayer` when it is ready. Example:

```js
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: "jimo_user_ready",
  email: "a@b.com",
  name: "Ada",
  plan: "pro",
  isPaying: true,
  language: "fr"
});
```

This custom event will be used as the GTM trigger.

***

### Step 3. Create a "Custom HTML" tag that pushes to Jimo

In GTM go to **Tags → New → Custom HTML** and create a **Custom HTML** tag in GTM and paste the following code:

```html
<script>
(function () {
  // Make sure the buffer exists (safe even if Jimo hasn't loaded yet)
  window.jimo = window.jimo || [];

  // 1) Identify fields (optional but common)
  var email  = "{{DLV - email}}";
  var name   = "{{DLV - name}}";

  // Only push if values are present (avoid polluting with empty strings)
  if (email)  window.jimo.push(["set", "user:email", [email]]);
  if (name)   window.jimo.push(["set", "user:name", [name]]);

  // 2) Attributes object
  var attrs = {
    plan: "{{DLV - plan}}",
    language: "{{DLV - language}}"
  };

  // Convert booleans/numbers if your GTM variables return strings
  var isPayingStr = "{{DLV - isPaying}}";
  if (isPayingStr !== "" && isPayingStr !== undefined) {
    attrs.isPaying = (isPayingStr === true || isPayingStr === "true");
  }

  // Remove empty attributes (optional cleanup)
  Object.keys(attrs).forEach(function (k) {
    if (attrs[k] === "" || attrs[k] === undefined) delete attrs[k];
  });

  // Push attributes to Jimo
  window.jimo.push(["set", "user:attributes", [attrs]]);

  // If you want Jimo to refetch boosted posts after updating attributes:
  // window.jimo.push(["set", "user:attributes", [attrs, { refetchBoosted: true }]]);
})();
</script>
```

***

### Step 4. Configure the trigger

Attach the tag to a **Custom Event trigger**:

* Trigger type: Custom Event
* Event name: `jimo_user_ready`

This ensures attributes are sent only when user data is available.

***

### Best practices

* **Timing:** If your variables are only known after login, don't fire on "All Pages", fire on the login success event (or your `jimo_user_ready` event).
* **Types:** GTM often injects values as strings. If you care about booleans/numbers in segmentation, cast them (as in the snippet).
* **Don't send empty strings:** Jimo will receive them as real values; better to delete empties before pushing.
* **Safe before load:** Jimo's snippet pattern is built around buffering (`window.jimo = []` then `push(...)`).
  * **Attributes can be updated at any time**, calling `user:attributes` again will overwrite previous values.

</details>

#### Example Code

Here's an example of setting custom attributes and using them for segmentation:

```javascript
// Example 1: Set the attribute foo and bar
window.jimo.push([ "set", "user:attributes", [ {foo : "hello", bar: "world" } ] ])

// Example 2: Set the attribute foo and bar and refetch boosted posts
window.jimo.push([ "set", "user:attributes", [ {foo : "hello", bar: "world" }, true ]])
```

{% hint style="success" %}

#### Understanding Segmentation

Setting custom attributes is only the first step. This custom data can be reused to segment users effectively, allowing for more personalized interactions. To understand how segmentation works and how to leverage custom data for creating segments, check out [How Segmentation Works](https://help.usejimo.com/help-center/v/using-jimo/users-and-segments/segments).
{% endhint %}

## Why Use Custom Attributes?

Jimo provides default attributes (e.g., name, email, language, and activity data), but these are **limited to basic user metadata and activity tracking only on pages where Jimo is installed**.

**However, real-world segmentation often requires custom data from your own infrastructure** to define specific groups of users based on internal business logic and Jimo doesn't automatically have access to deeper user data that might be critical for **targeting**, **personalization**, or **monitoring**.

#### Why Extend Jimo's Default Attributes?

✅ **Better Targeting & Personalization**\
Jimo can only segment users based on **what it knows**, such as experience interactions or basic identity. However, businesses often need **specific conditions based on internal user data**, like:

* Subscription plans (Free, Pro, Enterprise)
* Internal permissions (Admin, Editor, Viewer)
* Last purchase date or engagement scores

By pushing these attributes, you can create tailored experiences for different user cohorts.

✅ **Flexible Segmentation Based on Business Data**\
Jimo can only track events from **when it was installed**. This means:

* If a user signed up **before Jimo was implemented**, there's no record of their signup date unless you push it as an attribute.
* If you want to filter users based on **payment history**, Jimo cannot access your billing system, but you can push a `last_payment_date` attribute.
* Jimo can track **the last time a user visited a page**, but if you want to track **feature usage** or customer lifecycle stages, pushing custom attributes is necessary.

✅ **Improved Debugging & Monitoring**\
If you need **better insights into technical issues**, attributes like:

* **Device & OS:** Helps debug experience rendering issues.
* **Browser type:** Identifies compatibility problems.
* **Time zone & localization:** Ensures experiences are displayed at the right time and in the correct language.

✅ **Differentiate Workflows & User Configurations**\
Not all users have the same setup. If your product has multiple workflows or permissions, pushing attributes like:

* **Enabled features (A/B tests, beta access)**
* **User-defined settings (e.g., dark mode, accessibility preferences)**
* **Region-specific conditions (e.g., compliance restrictions, geofencing)**

… can ensure that Jimo experiences adapt dynamically to different users.

## Recommended Attributes

Here are key **custom attributes** that we recommend setting up to **extend segmentation and personalize experiences**:

### 1. User Profile & Subscription Details

These attributes help define **who** the user is within your system.

| **Attribute Name** | **Example Values**                | **Use Case**                                |
| ------------------ | --------------------------------- | ------------------------------------------- |
| `plan`             | `"Free"`, `"Pro"`, `"Enterprise"` | Target features based on subscription level |
| `user_role`        | `"Admin"`, `"Editor"`, `"Viewer"` | Adjust permissions for team members         |
| `permissions`      | `["edit", "publish"]`             | Enable/disable specific actions per user    |

### 2. Engagement & Activity Tracking

Jimo tracks activity **only after installation**, pushing internal data allows for more precise user tracking, on events prior to Jimo install.

| **Attribute Name** | **Example Values**         | **Use Case**                                        |
| ------------------ | -------------------------- | --------------------------------------------------- |
| `signup_date`      | `"2023-06-01T00:00:00Z"`   | Target only users who signed up before/after a date |
| `last_active_days` | `15`                       | Segment inactive users for re-engagement            |
| `feature_usage`    | `["dashboard", "reports"]` | Trigger hints based on feature adoption             |

### 3. Technical & Debugging Information

These attributes improve **monitoring and troubleshooting**.

| **Attribute Name** | **Example Values**      | **Use Case**                                |
| ------------------ | ----------------------- | ------------------------------------------- |
| `browser`          | `"Chrome"`, `"Firefox"` | Debug experience display issues             |
| `os`               | `"Windows"`, `"MacOS"`  | Identify OS-specific rendering problems     |
| `timezone`         | `"UTC+2"`               | Optimize scheduling for experience delivery |

### 4. Localization & User Preferences

Ensure experiences are **personalized** based on user settings.

| **Attribute Name**      | **Example Values**  | **Use Case**                              |
| ----------------------- | ------------------- | ----------------------------------------- |
| `language`              | `"fr"`, `"en"`      | Serve experiences in the correct language |
| `notifications_enabled` | `true/false`        | Enable/disable push notifications         |
| `preferred_theme`       | `"light"`, `"dark"` | Adjust UI preferences dynamically         |

***

#### Example Code

Once you've defined which attributes to push, implement them using the **Jimo SDK**:

```javascript
// Assign key user attributes to Jimo
window.jimo.push(["set", "user:attributes", [{
  plan: "Pro",
  user_role: "Admin",
  last_active_days: 15,
  browser: "Chrome",
  os: "Windows"
}]]);
```

Here's a **fully integrated example** of how to set up user identification, assign default Jimo attributes, and push custom attributes for advanced segmentation. Queue everything first, then finish with `identify`: all commands are buffered and applied in order once the profile is initialized.

```javascript
// 1️⃣ Set default Jimo attributes
window.jimo.push(['set', 'user:name', ['John Doe']]);
window.jimo.push(['set', 'user:email', ['john.doe@email.com']]);
window.jimo.push(['set', 'core:language', ['en']]);

// 2️⃣ Set custom attributes for segmentation
window.jimo.push(['set', 'user:attributes', [{
  plan: "Pro",
  user_role: "Admin",
  permissions: ["edit", "publish"],
  signup_date: "2023-06-01T00:00:00Z",
  last_active_days: 12,
  browser: "Chrome",
  os: "MacOS",
  timezone: "UTC+2",
  notifications_enabled: true,
  preferred_theme: "dark"
}]]);

// 3️⃣ Identify the user (always last)
window.jimo.push(['do', 'identify', ['user_12345']]);
```

This script should be added **after Jimo is loaded** on your website or app **where your users login** to ensure users are properly identified and categorized for targeted experiences.