[Kapusch]

Summary

Release 1.2.0 (to be published first as 1.2.0-rc.1, not tagged yet):

1. Facebook Android SDK 18.1.3 → 19.0.0 (own commit). All five AARs locked by SHA-256 (cross-checked against Maven Central .sha1). The AAR manifests and POM dependency sets are identical to 18.1.3, except installreferrer 1.0 → 2.2 in facebook-core. 19.0.0 adds Google Play Billing Library 8 auto-logging and the AutoLogMetaDataEnabled / AutoLogProductImprovementEnabled controls.
2. New selectable AppEvents feature. KapuschFacebookFeatures now accepts AppEvents alone or combined, e.g. Login;AppEvents. The default stays Login.
3. Managed FacebookAppEvents API over a static Java facade, called through JNI.
4. Validators wired into CI and publish, plus an R8 build of the sample.
5. Docs: integration, consent gating, double counting, upgrade notes.

Public C# API (namespace Kapusch.Facebook.Android)

• FacebookAppEvents (static):
  • SDK state: InitializeSdk(Context? = null, string[]? dataProcessingOptions = null, int dataProcessingCountry = 0, int dataProcessingState = 0), IsSdkInitialized, IsSdkFullyInitialized
  • SDK switches, each a Set* method plus an Is* getter: SetAutoInitEnabled, SetAutoLogAppEventsEnabled, SetAdvertiserIdCollectionEnabled, SetMetadataCollectionEnabled, SetAutoLogProductImprovementEnabled
  • other settings: SetDataProcessingOptions(string[], int country = 0, int state = 0), SetDebugLoggingEnabled(bool) (debug mode plus the APP_EVENTS logging behavior), SetFlushBehavior(FacebookAppEventsFlushBehavior) with the FlushBehavior getter
  • events: ActivateApp(Context? = null), LogEvent(string eventName, IReadOnlyDictionary<string, object>? = null, double? valueToSum = null), LogPurchase(decimal, string currencyIsoCode, parameters?)
  • typed helpers: LogStartTrial(decimal? value, string? currency, string? orderId, parameters?), the same signature for LogSubscribe, and LogCompleteRegistration(string? registrationMethod, decimal? value, string? currencyIsoCode, parameters?)
  • Flush()
  • identity: GetAnonymousId() (string?), SetUserId(string?), GetUserId(), ClearUserId(), SetUserData(FacebookAppEventsUserData) (replaces every field; null clears), ClearUserData()
  • every setter, identity call and event call throws Java.Lang.IllegalStateException before sdkInitialize
• Constants generated from the bundled AppEventsConstants: FacebookAppEventNames, FacebookAppEventParameterNames and FacebookAppEventParameterValues, 77 constants in total.
• Support types: FacebookAppEventsUserData (sealed record), FacebookAppEventsFlushBehavior, FacebookDataProcessingOptions.LimitedDataUse.
• The App Events names match the Kapusch.Facebook.iOS package so shared code compiles on both; Integration.md lists the shared surface and the Android-only members.
• Android has no iOS-only features: ATT, SKAdNetwork, AEM and URL forwarding. Not wrapped: push-open logging, product items, WebView augmentation, codeless setup and manual install referrer. These gaps are documented in Docs/Integration.md.

Why these choices

• Extending this package instead of creating a new one. facebook-core is already always injected. A separate App Events package would ship a second facebook-core, causing duplicate classes and version skew. App Events therefore needs no new AAR: the facade lives in the existing interop AAR.
• Plain Java static class, not a Kotlin object. The interop module is Java-only. A class with public static methods has the same JNI shape as object + @JvmStatic. Using it avoids adding the Kotlin Gradle plugin and Kotlin metadata keep rules. The C# side follows the Kapusch.PostHog.Android pattern: JNIEnv.FindClass and cached static method IDs, with local references released after each call.
• Purchase amounts and decimal parameters cross JNI as invariant strings. The SDK builds a BigDecimal and stringifies every parameter, so no precision is lost to double.
• Install Referrer comes from the consumer's managed NuGet, not bundled and not a hard dependency. facebook-core reads the referrer only when com.android.installreferrer classes are present.
  • Bundling the AAR would create duplicate classes with other SDKs that use Microsoft's Xamarin.Google.Android.InstallReferrer binding.
  • A hard NuGet dependency would change the graph and the collected data for Login-only consumers.
  • Instead, the AppEvents feature emits warning KFBA001 when no referrer library is referenced. It can be silenced with KapuschFacebookAndroidSuppressInstallReferrerWarning=true.
  • Caveat, documented: that Microsoft binding downloads installreferrer-2.2.aar from Google Maven on the consumer's first build (Xamarin.Build.Download). This is why the package recommends it but does not depend on it.
