Skip to main content

Introduction

Record what your users and guests do, and turn it into personalized experiences.

More information about the module's user interface https://doc.oneentry.cloud/docs/category/useractivity

🎯 What does this module do?​

The UserActivity module lets you track activity events for the current user or guest - product views, page views, searches, cart and wishlist actions, purchases and ratings.

The events you send feed OneEntry's recommendation engine, which powers personalization blocks like personal recommendations, recently viewed, repeat purchase and trending.

🚀 Quickstart​

Initialize the module from defineOneEntry:


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

Record a product view event (works for an authorized user or a guest):

// Track that the visitor opened a product page.
const ok = await UserActivity.trackUserActivity({
  type: "product_view",
  productId: 12345,
  meta: { sourceBlock: "catalog" },
});

console.log(ok); // true on success

trackUserActivity() takes a single body object and resolves to true on success. It is fire-and-forget — don't block rendering on it.

✨ Key Concepts​

Works for users and guests​

Activity is tied to the current context: an authorized user (via the AuthProvider module) or a guest. For guests, the SDK sends an x-guest-id header so events are attributed to the right anonymous visitor. See Guest mode for details.

Event types​

The event type is one of a fixed set of values: product_view, page_view, category_view, search, product_add_to_cart, product_remove_from_cart, product_add_to_wishlist, product_remove_from_wishlist, product_purchase, product_rating.

📋 What You Need to Know​

  • Send the field that matches the action: include productId for product events, pageId for page/category views, and query for searches.
  • The meta field accepts arbitrary data (source block, A/B variant, scroll-depth) for your own analytics.
  • trackUserActivity() resolves to true on success - it is fire-and-forget and should not block the UI.

📊 Quick Reference Table​

MethodDescription
trackUserActivity()Record a user or guest activity event

❓ Common Questions (FAQ)​

Do I need to authorize the user to track activity?​

No. Activity is recorded for the current context - an authorized user or a guest. In the browser the SDK generates and persists a guest id automatically; on the server pass a per-visitor guestId.

What is the meta field for?​

meta is a free-form object for any extra information you want to attach to an event, such as the source block, an A/B test variant, or scroll depth.

🎓 Best Practices​

  • Track events as they happen, but don't block rendering on the network call.
  • Send productId / pageId / query that matches the event type.
  • Keep guest ids stable so a guest's activity is consistent across requests.

🔗 Related Documentation​