Sessions & User Identity

Sessions and user identity

Sessions provide the foundation for consistent personalization. By initializing a session, user interactions and recommendations can be linked to a stable identifier — enabling long-term analytics, segmentation, and CRM activation.

Initializing a session

Use initSession to establish a user identity at the start of each interaction.

mutation InitSession {
  initSession(
    userId: "4ad05833-01e9-412f-b6fd-a02c2ce1f7cd"
    timestamp: 1706000000
  ) {
    userId
    timestamp
  }
}

{
  "data": {
    "initSession": {
      "userId": "4ad05833-01e9-412f-b6fd-a02c2ce1f7cd",
      "timestamp": 1706000000
    }
  }
}

The returned userId and sessionId should be reused throughout the session and across subsequent API calls.

Why sessions matter

Sessions connect the dots between exploration, preference capture, and recommendations:

Recommendations improve over time — passing userId to recommendation queries lets the API learn from prior interactions
Preferences persist across sessions — the same userId links behavior across visits, devices, and channels
CRM activation — session data can be exported for email campaigns, lifecycle journeys, and segmentation

Anonymous vs identified users

You can initialize sessions with or without a known user identity:

Identified users: Pass your platform’s user ID (UUID, email hash, or CRM identifier) to link sessions to a known profile
Anonymous users: Generate a temporary identifier for the session. If the user later registers, you can re-initialize with their permanent ID to merge behavior

Using session data in queries

Once a session is initialized, pass the userId to queries that support personalization:

query PersonalizedRecommendations {
  recommendedPerfumes(
    userId: "4ad05833-01e9-412f-b6fd-a02c2ce1f7cd"
    search: { lang: "EN", perfumes: "424" }
  ) {
    id
    name
    brand {
      name
    }
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "734",
        "name": "HYPNOTIC POISON",
        "brand": {
          "name": "Dior"
        }
      },
      {
        "id": "36141",
        "name": "GUCCI GUILTY ABSOLU DE PARFUM POUR FEMME",
        "brand": {
          "name": "Gucci"
        }
      }
    ]
  }
}

See Recommendations for the full recommendation guide, and CRM & Personalization for how to extend sessions beyond the website.

Getting Started

Guides

API Reference

Sessions & User Identity

Sessions and user identity

Initializing a session

Why sessions matter

Anonymous vs identified users

Using session data in queries

​Sessions and user identity

​Initializing a session

​Why sessions matter

​Anonymous vs identified users

​Using session data in queries

Sessions and user identity

Initializing a session

Why sessions matter

Anonymous vs identified users

Using session data in queries