Capturing events

Last updated:

|Edit this page

Once your PostHog instance is up and running, the next step is to start sending events.

You can send custom events using capture:

Web
posthog.capture('user_signed_up');

Tip: We recommend using a [object] [verb] format for your event names, where [object] is the entity that the behavior relates to, and [verb] is the behavior itself. For example, project created, user signed up, or invite sent.

Setting event properties

Optionally, you can also include additional information in the event by setting the properties value:

Web
posthog.capture('user_signed_up', {
login_type: "email",
is_free_trial: true
})

Page views and autocapture

By default, PostHog automatically captures the following frontend events:

  • Pageviews, including the URL.
  • Autocaptured events, such as any click, change of input, or submission associated with a, button, form, input, select, textarea, and label tags.

If you prefer to disable these, set the appropriate values in your configuration options.

Single-page apps and pageviews

PostHog automatically sends pageview events whenever it gets loaded. If you have a single-page app, that means it only sends a pageview once (when your app loads).

To make sure any navigating a user does within your app gets captured, you can make a pageview call manually.

Web
posthog.capture('$pageview')

This automatically sends the current URL along with other relevant properties.

Event ingestion

It's a priority for us that events are fully processed and saved as soon as possible. Typically, events will be usable in queries within a few minutes.

Advanced: Anonymous vs identified events

PostHog captures two types of events: anonymous and identified

Identified events enable you to attribute events to specific users, and attach person properties. They're best suited for logged-in users.

Scenarios where you want to capture identified events are:

  • Tracking logged-in users in B2B and B2C SaaS apps
  • Doing user segmented product analysis
  • Growth and marketing teams wanting to analyze the complete conversion lifecycle

Anonymous events are events without individually identifiable data. They're best suited for web analytics or mobile apps where users aren't logged in.

Scenarios where you want to capture anonymous events are:

  • Tracking a marketing website
  • Content-focused sites
  • B2C apps where users don't sign up or log in

Under the hood, the key difference between identified and anonymous events is that for identified events we create a person profile for the user, whereas for anonymous events we do not.

💡 Tip: Under our current pricing, anonymous events can be up to 4x cheaper than identified ones (due to the cost of processing them), so it's recommended you only capture identified events when needed.

How to capture anonymous events

PostHog captures identified events by default. To change this and capture anonymous events, change the person_profiles config when initializing PostHog:

  1. person_profiles: 'always' (default) - Capture identified events for all events.

  2. person_profiles: 'identified_only' (recommended) - Anonymous events are captured by default. PostHog only captures identified events for users where person profiles have already been created.

For example:

Web
posthog.init(
'<ph_project_api_key>',
{
api_host: 'https://us.i.posthog.com',
person_profiles: 'identified_only'
}
)

How to capture identified events

Identified events are captured by default if you've set the person_profiles config to always (the default option).

If you've set the person_profiles to identified_only, anonymous events are captured by default. Then, to capture identified events, call any of the following functions:

When you call any of these functions, it creates a person profile for the user. Once this profile is created, all subsequent events for this user will be captured as identified events.

Questions?

Was this page useful?

Next article

Creating insights

Insights are the main building blocks of product analytics. They enable you visualize your events and actions and analyze how people use your products. Types of insight Trends Trends enable you to track how metrics change over time and use formulas to create custom metrics. Funnels Use funnels to understand conversion between steps, identify possible causes of success or failure, and track how conversion changes over time. Retention Retention insights enable you to see how often users…

Read next article