docs: add 4.5.0 automatic push integration flags to Android migration guide + README (#520)

* docs: add 4.4.0 automatic push tracking flags migration guide and README note

- Add migration guide entry for `automatic_push_open_tracking` (opt-in, default off)
  and `automatic_push_token_forwarding` (default on, pending #516/MAGE-937 merge)
- Token-forwarding entry is explicitly marked pending klaviyo-android-sdk#516;
  finalize on merge before releasing docs
- Add two-stage rollout summary table covering both Android and iOS flags
- Add anonymous-profile note to README Anonymous Tracking section

Relates to MAGE-897.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: drop pending-#516 caveats from Android migration guide

MAGE-937 (#516) is landing imminently; remove the "pending merge" note,
heading suffix, and table caveat, and fix the README anchor link.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: fix Anonymous Tracking anchor to point at the README

Bare `#anonymous-tracking` fragment resolved against MIGRATION_GUIDE.md;
link explicitly to ./README.md#anonymous-tracking.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: correct token-forwarding timing to init/foreground/refresh

Per maybeAutoRegisterPushToken (called from initialize and on app foreground)
plus onNewToken: the SDK forwards the current token at initialization, on
foreground, and on FCM token refresh — not only "as soon as FCM delivers one".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: correct auto-push release version to 4.5.0 (Android)

The automatic push behaviors ship in the upcoming 4.5.0 minor, not 4.4.0.
Updated the migration guide section and the README anonymous-profile note;
left install snippets and unrelated version references untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: Android-only migration guide + clarify default-on token forwarding

- Remove iOS flag rows from the rollout summary (Android guide should not
  document iOS behavior).
- Reword the intro to distinguish the opt-in open-tracking flag from the
  default-on token forwarding, and note the manual-control opt-out
  (addresses CodeRabbit).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: move opt-in/out instructions to README, point migration guide there

Per review feedback: configuration instructions (XML snippets) belong in
the README alongside the existing Option A setup guide; the migration
guide now links there instead of duplicating them.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: glenn-klaviyo

MIGRATION_GUIDE.md

@@ -2,6 +2,48 @@
 This document provides guidance on how to migrate from one version of the SDK to a newer version.
 It will be updated as new versions are released including deprecations or breaking changes.
 
+# 4.5.0
+
+## New Automatic Push Behaviors (Manifest Flags)
+
+SDK 4.5.0 introduces two push behaviors controlled via `AndroidManifest.xml` metadata:
+`automatic_push_open_tracking` (new, opt-in) and `automatic_push_token_forwarding` (**on by
+default**, formalizing the SDK's existing automatic token forwarding). No action is required to
+preserve your current behavior. If you manage push tokens manually and want to disable automatic
+forwarding, opt out as described below.
+
+### `automatic_push_open_tracking` (opt-in, default **off**)
+
+When enabled, the SDK automatically records push-open events without requiring you to call
+`Klaviyo.handlePush` manually in your notification interaction handler.
+
+This flag defaults to **off** in 4.5.0 and is expected to become the default (opt-out) in a future
+major release. For setup instructions, see
+[Option A — Automatic Integration](./README.md#option-a--automatic-integration) in the README.
+
+### `automatic_push_token_forwarding` (default **on**)
+
+When this flag is enabled (which is the **default**), the SDK automatically registers the device's
+FCM push token with Klaviyo on your behalf — you no longer need to call `Klaviyo.setPushToken`
+manually on app startup.
+
+To opt out and retain manual control, see
+[Option A — Automatic Integration](./README.md#option-a--automatic-integration) in the README.
+
+### Rollout summary
+
+| Behavior | This release (4.5.0) | Future major release |
+|---|---|---|
+| `automatic_push_token_forwarding` | Default on (opt-out via manifest) | Default on |
+| `automatic_push_open_tracking` | Opt-in (default off) | Default on (opt-out) |
+
+> **Anonymous profiles:** When `automatic_push_token_forwarding` is enabled (the Android default),
+> the SDK registers the device's push token with Klaviyo automatically — at initialization, when the
+> app returns to the foreground, and whenever FCM issues a new token — which can occur before you call
+> `setProfile`, `setEmail`, or `setPhoneNumber`. This results in an anonymous profile being created in Klaviyo
+> until you provide identifying information. This is expected behavior. See
+> [Anonymous Tracking](./README.md#anonymous-tracking) in the README.
+
 # 4.3.0
 
 ## New Modules for Cross-Platform Support

README.md

@@ -347,6 +347,14 @@ Klaviyo will track unidentified users with an autogenerated ID whenever a push t
 That way, you can collect push tokens and track events prior to collecting profile identifiers such as email or
 phone number. When an identifier is provided, Klaviyo will merge the anonymous user with an identified user.
 
+> **Automatic push token forwarding:** When `automatic_push_token_forwarding` is enabled (the
+> default in SDK 4.5.0+), the SDK registers the device's push token with Klaviyo automatically — at
+> initialization, when the app returns to the foreground, and whenever FCM issues a new token — which
+> can occur before any call to `setProfile`, `setEmail`, or `setPhoneNumber`. This results
+> in an anonymous profile being created in Klaviyo until you provide identifying information.
+> This is expected behavior. To opt out, see
+> [Option A — Automatic Integration](#option-a--automatic-integration) below.
+
 ## Event Tracking
 The SDK provides tools for tracking analytics events via the
 [Create Client Event API](https://developers.klaviyo.com/en/reference/create_client_event).