• R8 rules.
  • The existing consumer rule already keeps com.kapusch.facebook.androidinterop.**. The facade is reachable only through JNI.
  • facebook-core's own proguard.txt covers its install-referrer and GMS reflection.
  • It does not keep com.android.billingclient.api.*, which it uses through reflection for purchase auto-logging. AppEvents therefore injects buildTransitive/proguard/kapusch-facebook-appevents.pro, which keeps the public Play Billing API. The rule is inert without Billing, and Login- and Share-only apps never receive it.
  • The R8 run showed that .NET for Android passes -dontobfuscate, so the real risk is shrinking rather than renaming. The rule's comment says so.
• FacebookInitProvider behaviour is unchanged.
  • InitializeSdk() only calls sdkInitialize when the provider has not already done so, then calls fullyInitialize.
  • Setters map one to one to upstream, and the wrapper sets no defaults.
  • Every setter, identity call and event call fails with an actionable IllegalStateException on an uninitialized SDK, instead of the SDK dropping it silently (see review follow-up).
• Bundle typing. Accepted value types: string; bool, sent as "1"/"0", the SDK's YES/NO values; integral types; finite float/double; and decimal. Anything else throws ArgumentException, because the SDK rejects non-string, non-numeric values.

Behaviour for existing consumers

• Same injected AARs and same merged manifest. I built a clean consumer with default features against 1.1.0 from NuGet.org and against this 1.2.0 package. The merged AndroidManifest.xml files are byte-identical apart from the generated-from comment, and the lp/ AAR set is the same: bolts, common, core, login and the interop AAR.
• No KFBA001 and no new R8 rule for consumers that do not select AppEvents.
• The SDK itself behaves differently in 19.0.0. These changes are listed under "Upgrading to 1.2.0" in Integration.md:
  • Billing 8 purchases can now be auto-logged when Meta enables it server side.
  • Events carry the screen title and AppLink URL unless AutoLogMetaDataEnabled=false.
  • A local AutoLogAppEventsEnabled=false now wins over the Events Manager setting.

Pre-existing issues fixed along the way

• The sample never applied the default Login feature. It imported only the .targets, so facebook-login was not injected. It now imports the .props like NuGet does, and Docs/SourceMode.md says to do the same.
• The sample crashed at launch with NoClassDefFoundError: androidx.localbroadcastmanager.... facebook-core needs this class, and a bare AppCompat app does not include it. The sample had only ever been built, never run. It now references Xamarin.AndroidX.LocalBroadcastManager, and Integration.md lists the AndroidX and Kotlin runtime dependencies the app must provide.

Validation (local: .NET 10.0.203, JDK 21, Android SDK 36, Android workload 36.1.53)

• python3 scripts/verify-public.py: passes. It rejects real Meta app IDs, client tokens and emails, plus private terms read only from an untracked source (KAPUSCH_PRIVATE_TERMS secret in CI, .git/info/private-terms locally). Negative test: a configured term that occurs in the tree fails the scan and the output names only "private term Add Facebook Android interop wrapper and documentation #1".
• bash tests/validate-feature-selection.sh: covers 6 feature combinations and 5 KFBA001 cases.
• python3 scripts/app-event-constants.py: the 77 constants match facebook-core 19.0.0.
• python3 scripts/verify-interop.py jni: all 28 managed JNI calls match the javap -s descriptors in the wrapper AAR.
• dotnet pack then python3 scripts/validate-package.py artifacts/nuget: checks the deps set and SHA-256 against the lockstate, a single SDK version, no bundled AndroidX/Kotlin/Google artifacts, wrapper classes and keep rule, a default of Login, and the AppEvents wiring.
• Sample builds:
  • Debug: passes.
  • Release with R8, then verify-interop.py apk: the facade, every called method and the SDK entry points survive in the dex.
