docs(appevents): app opens need automatic logging

Docs/Integration.md

@@ -112,7 +112,7 @@ value, and a persisted value wins over the manifest on later launches.
 | Manifest `meta-data` (`com.facebook.sdk.`) | Runtime API | Effect |
 | --- | --- | --- |
 | `AutoInitEnabled` | `SetAutoInitEnabled`, `IsAutoInitEnabled` | `false` keeps the SDK from fully initializing; the SDK does not process Graph API responses until then. |
-| `AutoLogAppEventsEnabled` | `SetAutoLogAppEventsEnabled`, `IsAutoLogAppEventsEnabled` | Automatic install ping, app activation and, when Events Manager allows it, Google Play purchase and subscription events. Since 19.0.0 a local `false` wins over Events Manager. |
+| `AutoLogAppEventsEnabled` | `SetAutoLogAppEventsEnabled`, `IsAutoLogAppEventsEnabled` | The SDK's automatic events: app activation and deactivation (`fb_mobile_activate_app`, `fb_mobile_deactivate_app`, even when `ActivateApp()` started tracking) and, when the App Dashboard allows it, Google Play purchase and subscription events. It does not cover the install ping, which only `ActivateApp()` sends. The effective value is the local value and the Events Manager value: since 19.0.0 a local `false` always wins, and disabling automatic SDK event logging in Events Manager overrides a local `true`. |
 | `AdvertiserIDCollectionEnabled` | `SetAdvertiserIdCollectionEnabled`, `IsAdvertiserIdCollectionEnabled` | Advertising ID collection. |
 | `AutoLogMetaDataEnabled` | `SetMetadataCollectionEnabled`, `IsMetadataCollectionEnabled` | SDK 19.0.0+: attaches the screen title and AppLink URL to events. `false` also discards what was collected. |
 | `AutoLogProductImprovementEnabled` | `SetAutoLogProductImprovementEnabled`, `IsAutoLogProductImprovementEnabled` | SDK 19.0.0+: control for product-improvement data. The 19.0.0 changelog says the SDK does not collect such data yet. |
@@ -143,17 +143,34 @@ SDK (see the strictest setup below).
    {
        FacebookAppEvents.SetAutoInitEnabled(true);
        FacebookAppEvents.SetAdvertiserIdCollectionEnabled(true);
-       // Either let the SDK log automatically ...
-       // FacebookAppEvents.SetAutoLogAppEventsEnabled(true);
-       // ... or keep automatic logging off and log activation yourself. ActivateApp()
-       // sends the one-time install ping and starts activation tracking, which logs
-       // fb_mobile_activate_app from the next activity resume on. Call it after
-       // auto-init is enabled, or the SDK discards the ping response.
-       FacebookAppEvents.SetAutoLogAppEventsEnabled(false);
+       // App opens (fb_mobile_activate_app) are automatic events: they need
+       // automatic logging on.
+       FacebookAppEvents.SetAutoLogAppEventsEnabled(true);
+       // One-time install ping, and activity tracking. Call it after auto-init
+       // is enabled, or the SDK discards the ping response.
        FacebookAppEvents.ActivateApp();
    }
    ```
 
+   `ActivateApp()` alone does not measure app opens. It sends the install ping
+   and starts activity tracking, but facebook-core 19.0.0 logs the activation
+   and deactivation events through its automatic-event path, which drops them
+   while automatic logging is off. With `SetAutoLogAppEventsEnabled(false)`,
+   the app reports the install and nothing else.
+
+   Automatic logging also turns on automatic Google Play purchase and
+   subscription logging. When a server already reports purchases (see
+   [Avoid double counting](#avoid-double-counting-with-server-side-events)),
+   set "Log In-App Purchases Automatically" and "Log In-App Subscriptions
+   Automatically" to "No" on the Android card of the Meta App Dashboard
+   (Settings > Basic) before you enable it. In Events Manager, leave the
+   dataset's automatic SDK event logging setting unspecified so the app
+   decides: disabling it there overrides a local `true` once the SDK cached
+   the app settings, and app opens stop.
+
+   `SetAutoLogAppEventsEnabled` persists its value across launches, so the
+   withdrawal branch must set it back to `false` (step 3).
+
    When consent is first granted from a dialog, the activity is already
    resumed, so that session's activation is only counted from the next resume.
    Do not log `fb_mobile_activate_app` yourself to make up for it: the SDK owns
@@ -172,18 +189,17 @@ SDK (see the strictest setup below).
    ```
 
    Withdrawal fully takes effect on the next process start. Until then the
-   SDK stays fully initialized: it keeps flushing queued events and, once
-   `ActivateApp()` or automatic logging started activity tracking, keeps
-   logging `fb_mobile_activate_app` and deactivation on every resume; none of
-   the switches above stops that. So:
+   SDK stays fully initialized and keeps flushing queued events. Activity
+   tracking keeps running too, but `SetAutoLogAppEventsEnabled(false)` stops
+   the activation, deactivation and automatic purchase events at once: the SDK
+   checks the flag for every automatic event. So:
 
    - gate your own `Log*` calls on the consent state, so manual events stop at
      once;
    - set `ExplicitOnly` and do not call `Flush()` until the process restarts,
      so nothing more is sent in this process;
