PostHog

Step-by-step guide to send event data from RudderStack to PostHog.

PostHog is a complete product analytics stack built for data analysts and managers. It gives you easy access to scalable product analytics with full control over all your user data.

RudderStack supports PostHog as a destination to which you can seamlessly send your event data for analytics.

Find the open-source transformer code for this destination in our GitHub repository.

Getting started

Before configuring PostHog as a destination in RudderStack, verify if the source platform is supported by PostHog by referring to the table below:

Connection Mode	Web	Mobile	Server
Device Mode	Supported	-	-
Cloud Mode	Supported	Supported	Supported

To know more about the difference between cloud mode and device mode in RudderStack, refer to the RudderStack Connection Modes guide.

Once you have confirmed that the source platform supports sending events to PostHog, follow these steps:

1. From your RudderStack dashboard, add the source. Then, from the list of destinations, select PostHog.

2. Assign a name to your destination and click on Next.

Connection settings

To successfully configure PostHog as a destination, you will need to configure the following settings:

• Team API Key: Enter your PostHog team API key. This is a mandatory field.

For more information on obtaining your PostHog Team API Key, refer to the FAQ section below.

The settings are listed below:

• Instance URL: Enter your PostHog instance URL.

If you’re hosting your own PostHog instance, add the URL of your instance without the trailing slash. So, the URL will look something like https://[your-instance].com.

• Use updated mapping for Group calls: Enable this setting to send the group traits as event properties to PostHog.

For more information, refer to the Updated group mapping section below.

Web SDK settings

This section lists some of the other configurable settings when sending events to PostHog via the web device mode.

• Use device mode to send events: If enabled, RudderStack will send the events to PostHog via the device mode.
• Enable Local Storage for Persistence: Enable this option to reduce the amount of data stored in the cookies by storing it locally instead.

• Enable autocapture with PostHog: Enable this option to allow PostHog to send auto-captured events.
• Allow PostHog to automatically capture pageview events: Enable this setting to allow the PostHog web SDK to send a page view event every time it is loaded on a page.

• Disable session recoding: Enable this setting to stop PostHog from recording the user sessions.

For more information on PostHog's session recording feature, refer to the PostHog documentation.

• Additional headers to pass with XHR requests to PostHog API: Add a list of key-value pairs in this field. The RudderStack web SDK will then forward these headers on the event requests sent to PostHog.

• Property black list - Add a list of traits or event properties that you want the PostHog SDK to filter.

Identify

To identify a user in PostHog, you need to call RudderStack's identify API.

For information on the identify call, refer to the RudderStack API Specification guide.

A sample identify call is as shown below:

rudderanalytics.identify("1hKOmRA4el9Zt1WSfVJIVo4GRlm", {
  name: "Alex Keener",
  first_name: "Alex",
  last_name: "Keener",
  email: "[e-mail]",
  createdAt: "2019-07-23T23:45:56.000Z",
})

RudderStack passes the user traits within the identify call to PostHog under the $set key according to the PostHog Identify API.

Page

The page call lets you record your app's page views with any additional relevant information about the viewed page.

For information on the page call, refer to the RudderStack API Specification guide.

A sample page call is shown below:

rudderanalytics.page({
  path: "/best-seller/1",
  url: "https://www.estore.com/best-seller/1",
  title: "EStore Bestsellers",
  search: "estore bestseller",
  referrer: "https://www.google.com/search?q=estore+bestseller",
})

In the above example, RudderStack captures information related to the viewed page such as its path, URL, referrer, etc.

For the page call, RudderStack sends $pageview as an event to PostHog according to the PostHog Page API.

Screen

The screen call lets you record whenever your user views their mobile screen with any additional relevant information about the screen.

For information on the screen call, refer to the RudderStack API Specification guide.

A sample screen call using RudderStack's iOS SDK is shown below:

[[RudderClient sharedInstance] screen:@"Home Screen"
            properties:@{@"category" : @"launcher"}];

In the above snippet, RudderStack captures information related to the viewed screen such as its name and category.

For the screen call, RudderStack sends $screen as an event to PostHog according to the PostHog Screen API.

Track

The track call lets you capture user events along with the properties associated with them.

For information on the track call, refer to the RudderStack API Specification guide.

A sample track call is shown below:

rudderanalytics.track("Order Completed", {
  checkout_id: "C324532",
  order_id: "T1230",
  value: 15.98,
  revenue: 16.98,
  shipping: 3.0,
  coupon: "FY21",
  currency: "INR",
  products: [
    {
      product_id: "product-mixedfruit-jam",
      sku: "sku-1",
      category: "Food",
      name: "Food/Drink",
      brand: "Sample",
      variant: "None",
      price: 10.0,
      quantity: 2,
      currency: "INR",
      position: 1,
      value: 6.0,
      typeOfProduct: "Food",
      url: "https://www.example.com/product/bacon-jam",
      image_url: "https://www.example.com/product/bacon-jam.jpg",
    },
  ],
})

PostHog supports the RudderStack track call as typecapture. and sends the user action as an event to PostHog according to the PostHog Capture API.

Group

The group call lets you associate a particular identified user with a group, such as a company, organization, or an account.

For information on the group call, refer to the RudderStack API Specification guide.

A sample group call is shown below:

rudderanalytics.group("sample_group_id", {
  name: "CompanyA",
  location: "USA",
})

