Subchapter 47.49

Node

references/node.mdMarkdown27 KBView on GitHub

Node.js - Docs

If you’re working with Node.js (versions 20+), the official posthog-node library is the simplest way to integrate your software with PostHog. This library uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your web app or other server-side application that needs performance. And in addition to event capture, are supported as well.

Node · Instrument Integration · PostHog/skills · Skills Docs

Variable	Description	Default value
host	Your PostHog host	https://us.i.posthog.com/ (opens in a new tab)
flushAt	After how many capture calls we should flush the queue (in one batch)	20
flushInterval	After how many ms we should flush the queue	10000
personalApiKey	An optional personal API key (opens in a new tab) for evaluating feature flags locally. Note: Providing this will trigger periodic calls to the feature flags service, even if you’re not using feature flags.	null
featureFlagsPollingInterval	Interval in milliseconds specifying how often feature flags should be fetched from the PostHog API	300000
requestTimeout	Timeout in milliseconds for any calls	10000
maxCacheSize	Maximum size of cache that deduplicates $feature_flag_called calls per user.	50000
disableGeoip	When true, disables automatic GeoIP resolution for events and feature flags.	true
evaluation_contexts	Evaluation context tags that constrain which feature flags are evaluated. When set, only flags with matching evaluation context tags (or no evaluation context tags) will be returned. This helps reduce unnecessary flag evaluations and improves performance. See evaluation contexts documentation (opens in a new tab) for more details. Available in version 5.10.0+. The legacy parameter evaluation_environments (version 5.9.6+) is also supported for backward compatibility.	undefined

client.register({
  app_version: '1.2.0',
  environment: 'production',
})
// Both events include app_version and environment
client.capture({
  distinctId: 'distinct_id',
  event: 'page_viewed',
})
client.capture({
  distinctId: 'distinct_id',
  event: 'button_clicked',
})

client.register({ environment: 'production' })
// This event is captured with environment='staging'
client.capture({
  distinctId: 'distinct_id',
  event: 'page_viewed',
  properties: { environment: 'staging' },
})

posthog.withContext(
  {
    distinctId: 'user-123',
    properties: { transactionId: 'abc123' }
  },
  () => {
    // This event is captured with the distinct ID and properties set above
    posthog.capture({ event: 'order_processed' })
  }
)

function someFunction() {
  // When called from `outerFunction`, this event is captured
  // with transactionId='abc123'
  posthog.capture({ event: 'order_processed' })
}
function outerFunction() {
  posthog.withContext(
    { properties: { transactionId: 'abc123' } },
    () => {
      someFunction()
    }
  )
}

posthog.withContext(
  {
    properties: {
      someKey: 'value-1',
      someOtherKey: 'another-value'
    }
  },
  () => {
    posthog.withContext(
      { properties: { someKey: 'value-2' } },
      () => {
        // Captured with someKey='value-2', someOtherKey='another-value'
        posthog.capture({ event: 'order_processed' })
      },
    )
    // Captured with someKey='value-1', someOtherKey='another-value'
    posthog.capture({ event: 'order_completed' })
  }
)

posthog.withContext(
  { distinctId: 'user-123' },
  () => {
    // Associated with "user-123"
    posthog.capture({ event: 'order_processed' })
    // Overrides to "another-user"
    posthog.capture({
      distinctId: 'another-user',
      event: 'order_processed'
    })
  }
)

posthog.withContext(
  { sessionId: 'some-session' },
  () => {
    // Associated with session "some-session"
    posthog.capture({ event: 'image_uploaded' })
    // Overrides to "next-session"
    posthog.capture({
      event: 'image_uploaded',
      properties: { $sessionId: 'next-session' }
    })
  }
)

posthog.withContext(
  { flightNumber: 'TAC313' },
  () => {
    // Associated with flightNumber TAC313
    posthog.capture({ event: 'flight_cancelled' })
    // Overrides to PL7714
    posthog.capture({
      event: 'flight_cancelled',
      properties: { flightNumber: 'PL7714' }
    })
  }
)

const flags = await client.evaluateFlags('distinct_id_of_your_user')
if (flags.isEnabled('flag-key')) {
    // Do something differently for this user
    // Optional: fetch the payload
    const matchedFlagPayload = flags.getFlagPayload('flag-key')
}

const flags = await client.evaluateFlags('distinct_id_of_your_user')
const enabledVariant = flags.getFlag('flag-key')
if (enabledVariant === 'variant-key') { // replace 'variant-key' with the key of your variant
    // Do something differently for this user
    // Optional: fetch the payload
    const matchedFlagPayload = flags.getFlagPayload('flag-key')
}

const flags = await client.evaluateFlags('distinct_id_of_your_user')
if (flags.isEnabled('flag-key')) {
    // Do something differently for this user
}
client.capture({
    distinctId: 'distinct_id_of_your_user',
    event: 'event_name',
    flags,
})

// Attach only flags accessed with isEnabled() or getFlag() before this call
client.capture({
    distinctId: 'distinct_id_of_your_user',
    event: 'event_name',
    flags: flags.onlyAccessed(),
})
// Attach only specific flags
client.capture({
    distinctId: 'distinct_id_of_your_user',
    event: 'event_name',
    flags: flags.only(['checkout-flow', 'new-dashboard']),
})

client.capture({
    distinctId: 'distinct_id_of_your_user',
    event: 'event_name',
    properties: {
        // Replace feature-flag-key with your flag key and 'variant-key' with the key of your variant
        '$feature/feature-flag-key': 'variant-key',
    },
})

const flags = await client.evaluateFlags('distinct_id_of_the_user', {
    personProperties: {
        property_name: 'value',
    },
    groups: {
        your_group_type: 'your_group_id',
        another_group_type: 'your_group_id',
    },
    groupProperties: {
        your_group_type: {
            group_property_name: 'value',
        },
        another_group_type: {
            group_property_name: 'value',
        },
    },
})
if (flags.isEnabled('flag-key')) {
    // Do something differently for this user
}

const client = new PostHog('<ph_project_token>', {
    api_host: 'https://us.i.posthog.com',
    feature_flag_request_timeout_ms: 3000, // Time in milliseconds. Defaults to 3000 (3 seconds).
})

const flags = await client.evaluateFlags('user distinct id', {
    groups: { organization: 'google' },
    groupProperties: { organization: { is_authorized: true } },
})
const flagValue = flags.getFlag('flag-key')

client.groupIdentify({
  groupType: 'company',
  groupKey: 'company_id_in_your_db',
  properties: {
    name: 'Awesome Inc',
    employees: 11,
  },
  // optional distinct ID to associate event with an existing person
  distinctId: 'xyz'
})

export const handler() {
  client.capture({
    distinctId: 'distinct_id_of_the_user',
    event: 'thing_happened'
  })
  client.capture({
    distinctId: 'distinct_id_of_the_user',
    event: 'other_thing_happened'
  })
  // So far 2 events are queued but not sent
  // Calling shutdown, flushed the queue but batched into 1 API call for maximum efficiency
  await client.shutdown()
}