-   - events already queued (including the activation events logged meanwhile)
-     stay in the SDK's disk queue, and a later fully initialized session (after
-     consent is granted again) sends them.
+   - events already queued stay in the SDK's disk queue, and a later fully
+     initialized session (after consent is granted again) sends them.
 
    The SDK cannot delete events it already sent; that goes through Meta's data
    deletion process.
@@ -247,9 +263,12 @@ event ID shared by both sides, and such integrations do not coordinate one with
 the SDK. When a server already sends trial, subscription or purchase events:
 
 - do not log those events from the app as well;
-- disable automatic purchase logging: keep `AutoLogAppEventsEnabled=false` and
-  call `ActivateApp()` (install and activation are still measured), and/or set
-  "Log In-App Events Automatically" to "No" in the Meta App Dashboard.
+- disable automatic purchase logging on the Android card of the Meta App
+  Dashboard (Settings > Basic): "Log In-App Purchases Automatically" and "Log
+  In-App Subscriptions Automatically" on "No". Keep `AutoLogAppEventsEnabled`
+  on after consent if you measure app opens: they are automatic events too.
+  With `AutoLogAppEventsEnabled=false`, `ActivateApp()` only measures the
+  install.
 
 ### Identity
 

samples/Kapusch.Facebook.Android.Sample/README.md

@@ -44,12 +44,15 @@ the untracked `strings.xml` only; never commit them.
 The manifest template sets every automatic collection switch to `false`
 (`AutoInitEnabled`, `AutoLogAppEventsEnabled`, `AdvertiserIDCollectionEnabled`,
 `AutoLogMetaDataEnabled`, `AutoLogProductImprovementEnabled`). The sample's
-"Grant ads consent" button enables auto-init and advertiser ID collection, then
-calls `ActivateApp()` with automatic logging still off (activation is logged
-from the next resume on); "Withdraw ads consent" reverts them and sets the
-flush behavior to `ExplicitOnly`, because the SDK keeps tracking activation
-until the process restarts. Debug builds enable `SetDebugLoggingEnabled(true)`, so logged and
-flushed events appear in `adb logcat`. Use Meta Events Manager > Test events to
+"Grant ads consent" button enables auto-init, advertiser ID collection and
+automatic logging, then calls `ActivateApp()` (install ping; activation is
+logged from the next resume on, and only while automatic logging is on);
+"Withdraw ads consent" reverts them and sets the flush behavior to
+`ExplicitOnly`, because the SDK keeps flushing queued events until the process
+restarts. Automatic logging also enables automatic purchase logging: turn it
+off on the Android card of the Meta App Dashboard if you test purchases. Debug
+builds enable `SetDebugLoggingEnabled(true)`, so logged and flushed events
+appear in `adb logcat`. Use Meta Events Manager > Test events to
 confirm delivery.
 
 ### Access token attribution check

samples/Kapusch.Facebook.Android.Sample/src/MainActivity.cs

@@ -86,11 +86,12 @@ private static void GrantConsent()
 		FacebookAppEvents.SetFlushBehavior(FacebookAppEventsFlushBehavior.Auto);
 		FacebookAppEvents.SetAutoInitEnabled(true);
 		FacebookAppEvents.SetAdvertiserIdCollectionEnabled(true);
-		// Keep automatic logging off (no purchase auto-logging) and log activation explicitly.
-		// ActivateApp sends the one-time install ping and logs activation from the next activity
-		// resume on; this screen is already resumed, so the current session is not counted. A real
+		// App opens are automatic events, so they need automatic logging on. Turn automatic purchase
+		// logging off in the Meta App Dashboard when a server reports purchases.
+		FacebookAppEvents.SetAutoLogAppEventsEnabled(true);
+		// ActivateApp sends the one-time install ping; activations are logged from the next activity
+		// resume on. This screen is already resumed, so the current session is not counted. A real
 		// app calls it on every launch with consent, before the first activity resumes.
-		FacebookAppEvents.SetAutoLogAppEventsEnabled(false);
 		FacebookAppEvents.ActivateApp();
 	}
 
@@ -101,8 +102,9 @@ private static void WithdrawConsent()
 		FacebookAppEvents.SetAutoInitEnabled(false);
 		FacebookAppEvents.ClearUserId();
 		FacebookAppEvents.ClearUserData();
-		// The SDK stays fully initialized and keeps tracking activation until the process restarts.
-		// Stop sending for this process; a real app also stops calling the Log* methods.
+		// Automatic events stop at once, but the SDK stays fully initialized and keeps flushing queued
+		// events until the process restarts. Stop sending for this process; a real app also stops
+		// calling the Log* methods.
 		FacebookAppEvents.SetFlushBehavior(FacebookAppEventsFlushBehavior.ExplicitOnly);
 	}
 

