Ingest live data

Last updated:

Live data ingestion, opposed to historical data ingestions, is the process of sending events from your applications to PostHog in real-time; as they happen.

Live (real-time) events can be integrated using client libraries, server libraries, and third-party platform integrations.

The purpose of this guide is to help you understand some key concepts with a goal of ingesting live data into PostHog. For the purposes of the guide we'll focus on the client libraries as a means for data ingestion.

The guide covers the following:

If you prefer to learn by doing, you can get started on the web with the JavaScript snippet.

Install a library

Install the library for the platform you are building your application for.

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

<script>
!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
posthog.init('<ph_project_api_key>', {api_host: '<ph_instance_address>'})
</script>

Place the snippet in the <head> tags of your website, ideally just above the closing </head> tag. You will need to do this for all pages that you wish to track.

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("<ph_project_api_key>", {api_host: '<ph_instance_address>'});

If you don't want to send a bunch of test data while you're developing, you could do the following:

if (!window.location.href.includes('127.0.0.1')) {
posthog.init("<ph_project_api_key>", {api_host: '<ph_instance_address>'})
}

Autocapture

Autocapture is presently only available in the web browser using the JavaScript library. For non-browser platforms and for situations where you wish to manually capture events, see the capture user events section.

When you call posthog.init the PostHog JS library begins automatically capturing user 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

PostHog puts a great amount of effort into making sure it doesn't capture any sensitive data from your website. If there are other elements you don't want to be captured, you can add the ph-no-capture class name.

<button class='ph-no-capture'>Sensitive information here</button>

Capture user events

This allows you to send more context than the default event info that PostHog captures whenever a user does something. In that case, you can send an event with any metadata you may wish to add.

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

Identify 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]', // distinct_id, required
{ userProperty: 'value1' }, // $set, optional
{ anotherUserProperty: 'value2' } // $set_once, optional
);

You can also pass two more arguments to posthog.identify. Both take objects consisting of as many properties as you want to be set on that user's profile. The difference is that the second argument will use the $set mechanism, whereas the third argument will use $set_once.

You can read more about the difference between this in the setting properties section.

Warning! You can't call identify straight after an `.init` (as `.init` sends a pageview event, probably with the user's anonymous ID).

To address the issue described above, you can call .init passing a loaded callback function, inside which you can then call identify, like so:

posthog.init('[your api key]', {
api_host: 'https://posthog.[your-domain].com',
loaded: function(posthog) { posthog.identify('[user unique id]'); }
});