From 762110f10877824a9c5716f89678e371eb74f26c Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Thu, 12 Nov 2026 18:11:13 -0800 Subject: [PATCH 1/2] Revert "docs: scope the capture v1 pages to the server SDKs in this release" This reverts commit 55024f1819488fbfece4ac21eff3ec89fcea9ff1. --- .../docs/ai-observability/installation/manual-capture.mdx | 2 ++ contents/docs/ai-observability/large-events.mdx | 4 ++-- contents/docs/api/capture-v1.mdx | 2 +- contents/docs/libraries.mdx | 5 ++++- contents/docs/self-host/index.mdx | 2 +- 5 files changed, 10 insertions(+), 5 deletions(-) diff --git a/contents/docs/ai-observability/installation/manual-capture.mdx b/contents/docs/ai-observability/installation/manual-capture.mdx index e5fce860c9b3..c6d51a13aa95 100644 --- a/contents/docs/ai-observability/installation/manual-capture.mdx +++ b/contents/docs/ai-observability/installation/manual-capture.mdx @@ -47,6 +47,8 @@ import EmbeddingEvent from '../_snippets/embedding-event.mdx' ## Large events +On the iOS and Android SDKs (`4.0.0`+) and the Flutter SDK (`6.0.0`+, except on web, where `captureAi` sends nothing), send the events above with `captureAi` instead of `capture` – see the [iOS](/docs/libraries/ios/usage#ai-events), [Android](/docs/libraries/android#ai-events), and [Flutter](/docs/libraries/flutter#ai-events) docs. + For large events, use the dedicated AI ingestion path – see [capturing large AI events](/docs/ai-observability/large-events). In Python, large events sent with `capture()` are dropped: posthog-python 7.x drops events over 900 KiB, and on 8.0 PostHog drops events over [the 1MB event limit](/docs/data/ingestion-warnings#discarded-event-exceeding-1mb-limit). Call `capture_ai()` instead, with the same arguments, to send events up to 8MB: diff --git a/contents/docs/ai-observability/large-events.mdx b/contents/docs/ai-observability/large-events.mdx index 21008ec185d4..70ff5d6ce0b3 100644 --- a/contents/docs/ai-observability/large-events.mdx +++ b/contents/docs/ai-observability/large-events.mdx @@ -6,7 +6,7 @@ import CalloutBox from 'components/Docs/CalloutBox' -Large event capture is in public beta. The [capture v1 SDKs](/docs/libraries#sdk-versions-and-capture-v1) use it for every event sent with their AI capture method, and posthog-python and posthog-node also use it for their AI integrations: [posthog-python](/docs/libraries/python/reference#capture-ai) 8.0.0+, [posthog-node](/docs/libraries/node/reference#capture-ai) 6.0.0+, [posthog-go](/docs/libraries/go) v2.0.0+, and the [Rust SDK](/docs/libraries/rust) 1.0.0+. Older versions of posthog-python (7.39+) and posthog-node (5.49+, with `@posthog/ai` 8.8+) support it as an opt-in. We'd love to [hear your feedback](https://app.posthog.com/ai-observability#panel=support%3Afeedback%3Allm-analytics%3Alow%3Atrue) as we roll it out. +Large event capture is in public beta. The [capture v1 SDKs](/docs/libraries#sdk-versions-and-capture-v1) use it for every event sent with their AI capture method, and posthog-python and posthog-node also use it for their AI integrations: [posthog-python](/docs/libraries/python/reference#capture-ai) 8.0.0+, [posthog-node](/docs/libraries/node/reference#capture-ai) 6.0.0+, [posthog-go](/docs/libraries/go) v2.0.0+, the [Rust SDK](/docs/libraries/rust) 1.0.0+, the iOS and Android SDKs 4.0.0+, and the Flutter SDK 6.0.0+ (except on the web). Older versions of posthog-python (7.39+) and posthog-node (5.49+, with `@posthog/ai` 8.8+) support it as an opt-in. We'd love to [hear your feedback](https://app.posthog.com/ai-observability#panel=support%3Afeedback%3Allm-analytics%3Alow%3Atrue) as we roll it out. @@ -46,7 +46,7 @@ With the flag on, nothing is truncated or redacted. On posthog-python 8.0.0+ and ## Calling capture_ai directly -If you build AI events yourself instead of using the integrations, call `capture_ai` (Python) or `captureAi` (Node) instead of `capture`. It takes the same arguments as `capture` and returns the captured event's UUID. The other capture v1 SDKs have an AI capture method too: `EnqueueAI` in Go and `capture_ai` in Rust. Your SDK's [migration guide](/docs/libraries#sdk-versions-and-capture-v1) lists its AI settings. +If you build AI events yourself instead of using the integrations, call `capture_ai` (Python) or `captureAi` (Node) instead of `capture`. It takes the same arguments as `capture` and returns the captured event's UUID. The other capture v1 SDKs have an AI capture method too: `EnqueueAI` in Go, `capture_ai` in Rust, and `captureAi` on [iOS](/docs/libraries/ios/usage#ai-events), [Android](/docs/libraries/android#ai-events), and [Flutter](/docs/libraries/flutter#ai-events). Your SDK's [migration guide](/docs/libraries#sdk-versions-and-capture-v1) lists its AI settings. The mobile SDKs keep AI events in their own on-disk queue and drop an event over 8 MiB plus 64 KiB before sending it. On Flutter web, `captureAi` is a no-op. diff --git a/contents/docs/api/capture-v1.mdx b/contents/docs/api/capture-v1.mdx index 6059e8afa55e..8ca9d05b8a7b 100644 --- a/contents/docs/api/capture-v1.mdx +++ b/contents/docs/api/capture-v1.mdx @@ -28,7 +28,7 @@ Capture v1 has two endpoints: one for analytics events and one for AI events. Bo Use `https://us.i.posthog.com` for US Cloud and `https://eu.i.posthog.com` for EU Cloud. Both endpoints accept POST only. -Self-hosted (hobby) instances serve both endpoints from PostHog commit `1d6f4d0` (October 21, 2026) onward. [Upgrade your instance](/docs/self-host#upgrading) before you move an SDK to capture v1. An older instance doesn't serve one or both endpoints. Server SDKs on capture v1 drop events that still get a `404` after their retries. +Self-hosted (hobby) instances serve both endpoints from PostHog commit `1d6f4d0` (October 21, 2026) onward. [Upgrade your instance](/docs/self-host#upgrading) before you move an SDK to capture v1. An older instance doesn't serve one or both endpoints. Server SDKs on capture v1 drop events that still get a `404` after their retries. The iOS, Android, and Flutter SDKs keep them queued until the path is served or their queue fills. If you send through a reverse proxy, it must forward both paths and pass the request headers through unchanged. See the [proxy reference](/docs/advanced/proxy/proxy-reference). diff --git a/contents/docs/libraries.mdx b/contents/docs/libraries.mdx index 54609f614a47..79f4740a68b2 100644 --- a/contents/docs/libraries.mdx +++ b/contents/docs/libraries.mdx @@ -23,8 +23,11 @@ We suggest you migrate as soon as possible, but the older major versions keep wo | [Go](/docs/libraries/go) | `v2.0.0` | [`v1` to `v2`](/docs/libraries/go/migration) | | [Rust](/docs/libraries/rust) | `1.0.0` | [`0.x` to `1.0`](/docs/libraries/rust/migration) | | [Node.js](/docs/libraries/node) | `6.0.0` | [`5.x` to `6.0`](https://github.com/PostHog/posthog-js/blob/main/packages/node/MIGRATION.md) | +| [iOS](/docs/libraries/ios) | `4.0.0` | [`3.x` to `4.0`](/docs/libraries/ios/migration) | +| [Android](/docs/libraries/android) | `4.0.0` | [`3.x` to `4.0`](/docs/libraries/android/migration) | +| [Flutter](/docs/libraries/flutter) | `6.0.0` | [`5.x` to `6.0`](/docs/libraries/flutter/migration) | -Every other SDK, including the JavaScript Web SDK and the mobile SDKs, stays on legacy capture for now. +The JavaScript Web SDK, React Native, and other SDKs stay on legacy capture for now. Flutter apps on the web use the JavaScript Web SDK, so they stay on legacy capture too. For how capture v1 handles events, see the [Capture API (v1)](/docs/api/capture-v1). diff --git a/contents/docs/self-host/index.mdx b/contents/docs/self-host/index.mdx index bf716ac2f629..c738b90cc4e1 100644 --- a/contents/docs/self-host/index.mdx +++ b/contents/docs/self-host/index.mdx @@ -197,7 +197,7 @@ The best place to start looking is in the `web` container, which runs all the da To upgrade, you can run the `upgrade-hobby` script from the PostHog repo. -Upgrade before you move an SDK to a [capture v1](/docs/libraries#sdk-versions-and-capture-v1) version. Instances serve the capture v1 endpoints from PostHog commit `1d6f4d0` (October 21, 2026) onward. Server SDKs on capture v1 drop events that still get a `404` after their retries. +Upgrade before you move an SDK to a [capture v1](/docs/libraries#sdk-versions-and-capture-v1) version. Instances serve the capture v1 endpoints from PostHog commit `1d6f4d0` (October 21, 2026) onward. Server SDKs on capture v1 drop events that still get a `404` after their retries. The iOS, Android, and Flutter SDKs keep them queued until the path is served or their queue fills. ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/posthog/posthog/HEAD/bin/upgrade-hobby)" From bdf43bc4371cbc27294f21bf5faf642346596099 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Fri, 13 Nov 2026 12:22:07 -0500 Subject: [PATCH 2/2] docs: point the mobile AI events links at the reference pages Co-Authored-By: Claude Opus 5.5 --- contents/docs/ai-observability/installation/manual-capture.mdx | 2 +- contents/docs/ai-observability/large-events.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/contents/docs/ai-observability/installation/manual-capture.mdx b/contents/docs/ai-observability/installation/manual-capture.mdx index c6d51a13aa95..d4e0919a99b5 100644 --- a/contents/docs/ai-observability/installation/manual-capture.mdx +++ b/contents/docs/ai-observability/installation/manual-capture.mdx @@ -47,7 +47,7 @@ import EmbeddingEvent from '../_snippets/embedding-event.mdx' ## Large events -On the iOS and Android SDKs (`4.0.0`+) and the Flutter SDK (`6.0.0`+, except on web, where `captureAi` sends nothing), send the events above with `captureAi` instead of `capture` – see the [iOS](/docs/libraries/ios/usage#ai-events), [Android](/docs/libraries/android#ai-events), and [Flutter](/docs/libraries/flutter#ai-events) docs. +On the iOS and Android SDKs (`4.0.0`+) and the Flutter SDK (`6.0.0`+, except on web, where `captureAi` sends nothing), send the events above with `captureAi` instead of `capture` – see the [iOS](/docs/libraries/ios/reference#capture-ai), [Android](/docs/libraries/android/reference#capture-ai), and [Flutter](/docs/libraries/flutter/reference#capture-ai) docs. For large events, use the dedicated AI ingestion path – see [capturing large AI events](/docs/ai-observability/large-events). diff --git a/contents/docs/ai-observability/large-events.mdx b/contents/docs/ai-observability/large-events.mdx index 70ff5d6ce0b3..91f061f6353e 100644 --- a/contents/docs/ai-observability/large-events.mdx +++ b/contents/docs/ai-observability/large-events.mdx @@ -46,7 +46,7 @@ With the flag on, nothing is truncated or redacted. On posthog-python 8.0.0+ and ## Calling capture_ai directly -If you build AI events yourself instead of using the integrations, call `capture_ai` (Python) or `captureAi` (Node) instead of `capture`. It takes the same arguments as `capture` and returns the captured event's UUID. The other capture v1 SDKs have an AI capture method too: `EnqueueAI` in Go, `capture_ai` in Rust, and `captureAi` on [iOS](/docs/libraries/ios/usage#ai-events), [Android](/docs/libraries/android#ai-events), and [Flutter](/docs/libraries/flutter#ai-events). Your SDK's [migration guide](/docs/libraries#sdk-versions-and-capture-v1) lists its AI settings. The mobile SDKs keep AI events in their own on-disk queue and drop an event over 8 MiB plus 64 KiB before sending it. On Flutter web, `captureAi` is a no-op. +If you build AI events yourself instead of using the integrations, call `capture_ai` (Python) or `captureAi` (Node) instead of `capture`. It takes the same arguments as `capture` and returns the captured event's UUID. The other capture v1 SDKs have an AI capture method too: `EnqueueAI` in Go, `capture_ai` in Rust, and `captureAi` on [iOS](/docs/libraries/ios/reference#capture-ai), [Android](/docs/libraries/android/reference#capture-ai), and [Flutter](/docs/libraries/flutter/reference#capture-ai). Your SDK's [migration guide](/docs/libraries#sdk-versions-and-capture-v1) lists its AI settings. The mobile SDKs keep AI events in their own on-disk queue and drop an event over 8 MiB plus 64 KiB before sending it. On Flutter web, `captureAi` is a no-op.