• Package-mode consumer (Login;AppEvents, R8, packed nupkg): KFBA001 fires without the referrer library, and the APK check passes.
• Runtime smoke test: R8 Release x86_64 build of the sample on an API 36 emulator, with the consent switches set to off in the manifest.
  • The getters reflect the manifest values, and GetAnonymousId() returns an XZ… ID.
  • After "Grant consent", the SDK reports itself fully initialized, with auto-init and advertiser ID on.
  • StartTrial, Subscribe, the custom event and Flush all ran without exceptions.
  • The Graph calls were rejected only because of the placeholder app ID.
  • After withdrawing consent and relaunching, the SDK logs GraphRequest can't be used when Facebook SDK isn't fully initialized, which is now documented.
• Not done: delivery to Meta Events Manager > Test events. This needs a real Meta app ID and token, and none are committed.

Review follow-up (history rewritten and rebased on current master)

The branch was rebased onto master (which now has #5, the CI toolchain pins) and rewritten before merge, so that the review's genericity finding never reaches master:

• Public-tree scanner no longer embeds a private term. The hex-escaped pattern is gone from scripts/verify-public.py in every commit. Private terms come from the optional KAPUSCH_PRIVATE_TERMS repository secret (wired in ci.yml and publish.yml; the check is skipped with a notice when it is unset) or the untracked .git/info/private-terms. Output never prints the term, because Actions logs on a public repo are public.
• Commit hygiene. The .pro wording now lands in the packaging commit, and the version bump is its own chore(release) commit at the end.

New commits on top:

1. fix(appevents): create a logger per call — AppEventsLogger captures the current access token at construction and sends every event under it (checked with javap on 19.0.0). The cached process-wide logger kept tagging post-logout events with the signed-out user's token. Construction is cheap because the queue is static. The sample README gives a manual log-in/log-out check (by inspecting POST /<app id>/activities, since the SDK redacts tokens in logcat).
2. fix(appevents): fail before SDK init and apply LDU in InitializeSdk — before sdkInitialize, FacebookSdk.setDataProcessingOptions throws inside CrashShield, which swallows it, so SetDataProcessingOptions(LDU) + InitializeSdk() silently dropped LDU in the provider-removed setup. Now every setter, identity and event call throws until the SDK is initialized, and InitializeSdk takes the options and applies them between sdkInitialize and fullyInitialize, the only point where they reach the SDK's first Graph requests. InitializeSdk() with no arguments keeps working.
3. refactor(appevents): align the managed API with the iOS package — adopt the iOS names (eventName, LogCompleteRegistration value/currency, FacebookAppEvents* type names, SetMetadataCollectionEnabled, string? GetAnonymousId) and the iOS user-data semantics (a null field clears it; the facade calls clearUserData before setUserData, both on the SDK's single-threaded executor). The constants generator now spells AppLink/IPhone/IPad like the iOS constants. Why iOS's names rather than Android's: the review's explicit suggestions (eventName, value/currency on registration, nullable anonymous ID) already matched iOS, so following iOS for the remaining names keeps a single direction of change. Nothing has been released with the old names.
4. docs(appevents): state that withdrawal applies at the next process start — setAutoInitEnabled(false) never clears the fully-initialized state, and the lifecycle callbacks registered by ActivateApp keep logging activation on every resume. The recipe now says so, recommends gating the app's own Log* calls plus ExplicitOnly without further Flush(), and notes that queued events stay on disk. ActivateApp docs now say activation is logged from the next resume, and recommend calling it on every launch before the first activity resumes. No facade-level kill switch: it would be Android-only, and gating at the call site already stops manual events at once.
5. chore(release): bump package version to 1.2.0.

Re-validated after the rewrite: native build, AAR restore, pack, validate-package.py (17 entries), verify-public.py (with a private term configured), constants (77), JNI contract (28 calls), feature selection and KFBA001, Debug sample, and Release R8 sample (arm64) + verify-interop.py apk. No new runtime smoke test was run for these changes.

Checklist

• No secrets committed (samples use all-zero placeholders; the scan enforces it)
• Built wrapper: bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/build.sh
• Restored pinned AARs: bash src/Kapusch.FacebookApisForAndroidComponents/Native/Android/restore-facebook-aars.sh
• Packed NuGet: dotnet pack src/Kapusch.FacebookApisForAndroidComponents/Kapusch.FacebookApisForAndroidComponents.csproj -c Release -o artifacts/nuget
• Ran the validators listed in README.md
• Updated docs

Next, after merge: tag v1.2.0-rc.1 on the merge commit, following Docs/Release.md.

🤖 Generated with Claude Code