Skip to main content

Users

Fetch and update registered users and manage their account state.

More information about user management in the OneEntry admin panel: https://doc.oneentry.cloud/docs/category/users (opens in a new tab)

The Users module works with a user who is already authenticated through the AuthProvider module, which handles registration and login. It fetches the profile, updates form data and the custom state object, archives or deletes the account, manages the user's (or a guest's) cart and wishlist, and registers FCM tokens for push notifications.

Quickstart​

Initialize the module from defineOneEntry:


const {  } = defineOneEntry(
  , {
    
  }
);

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

// Fetch the authenticated user's profile and state.
const user = await Users.getUser("en_US");
if ('statusCode' in user) throw new Error(user.message);

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

// Update one state key. Other state keys and form fields stay as they are.
await Users.updateUser({
  formIdentifier: user.formIdentifier,
  state: { orderCount: Number(user.state.orderCount ?? 0) + 1 },
});

User object​

A user is a registered account in your application:

  • identifier: the login value (email, phone, or username).
  • authProviderIdentifier: the authentication method used.
  • formData: profile fields defined by the registration form.
  • groups: IDs of the groups the user belongs to.
  • state: custom application data.
{
  id: 8,                                    // User ID
  total: '1',                               // Internal row count, always '1'; ignore
  identifier: 'john@example.com',           // User identifier (email/login)
  authProviderIdentifier: 'email',          // Auth provider type
  formIdentifier: 'reg',                    // Registration form identifier
  formData: [                               // User profile data
    { marker: 'name_reg', type: 'string', value: 'John' },
    { marker: 'phone_reg', type: 'string', value: '+12025550147' },
  ],
  groups: [1],                              // User groups for permissions
  state: {},                                // Custom application data
  rating: {},                               // User rating (IRating)
  moduleFormConfigs: [],                    // Additional form configurations
}

State object​

The per-user state object holds any application-specific data. updateUser() merges what you pass into the stored object, and later getUser() calls return it.

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

updateUser() merges state into the stored object at the top level: keys you send overwrite the stored ones, keys you omit are kept, and a key set to null is removed. Nested objects are replaced as a whole, not merged, so send the full nested value when you change part of it.

const user = await Users.getUser("en_US");
if ('statusCode' in user) throw new Error(user.message);

// Other keys in state stay as they are
await Users.updateUser({
  formIdentifier: user.formIdentifier,
  state: { orderCount: Number(user.state.orderCount ?? 0) + 1 },
});

// Removes promoCode from state
await Users.updateUser({
  formIdentifier: user.formIdentifier,
  state: { promoCode: null },
});

Reading state, changing a value and writing it back isn't atomic: two updates sent at the same time can overwrite each other, and a counter like orderCount can lose an increment. Keep values that must be exact, such as order counts, on your server.

Keep state for application data only. Don't put passwords, tokens, or card data in it. Organize it with nested objects and consistent naming.

Authentication​

All methods except the cart and wishlist ones need an authenticated session, so sign the user in through the AuthProvider module first. The cart and wishlist methods also work for guests (see Cart and wishlist below).

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.
  • Field types include string, integer, float, date, dateTime, time, text, textWithHeader, image, groupOfImages, file, radioButton, list, entity and timeInterval.

Use updateUser() to change form data fields, notification settings, and the state object.

Notification data​

updateUser() also accepts a notificationData object with delivery channels:

  • email: email address for notifications.
  • phonePush: FCM device tokens registered for push notifications. addFCMToken() and deleteFCMToken() maintain this list.
  • phoneSMS: phone number for SMS notifications.

updateUser() replaces notificationData as a whole, and the object must include both email and phonePush. getUser() doesn't return notificationData, so you can't read the registered tokens back: omit notificationData unless your app keeps the full list of FCM tokens itself, or the tokens added with addFCMToken() are lost.

To send push notifications to a user's devices, register a Firebase Cloud Messaging token with addFCMToken(), and remove it with deleteFCMToken() when the user logs out or turns notifications off.

Archiving vs. deleting​

archiveUser() is a soft delete: it marks the user for deletion but keeps the data. deleteUser() removes the account permanently.

Methods​

MethodDescriptionUse Case
getUser() 🔐Fetch the authenticated userFetch 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
getUsersByVectorSearch() 🔐Semantic (vector) search for usersFind users by meaning, not keywords

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

Cart and wishlist​

The cart and wishlist methods work for both authenticated users and guests. For a guest, the SDK sends an x-guest-id header so the cart or wishlist is tied to the right anonymous visitor; see Guest mode. The guest id must be a UUID v4 (for example, from crypto.randomUUID()). The API replaces any other value with a new random id on every request, so the guest's cart, wishlist and activity don't persist. A guest's cart is kept for 30 days after its last change, and a guest's wishlist for 90 days. 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). Adding or removing a product also records the matching product_add_to_cart, product_remove_from_cart, product_add_to_wishlist or product_remove_from_wishlist activity event (a quantity change alone records nothing), so you don't need to track these yourself.