The group call sends $group as an event to PostHog according to the PostHog Group API.

Updated group mapping

RudderStack lets you use the updated mapping feature for the group calls where it maps the group traits as event properties before sending them to PostHog. To use this feature, enable the Use Updated Mapping for Group calls setting in the RudderStack dashboard, as shown:

When disabled (default), RudderStack sends the group traits to PostHog as received without any modifications, as shown in the following snippet:

{
  "version": "1",
  "type": "REST",
  "method": "POST",
  "endpoint": "https://app.posthog.com/batch",
  "headers": {
    "Content-Type": "application/json"
  },
  "params": {},
  "body": {
    "JSON": {
      "groupId": "groupId27",
      "distinct_id": "sampleusrRudder7",
      "traits": {
        "groupType": "company",
        "KEY_3": {
          "CHILD_KEY_92": "value_95",
          "CHILD_KEY_102": "value_103"
        },
        "name_trait": "Company",
        "value_trait": "Company-ABC"
      },
      "messageId": "e5034df0-a404-47b4-a463-76df99934fea",
      "event": "$group",
      "api_key": "LNDs0JGdwbknNGolFc4HdoAE",
      "type": "group"
    },
  },
}

When enabled, RudderStack sends the group traits as event properties to PostHog, as shown:

{
  "version": "1",
  "type": "REST",
  "method": "POST",
  "endpoint": "https://app.posthog.com/batch",
  "headers": {
    "Content-Type": "application/json"
  },
  "params": {},
  "body": {
    "JSON": {
      "distinct_id": "sampleusrRudder7",
      "messageId": "e5034df0-a404-47b4-a463-76df99934fea",
      "properties": {
        "$group_key": "groupId27",
        "$group_type": "company",
        "$group_set": {
          "KEY_3": {
            "CHILD_KEY_92": "value_95",
            "CHILD_KEY_102": "value_103"
          },
          "name_trait": "Company",
          "value_trait": "Comapny-ABC"
        },
      },
      "event": "$group",
      "api_key": "LNDs0JGdwbknNGolFc4HdoAE",
      "type": "group"
    },
  },
}

The mapping is as shown:

Group trait	Updated group mapping disabled	Updated group mapping enabled
groupId	groupId	$group_key
groupType	groupType	$group_type
traits	traits	$group_set

Alias

Calling alias() passes userId and previousId to the PostHog queue.

For information on the alias call, refer to the RudderStack API Specification guide.

A sample alias call in RudderStack is as shown:

rudderanalytics.alias("user01", "previous01")

In the above example, previous01 gets mapped to distinct id in PostHog, while user01 gets mapped to alias in PostHog.

For the alias call, RudderStack sends $create_alias as an event to PostHog according to PostHog Alias API.

Passing super properties in the PostHog web SDK

To pass super properties to the PostHog JavaScript SDK, you can pass the key-value pairs as shown:

• The following example will set superKey1: "value1", superKey2: "value2" as super properties to the PostHog web SDK:

rudderanalytics.track("event", {prop: "value"}, {
  integrations: {
    POSTHOG: {
      superProperties: {
        superKey1: "value1",
        superKey2: "value2"
      }
    }
  }
})

• The following example will set superKey3: "value3" as super properties just once and pass on to the PostHog web SDK:

// This will set {superKey3: "value3"} as set once super properties to PostHog SDK
rudderanalytics.track("event", {prop: "value"}, {
  integrations: {
    POSTHOG: {
      setOnceProperties: {
        superKey3: "value3"
      }
    }
  }
})

• The following example unsets the previously set super properties:

// This will unset super properties superKey1, superKey2, superKey3 to PostHog SDK
rudderanalytics.track("event", {prop: "value"}, {
  integrations: {
    POSTHOG: {
      unsetProperties: [
        superKey1,
        superKey2,
        superKey3
      ]
    }
  }
})

The super properties can be passed to any of track, page, or identify calls of the RudderStack JavaScript SDK.

Property mapping

RudderStack maps the following properties sent to the Posthog standard contextual properties:

RudderStack field	PostHog field
context.os.name	$os
context.page.url	$current_url
url	$host
context.page.path	$pathname
context.screen.height	$screen_height
context.screen.width	$screen_width
context.library.name	$lib
context.library.version	$lib_version
originalTimestamp,timestamp	$time
context.device.id	$device_id
request_ip,context.ip	$ip
timestamp,originalTimestamp	$timestamp
anonymousId	$anon_distinct_id
userId,anonymousId	distinct_id
context.screen.density	$screen_density
context.device.manufacturer	$device_manufacturer
context.os.version	$os_version
context.timezone	$timezone
context.locale	$locale
context.userAgent	$user_agent
context.app.version	$app_version
context.device.name	$device_name
context.network.carrier	$network_carrier
context.app.name	$app_name
context.device.model	$device_model
context.app.namespace	$app_namespace
context.app.build	$app_build

The PostHog SDK autogenerates the property $insert_id when you send event via the RudderStack device mode. However, when sending the events via the cloud mode, RudderStack does not map any value to this property.

FAQs

How do I obtain the PostHog Team API Key?

To get your PostHog Project API Key or Team API Key, follow the steps below:

1. Login to your PostHog dashboard.

2. Go to the Settings tab under the Project section in the left sidebar.

3. Find your key under Project API Key or Team API Key.

Contact us

For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.