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.

Think of it as the analytics signal behind personalization - the events you send feed OneEntry's recommendation engine, which powers blocks like personal recommendations, recently viewed, repeat purchase and trending.

📖 Simple Explanation​

Every time a visitor does something meaningful, you record an event:

  • 👀 Product view - the visitor opened a product page
  • 📄 Page / category view - the visitor browsed a page or category
  • 🔎 Search - the visitor searched for something
  • 🛒 Cart / wishlist actions - items added or removed
  • 💰 Purchase - the visitor bought a product
  • ⭐ Rating - the visitor rated a product

OneEntry uses this stream of events to understand each visitor and personalize what they see.

✨ 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 event 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.

Definition of the UserActivity module​


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

🔗 Related Documentation​