Skip to main content

Introduction

Manage registered users — fetch profiles, update data, and handle account state.

More information about user management in the OneEntry admin panel: https://doc.oneentry.cloud/docs/category/users

🎯 What does this module do?​

The Users module manages the already-authenticated user: fetch the profile, update form data and the custom state object, archive or delete the account, manage the per-user (or guest) cart and wishlist, and register FCM tokens for push notifications.

Registration and login are not here — they live in the AuthProvider module. The Users module works with the user that AuthProvider has already authorized.

🚀 Quickstart​

Initialize the module from defineOneEntry:


const { Users } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Fetch the current user and update their custom state object (assumes an authenticated session — see AuthProvider):

// Fetch the authorized user's profile and state.
const user = await Users.getUser("en_US");

console.log(user.id, user.identifier);

// Update the user, preserving existing state.
await Users.updateUser({
  formIdentifier: user.formIdentifier,
  formData: user.formData,
  state: { ...user.state, orderCount: (user.state.orderCount || 0) + 1 },
});

✨ Key Concepts​

What is a User?​

A User is a registered account in your application:

  • Identifier - login value (email, phone, or username)
  • Auth Provider - the authentication method used (authProviderIdentifier)
  • Form Data - profile fields defined by the registration form (formData)
  • Groups - array of group IDs the user belongs to
  • State Object - custom application data

User Structure​

Each user has this structure:

{
  id: 8,                                    // User ID
  identifier: 'test@test.ru',               // User identifier (email/login)
  authProviderIdentifier: 'email',          // Auth provider type
  formIdentifier: 'reg',                    // Registration form identifier
  formData: [                               // User profile data
    { marker: 'name_reg', type: 'string', value: 'Ivan' },
    { marker: 'phone_reg', type: 'string', value: '+19258382556' },
  ],
  groups: [1],                              // User groups for permissions
  state: {},                                // Custom application data
  moduleFormConfigs: [],                    // Additional form configurations
}

State Object​

You can store any application-specific data in the per-user state object. When you update the user, add the data you need to state; subsequent getUser() calls return it back.

Use CaseState ExampleDescription
E-commerce{ orderCount: 5, totalSpent: 499.99 }Track purchase history
Content{ articlesRead: 25, bookmarks: [1,2,3] }Track content consumption
Gaming{ level: 15, score: 9500, achievements: [...] }Track game progress
SaaS{ plan: 'premium', usage: 75 }Track subscription data

Always preserve existing state when updating — spread it so you don't drop other fields:

// ❌ Bad - overwrites the entire state
const state = { orderCount: 1 };

// ✅ Good - preserve existing state
const state = {
  ...user.state,
  orderCount: (user.state.orderCount || 0) + 1,
};

📋 What You Need to Know​

Authorization required​

Every user method requires an authorized session — authenticate the user first through the AuthProvider module. The cart and wishlist methods also work for guests (see the Cart & Wishlist section below).

User form data​

User profile data follows the forms configured in the OneEntry admin panel:

  • Each user has a formIdentifier that references the registration form used.
  • Profile fields live in the formData array as marker / type / value entries.
  • Supported field types include: string, integer, float, date, dateTime, time, text, textWithHeader, image, groupOfImages, file, radioButton, list, entity, timeInterval.

State object guidelines​

  • Store application-specific data only; don't put passwords, tokens, or card data in state.
  • Keep it organized with nested objects and consistent naming.
  • Update by spreading the existing state (see above) — never overwrite blindly.

Notification data​

When updating a user you can pass a notificationData object with delivery channels:

  • email - email address for notifications
  • phonePush - array of phone numbers for push notifications
  • phoneSMS - phone number for SMS notifications

Pagination​

For cart/wishlist lists and other collections, page through results rather than loading everything at once.

📊 Quick Reference Table​

MethodDescriptionUse Case
getUser() 🔐Get authorized user dataFetch current user profile
updateUser() 🔐Update user informationProfile updates, state changes
archiveUser() 🔐Archive user accountSoft delete user account
deleteUser() 🔐Permanently delete userHard delete user account
addFCMToken() 🔐Add FCM token for push notificationsEnable push notifications
deleteFCMToken() 🔐Remove FCM tokenDisable push notifications
getCart()Get the user's or guest's cartRead the current cart
setCart()Replace the whole cartSync a client-side cart
addCartItem()Add an item to the cart"Add to cart" action
removeCartItem()Remove an item from the cart"Remove from cart" action
getWishlist()Get the user's or guest's wishlistRead the current wishlist
setWishlist()Replace the whole wishlistSync a client-side wishlist
addWishlistItem()Add an item to the wishlist"Add to wishlist" action
removeWishlistItem()Remove an item from the wishlist"Remove from wishlist" action

🔐 marks methods that require an authorized user session (AuthProvider). The cart and wishlist methods also work for guests.

🛒 Cart & Wishlist​

The cart and wishlist methods work for both authorized users and guests. For a guest, the SDK sends an x-guest-id header so the cart/wishlist is tied to the right anonymous visitor - see Guest mode. Once a guest logs in, the same methods operate on the authenticated user's data.

These methods also feed the personalization blocks (such as cart complement, cart similar and wishlist similar) and can be combined with user activity tracking.

❓ Common Questions (FAQ)​

What is the user state object and how should I use it?​

The state object is a flexible JSON storage for application-specific user data. Use it to track custom metrics like order counts, preferences, or progress. Always spread existing state when updating to avoid overwriting other data.

How do I update user profile information?​

Use updateUser() to modify form data fields, notification settings, and the state object. Authenticate the user first via the AuthProvider module.

What's the difference between archiveUser() and deleteUser()?​

archiveUser() is a soft delete that marks the user for deletion but preserves data. deleteUser() permanently removes the user account. Use archiving unless you need complete data removal.

How do I handle push notifications for users?​

Use addFCMToken() to register a Firebase Cloud Messaging token for the user, enabling push notifications to their devices. Use deleteFCMToken() when they log out or disable notifications.

How do I fetch user data after registration?​

After successful registration and authentication via AuthProvider, call getUser() to fetch the authenticated user's profile and custom state object.

🎓 Best Practices​

  • Authenticate first - every user method requires an authorized session (see the AuthProvider module).
  • Preserve existing state - spread existing data when updating state.
  • Don't store sensitive data in state - keep passwords, tokens, and card data out of state.
  • Cache user data - reduce API calls for frequently accessed data.

🔗 Related Documentation​