# 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:

1. [**User Identification**](/docs/for-developers/for-developers/sdk-guides/identify-users.md) **(`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"]]);
   ```
2. **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"]]);
   ```
3. **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 }]]);
   ```

{% hint style="warning" %}
When using the `set` attributes method, make sure it is executed **within the callback of the `do identify` method**. This ensures that the attributes are correctly linked to the intended user ID before being updated.

<pre class="language-javascript"><code class="lang-javascript"><strong>window.jimo.push(['do', 'identify', ['123456', () => {
</strong>    window.jimo.push(['set', 'user:name', ['John Doe']]);
    window.jimo.push(['set', 'user:email', ['john.doe@example.com']]);
}]);
</code></pre>

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#examples).
{% endhint %}

## Setup Custom Attributes

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

1. **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)
2. **Fetch User Data**
   * Fetch your user data that you want to use as custom attributes.
3. **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).

<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(...)`).&#x20;
  * **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.&#x20;

{% code fullWidth="false" %}

```javascript
// 1️⃣ Identify the user
window.jimo.push(["identify", {
  id: "user_12345"
}]);

// 2️⃣ Set default Jimo attributes
window.jimo.push(["set", "user", {
  name: "John Doe",
  email: "john.doe@email.com"
}]);

// 3️⃣ 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"
}]);
```

{% endcode %}

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.

```javascript
// Identify the user and assign key user attributes to Jimo
window['jimo'].push([
  'do',
  'identify',
  [
    "b7b8c565-65a0-4dbd-8438-3b8c8773f49f", // Unique User ID
    () => {
      window['jimo'].push([
        'set',
        'user:email',
        ["sam@example.com"] // Default Jimo attribute (User's email)
      ]);
      window['jimo'].push([
        'set',
        'user:name',
        ["Sam"] // Default Jimo attribute (User's name)
      ]);
      window['jimo'].push([
        'set',
        'core:language',
        ["en"] // Default Jimo attribute (User's preferred language)
      ]);
      window['jimo'].push([
        'set',
        'user:attributes',
        [
          {
            plan: "premium", // Custom attribute (Subscription plan)
            role: "admin", // Custom attribute (User role)
            last_activity: "2024-02-20T12:00:00Z", // Custom attribute (Last activity date)
            notifications_enabled: true, // Custom attribute (User's notifications status)
            browser: "Chrome", // Custom attribute (User's browser)
            timezone: "UTC+1" // Custom attribute (User's timezone)
          }
        ]
      ]);
    }
  ]
]);

```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.usejimo.com/docs/for-developers/for-developers/sdk-guides/setup-the-segmentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.