src/Kapusch.FacebookApisForAndroidComponents/Facebook/FacebookAppEvents.cs

@@ -19,10 +19,11 @@ namespace Kapusch.Facebook.Android;
 /// </para>
 /// <para>
 /// Turning switches off does not stop the SDK for the current process: it stays fully initialized,
-/// keeps flushing queued events and, once <see cref="ActivateApp"/> or automatic logging started
-/// activity tracking, keeps logging activation on every activity resume. Withdrawal fully applies
-/// on the next process start. Until then, stop calling the <c>Log*</c> methods and set
-/// <see cref="FacebookAppEventsFlushBehavior.ExplicitOnly"/> without calling <see cref="Flush"/>.
+/// keeps flushing queued events and keeps activity tracking running.
+/// <see cref="SetAutoLogAppEventsEnabled"/> with <see langword="false"/> stops the automatic events
+/// (activation, deactivation, purchases) at once. Withdrawal fully applies on the next process start. Until then, stop calling the
+/// <c>Log*</c> methods and set <see cref="FacebookAppEventsFlushBehavior.ExplicitOnly"/> without
+/// calling <see cref="Flush"/>.
 /// </para>
 /// <para>
 /// Every setter, the identity methods and the event methods throw
@@ -129,11 +130,18 @@ public static void InitializeSdk(
 
 	/// <summary>
 	/// Sets the persisted automatic App Events logging flag. <see langword="true"/> starts activity
-	/// tracking, which requires an initialized SDK. Automatic logging covers the install ping, app
-	/// activation and, when enabled in Events Manager, in-app purchases and subscriptions.
-	/// <see langword="false"/> does not stop activity tracking already started in this process; it
-	/// applies from the next process start.
+	/// tracking, which requires an initialized SDK. Automatic logging covers the SDK's automatic
+	/// events: app activation and deactivation (also when <see cref="ActivateApp"/> started
+	/// tracking) and, when enabled on the Android card of the Meta App Dashboard, in-app purchases and
+	/// subscriptions. It does not send the install ping; <see cref="ActivateApp"/> does.
+	/// <see langword="false"/> stops automatic events at once (the SDK checks the flag for each one)
+	/// but leaves activity tracking running until the process ends.
 	/// </summary>
+	/// <remarks>
+	/// The value persists across launches. The effective value (<see cref="IsAutoLogAppEventsEnabled"/>)
+	/// is <see langword="false"/> when either this value or the Events Manager setting cached by the SDK
+	/// is disabled.
+	/// </remarks>
 	public static void SetAutoLogAppEventsEnabled(bool enabled) =>
 		CallVoid("setAutoLogAppEventsEnabled", "(Z)V", new JValue(enabled));
 
@@ -198,16 +206,17 @@ public static void SetFlushBehavior(FacebookAppEventsFlushBehavior behavior)
 	}
 
 	/// <summary>
-	/// Sends the one-time install ping and starts activation tracking
-	/// (<c>AppEventsLogger.activateApp</c>): the SDK logs <c>fb_mobile_activate_app</c> and
-	/// deactivation from the next activity resume on. An activity already resumed when this runs is
-	/// not counted, so call it on every launch before the first activity resumes, for example from
+	/// Sends the one-time install ping and starts activity tracking
+	/// (<c>AppEventsLogger.activateApp</c>). App opens (<c>fb_mobile_activate_app</c>) and
+	/// deactivation are automatic events: the SDK logs them from the next activity resume on only
+	/// while <see cref="SetAutoLogAppEventsEnabled"/> is <see langword="true"/>. With automatic
+	/// logging off, this measures the install only. An activity already resumed when this runs is not
+	/// counted, so call it on every launch before the first activity resumes, for example from
 	/// <c>Application.OnCreate</c> or <c>MainActivity.OnCreate</c>. When it runs right after a consent
-	/// dialog, that session is only counted from the next resume. Use it when automatic logging is
-	/// disabled and the consumer still wants install and launch measurement. Call it once the SDK is
-	/// fully initialized (<see cref="SetAutoInitEnabled"/> or <see cref="InitializeSdk"/>); before
-	/// that the SDK discards the install ping response and only retries on a later activation.
-	/// Tracking cannot be stopped until the process ends.
+	/// dialog, that session is only counted from the next resume. Call it once the SDK is fully
+	/// initialized (<see cref="SetAutoInitEnabled"/> or <see cref="InitializeSdk"/>); before that the
+	/// SDK discards the install ping response and only retries on a later activation. Tracking cannot
+	/// be stopped until the process ends.
 	/// </summary>
 	public static void ActivateApp(Context? context = null) =>
 		CallVoid("activateApp", "(Landroid/content/Context;)V", new JValue(ResolveContext(context)));