From a6bf9d36aa79d4ecde2784ef428cb78c739a302d Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Fri, 12 Jun 2026 11:40:56 +0200 Subject: [PATCH] docs: centralize SDK examples in official docs --- EXAMPLE_SETUP.md | 142 ---------------------------------------- README.md | 23 +++---- posthog-rails/README.md | 11 ++-- 3 files changed, 14 insertions(+), 162 deletions(-) delete mode 100644 EXAMPLE_SETUP.md diff --git a/EXAMPLE_SETUP.md b/EXAMPLE_SETUP.md deleted file mode 100644 index a84f2c7..0000000 --- a/EXAMPLE_SETUP.md +++ /dev/null @@ -1,142 +0,0 @@ -# PostHog Ruby SDK Example Setup Guide - -This guide helps you set up the example script to demonstrate all PostHog Ruby SDK features, including the new complex cohort evaluation capabilities. - -## Quick Start - -1. **Set up credentials:** - ```bash - cp .env.example .env - # Edit .env with your actual PostHog credentials - ``` - -2. **Run the example:** - ```bash - ruby example.rb - ``` - -3. **Choose an example to run from the interactive menu** - -## Detailed Setup - -### 1. Environment Configuration - -Create a `.env` file with your PostHog credentials: - -```bash -# Your PostHog project API key (found on the /setup page in PostHog) -POSTHOG_API_KEY=phc_your_project_key_here - -# Your personal API key (required for local feature flag evaluation) -POSTHOG_PERSONAL_API_KEY=phx_your_personal_key_here - -# PostHog host URL -POSTHOG_HOST=https://us.posthog.com # or https://eu.posthog.com for EU, or your self-hosted URL -``` - -### 2. Complex Cohort Example Setup - -For the complex cohort evaluation example (option 3), you need to create a specific cohort and feature flag in your PostHog instance: - -#### Step 1: Create Supporting Cohort - -**Go to:** PostHog → People → Cohorts → New Cohort - -- **Name:** `posthog-team` (or any name) -- **Conditions:** - ``` - OR Group: - ├── email contains "@posthog.com" - └── $host equals "localhost:8010" - ``` - -#### Step 2: Create Main Cohort - -**Go to:** PostHog → People → Cohorts → New Cohort - -- **Name:** `complex-cohort` -- **Description:** `Complex cohort for Ruby SDK demo` -- **Conditions:** - ``` - OR Group (Top Level): - ├── AND Group 1: - │ ├── email contains "@example.com" - │ └── is_email_verified = "true" - └── OR Group 2: - └── User belongs to cohort "posthog-team" - ``` - -#### Step 3: Create Feature Flag - -**Go to:** PostHog → Feature Flags → New Feature Flag - -- **Name:** `test-complex-cohort-flag` -- **Key:** `test-complex-cohort-flag` -- **Release Conditions:** - - User belongs to cohort `complex-cohort` - - Rollout percentage: 100% - -## What the Examples Demonstrate - -### Option 1: Identify and Capture -- Event tracking with properties -- User identification and aliases -- Group identification -- Property setting ($set, $set_once) - -### Option 2: Feature Flag Local Evaluation -- Basic feature flag evaluation -- Location-based flags -- Local-only evaluation -- Bulk flag retrieval - -### Option 3: Complex Cohort Evaluation ⭐ **NEW** -This demonstrates the Ruby SDK's new capability to evaluate complex cohorts locally: - -**Test Cases:** -- ✅ `user@example.com` with `is_email_verified=true` → should match (first AND group) -- ✅ `dev@posthog.com` → should match (nested cohort reference) -- ❌ `user@other.com` → should not match (no conditions met) - -**Key Features Showcased:** -- Multi-level nested logic (OR → AND → properties) -- Cohort-within-cohort references -- Mixed property operators (`icontains`, `exact`) -- Zero API calls for complex evaluation -- Ruby SDK feature parity with Python/Node.js SDKs - -### Option 4: Feature Flag Payloads -- Getting payloads for specific flags -- Bulk payload retrieval -- Remote config payloads - -## Troubleshooting - -### Authentication Errors -- Verify your API keys are correct -- Ensure personal API key has proper permissions -- Check that your host URL is correct - -### Missing Feature Flag -If `test-complex-cohort-flag` doesn't exist, the example will still run but return `false` for all tests. Follow the setup steps above to create the required cohort and flag. - -### Local Evaluation Not Working -- Ensure you have a personal API key (not just project API key) -- Check that feature flags are active in your PostHog instance -- Verify cohort conditions are properly configured - -## Example Output - -When working correctly, option 3 should output: -``` -✅ Verified @example.com user: true -✅ @posthog.com user: true -❌ Regular user: false - -🎯 Results Summary: - - Complex nested cohorts evaluated locally: ✅ YES - - Zero API calls needed: ✅ YES (all evaluated locally) - - Ruby SDK now has cohort parity: ✅ YES -``` - -This demonstrates that the Ruby SDK can now evaluate complex, nested cohorts entirely locally - a major new capability that brings it to feature parity with other PostHog server-side SDKs! \ No newline at end of file diff --git a/README.md b/README.md index 8e006c3..ad5ee33 100644 --- a/README.md +++ b/README.md @@ -2,24 +2,17 @@ Please see the main [PostHog docs](https://posthog.com/docs). -Specifically, the [Ruby integration](https://posthog.com/docs/integrations/ruby-integration) details. +SDK usage examples and code snippets live in the official documentation so they stay up to date. -> [!IMPORTANT] -> **Use a single client instance (singleton)** — Create the PostHog client once and reuse it throughout your application. Multiple client instances with the same API key can cause dropped events and inconsistent behavior. The SDK will log a warning if it detects multiple instances. For Rails apps, use `PostHog.init` in an initializer (see [posthog-rails](posthog-rails/README.md)). +## Documentation -> [!IMPORTANT] -> Supports Ruby 3.2 and above -> -> We will lag behind but generally not support versions which are end-of-life as listed here https://www.ruby-lang.org/en/downloads/branches/ -> -> All 2.x versions of the PostHog Ruby library are compatible with Ruby 2.0 and above if you need Ruby 2.0 support. - -## Rails Integration - -**Using Rails?** Check out [posthog-rails](posthog-rails/README.md) for automatic exception tracking, ActiveJob instrumentation, and Rails-specific features. +- [Ruby library docs](https://posthog.com/docs/libraries/ruby) +- [Ruby on Rails framework docs](https://posthog.com/docs/libraries/ruby-on-rails) ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, example, and test instructions. +See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup and test instructions. + +## Releasing -For release instructions, see [RELEASING.md](RELEASING.md). +See [RELEASING.md](RELEASING.md). diff --git a/posthog-rails/README.md b/posthog-rails/README.md index bbfe5dd..cbb850b 100644 --- a/posthog-rails/README.md +++ b/posthog-rails/README.md @@ -1,9 +1,10 @@ -# PostHog Rails +# PostHog Ruby on Rails -Official PostHog integration for Ruby on Rails applications. +Please see the main [PostHog docs](https://posthog.com/docs). -For installation, configuration, usage, and troubleshooting, see the official documentation: +SDK usage examples and code snippets live in the official documentation so they stay up to date. -https://posthog.com/docs/libraries/ruby-on-rails +## Documentation -Keeping usage docs in one place avoids stale examples in this repository. +- [Ruby on Rails framework docs](https://posthog.com/docs/libraries/ruby-on-rails) +- [Ruby library docs](https://posthog.com/docs/libraries/ruby)