posthog-js

What is posthog-js?

The posthog-js npm package is a JavaScript library for integrating PostHog analytics into web applications. It allows you to track user interactions, capture events, and analyze user behavior in real-time.

What are posthog-js's main functionalities?

Initialization

Initialize the PostHog library with your API key and optional configuration settings.

const posthog = require('posthog-js');
posthog.init('YOUR_API_KEY', { api_host: 'https://app.posthog.com' });

Capture Events

Capture custom events with properties to track user interactions and behaviors.

posthog.capture('event_name', { property1: 'value1', property2: 'value2' });

Identify Users

Identify users with unique IDs and associate them with properties like email and name.

posthog.identify('user_id', { email: '[e-mail]', name: 'John Doe' });

Set User Properties

Set properties for identified users to enrich user profiles with additional information.

posthog.people.set({ property1: 'value1', property2: 'value2' });

Feature Flags

Check if a feature flag is enabled for the current user to implement feature toggling.

const isEnabled = posthog.isFeatureEnabled('feature_flag_key');

Other packages similar to posthog-js

mixpanel-browser

Mixpanel is a powerful analytics tool that offers similar functionalities to PostHog, such as event tracking, user identification, and property setting. Mixpanel also provides advanced features like A/B testing and user segmentation.

amplitude-js

Amplitude is an analytics platform focused on product intelligence. It offers event tracking, user identification, and behavioral analytics. Amplitude provides advanced features like cohort analysis and user journey mapping, which can be more detailed than PostHog's offerings.

README

PostHog.js

This library allows you to capture events and send those to any PostHog instance.

Installation

You can either load the snippet as a script in your HTML:

<script src="https://t.posthog.com/static/array.js"></script>
<script>
    posthog.init("[your-token]")
</script>

Or you can include it using npm, by doing either

yarn add posthog-js

or

npm install --save posthog-js

And then include it in your files

import { posthog } from 'posthog-js';
posthog.init("[your-token]");

Usage

Sending events

By default, PostHog captures every click on certain elements (like a, button, input etc.) and page views. However, if it's often worth sending more context whenever a user does something. In that case, you can send an event with any metadata you may have.

posthog.capture('[event-name]', {property1: 'value', property2: 'another value'});

Identifying users

To make sure you understand which user is performing actions within your app, you can identify users at any point. From the moment you make this call, all events will be identified with that distinct id.

The ID can by anything, but is usually the unique ID that you identify users by in the database. Normally, you would put this below posthog.init if you have the information there.

If a user was previously anonymous (because they hadn't signed up or logged in yet), we'll automatically alias their anonymous ID with their new unique ID. That means all their events from before and after they signed up will be shown under the same user.

posthog.identify('[user unique id]');

Sending user information

An ID alone might not be enough to work out which user is who within PostHog. That's why it's useful to send over more metadata of the user. At minimum, we recommend sending the email property, which is also what we use to display in PostHog.

You can make this call on every page view to make sure this information is up-to-date. Alternatively, you can also do this whenever a user first appears (afer signup) or when they change their information.

posthog.people.set({email: '[e-mail]'});

One-page apps and pageviews

This JS snippet automatically sends pageview events whenever it gets loaded. If you have a one-page app that means it'll only send 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.

posthog.capture('$pageview');

This will automatically send the current URL.

Complete signup psuedocode

As an example, here is how to put some of the above concepts together.

function signup(email) {
    // Your own internal logic for creating an account and getting a user_id
    let user_id = create_account(email);

    // Identify user with internal ID
    posthog.identify(user_id);
    // Set email or any other data
    posthog.people.set({email: email});
}

Development

To develop, clone the repo and run

yarn start

To create a minified production version, run

yarn build

Contributions

Contributions are very welcome! Please open a PR and we'll review it asap. If you have any questions, please shoot an email to [e-mail].