LeroyGumede.AdobeAnalytics.Maui.Android 0.1.6

AdobeAnalytics.Maui

.NET 10 MAUI bindings and a platform-neutral analytics facade for Adobe Experience Platform Mobile SDK.

This repository contains:

• LeroyGumede.AdobeAnalytics.Maui: DI-ready MAUI abstraction and Android/iOS native adapters.
• LeroyGumede.AdobeAnalytics.Maui.Android: .NET Android binding project using official Adobe Maven artifacts.
• LeroyGumede.AdobeAnalytics.Maui.iOS: .NET iOS binding project for official Adobe XCFrameworks built from Adobe Swift packages.
• AdobeAnalytics.Maui.Sample: MAUI MVVM sample app for Android and iOS.
• Unit tests plus manual Adobe Assurance integration-test gates.

Architecture

New implementations should prefer Adobe Experience Platform Edge Network and schema-compliant XDM events. Edge Bridge remains available when an app must preserve Adobe Analytics-style trackAction and trackState workflows, while Direct Analytics remains available as a compatibility mode.

Default mode in this wrapper is AdobeAnalyticsArchitecture.EdgeNetwork:

1. Register Core, Edge, Edge Identity, Consent, Lifecycle, Signal, and optionally Assurance.
2. Configure the SDK with the public Adobe Mobile App ID from Adobe Data Collection.
3. Build nested XDM page-view and link-click events matching the Nedbank schema.
4. Send those events through Edge.sendEvent to the services configured in the datastream.

The MAUI app consumes only IAdobeAnalyticsService; native Adobe types are kept inside platform adapters.

Compatibility Matrix

Primary references:

• https://developer.adobe.com/client-sdks/home/current-sdk-versions
• https://developer.adobe.com/client-sdks/home/getting-started/
• https://developer.adobe.com/client-sdks/solution/adobe-analytics/
• https://developer.adobe.com/client-sdks/edge/edge-bridge/
• https://experienceleague.adobe.com/en/docs/experience-platform/assurance/home
• https://developer.adobe.com/client-sdks/home/base/assurance/api-reference
• https://github.com/adobe/aepsdk-analytics-android

Installation

Local feed:

powershell -ExecutionPolicy Bypass -File build\pack.ps1 -Configuration Release
dotnet nuget add source "$PWD\artifacts\packages" --name AdobeAnalyticsMauiLocal
dotnet add <your-app>.csproj package LeroyGumede.AdobeAnalytics.Maui --version 0.1.6

The shared package brings in the appropriate native binding for Android and iOS. It includes the Adobe XCFrameworks in the iOS NuGet package, so consuming apps do not need a separate native-framework fetch step.

Configuration

Do not commit Adobe environment IDs for production apps. The sample reads:

• ADOBE_MOBILE_APP_ID
• ADOBE_EXPERIENCE_CLOUD_ORG_ID
• ADOBE_ENABLE_ASSURANCE
• ADOBE_ANALYTICS_ARCHITECTURE
• ADOBE_ANALYTICS_LOG_LEVEL

The Mobile App ID / environment file ID and Experience Cloud Org ID are public configuration identifiers, not client secrets, but they still identify your Adobe organisation and environment. Treat API keys, OAuth client secrets, private keys, signing credentials, and service-account credentials as secrets. Do not put those in a MAUI app.

MAUI registration:

builder.Services.AddAdobeAnalytics(options =>
{
    options.AppId = configuration.AdobeAppId;
    options.ExperienceCloudOrgId = configuration.ExperienceCloudOrgId;
    options.EnableLifecycleTracking = true;
    options.EnableAssurance = configuration.EnableAdobeAssurance;
    options.Architecture = AdobeAnalyticsArchitecture.EdgeNetwork;
});

When EnableLifecycleTracking is true, the package automatically dispatches Adobe lifecycle start and pause events as the app enters the foreground and background. Android activity callbacks and iOS application notifications are handled internally; consumers should not add duplicate platform lifecycle calls.

ExperienceCloudOrgId is optional and should normally come from the Adobe Data Collection mobile property downloaded by MobileCore.configureWithAppID. Set it only as a fallback when Assurance logs SDK configuration is not available to read OrgId while the Adobe property is being corrected.

Startup:

_ = Task.Run(() => analyticsService.InitialiseAsync(adobeOptions));

ViewModel usage:

await _analyticsService.TrackScreenAsync(
    "product_details",
    new Dictionary<string, string>
    {
        ["product_id"] = product.Id,
        ["product_category"] = product.Category
    },
    cancellationToken);

Event Naming

Use lower snake_case event names. Keep names stable and business-readable:

• screen_view
• product_viewed
• product_selected
• login_success
• logout
• analytics_consent_updated

Use context data for dimensions, not event-name suffixes. Example: product_selected with product_id, product_category, and price_band.

In Edge Network mode, screen calls produce web.webPageDetails.pageViews XDM events and action calls produce web.webInteraction.linkClicks events. The wrapper maintains the previous screen name and sends it as _nedbank.pageInformation.previousPageName from the second screen view onward.

Privacy And Security

The service defaults to Adobe-managed consent (RequireConsentBeforeTracking = false) so the Consent extension and published mobile-property configuration remain the source of truth. Calling SetConsentAsync(OptOut) always blocks subsequent events and clears queued events. Set RequireConsentBeforeTracking = true only when the host app explicitly calls SetConsentAsync(OptIn) after its own consent flow.

The sanitizer allow-list rejects unapproved context keys and removes values that look like email addresses, bearer tokens, or card numbers. Do not collect passwords, tokens, identity numbers, account numbers, card details, email addresses, phone numbers, precise location, or free-form text.

POPIA/GDPR checklist:

• Capture explicit analytics consent where required before tracking.
• Honour withdrawal immediately; this wrapper clears queued events on opt-out.
• Keep an event catalogue and data classification owner.
• Document retention in Adobe Analytics / Experience Platform datasets.
• Use Adobe privacy workflows for access and deletion requests.
• Use pseudonymous customer IDs only; do not send raw email, phone, national ID, or account numbers.
• Keep analytics calls non-blocking for startup and transaction flows.

Android Binding Notes

The Android binding uses official Maven artifacts with fixed versions. AndroidMavenLibrary downloads Adobe artifacts reproducibly; AndroidX/Kotlin dependencies are represented as NuGet packages where .NET Android requires them.

Minimum API level: 21.

Release guidance:

dotnet build src\AdobeAnalytics.Maui.Android\AdobeAnalytics.Maui.Android.csproj -c Release
dotnet build samples\AdobeAnalytics.Maui.Sample\AdobeAnalytics.Maui.Sample.csproj -c Release -f net10.0-android
dotnet publish samples\AdobeAnalytics.Maui.Sample\AdobeAnalytics.Maui.Sample.csproj -c Release -f net10.0-android /p:AndroidPackageFormat=aab

R8 rules are in src/AdobeAnalytics.Maui.Android/proguard-adobe.pro.

iOS Binding Notes

The iOS binding keeps Adobe binaries out of source control. The package script downloads checksum-verified XCFrameworks from Adobe's official GitHub releases before packing. For local source builds on a Mac:

bash build/fetch-ios-xcframeworks.sh
dotnet build src/AdobeAnalytics.Maui.iOS/AdobeAnalytics.Maui.iOS.csproj -c Release -f net10.0-ios
dotnet build samples/AdobeAnalytics.Maui.Sample/AdobeAnalytics.Maui.Sample.csproj -c Release -f net10.0-ios

Requirements:

• iOS 12 or later.
• Xcode 15 or later; use the Xcode version required by the installed .NET 10 iOS workload.
• Apple signing identity and provisioning profile for device/archive builds.

Adobe Experience Platform Assurance

Adobe Experience Platform Assurance provides a live view of Mobile SDK events, logs, configuration, shared state, and extension versions. The sample registers the native Assurance extension when ADOBE_ENABLE_ASSURANCE=true and demonstrates both connection modes described by Adobe:

• Deep Link Connect: Android registers an intent filter and iOS registers a custom URL scheme. Use adobeanalyticsmaui://assurance as the Base URL when creating the session. Scan the generated QR code to launch the sample, or paste the complete generated URL into Settings and select Connect with session URL. A valid generated URL contains the adb_validation_sessionid query parameter.
• Quick Connect: run a Debug build, open Settings, and select Start Quick Connect (Debug). In the Assurance UI, create a Quick Connect session and select the device when it appears. Adobe makes this API a no-op for non-debuggable builds.

The equivalent service calls are:

// Quick Connect (Debug builds only)
await analyticsService.StartAssuranceSessionAsync();

// Deep Link Connect
await analyticsService.StartAssuranceSessionAsync(generatedSessionUrl);

Assurance Verification

1. In the Adobe Data Collection UI, install the AEP Assurance extension in the mobile property and publish the updated environment.
2. Configure Edge/Analytics forwarding, then set ADOBE_MOBILE_APP_ID and ADOBE_ENABLE_ASSURANCE=true for the sample.
3. Confirm the published environment contains experienceCloud.org; Assurance cannot authenticate without the Experience Cloud Org ID. Use ADOBE_EXPERIENCE_CLOUD_ORG_ID only as a temporary fallback while correcting the property.
4. Launch a Debug build of the sample and opt in to analytics in Settings.
5. In the Assurance UI, create either a Deep Link Connect session with Base URL adobeanalyticsmaui://assurance or a Quick Connect session.
6. For Deep Link Connect, scan the QR code (or paste the generated session URL in Settings) and enter the displayed PIN. For Quick Connect, select Start Quick Connect (Debug) in the sample and then select the device in Assurance.
7. Confirm the red Adobe Experience Platform icon appears in the app, then navigate through Home, Products, Product Details, Settings, and Diagnostics.
8. In the Assurance event list and Adobe Analytics view, verify screen_view, product_selected, product_viewed, login_success, logout, and analytics_consent_updated.
9. Opt out and verify subsequent product events are not collected; log out and verify identity reset behaviour.

See Adobe's Assurance usage guide, Mobile SDK API reference, and common-issues guide for session creation and troubleshooting.

Assurance Org ID Troubleshooting

Assurance/AssuranceStateManager - SDK configuration is not available to read OrgId means Assurance could not read experienceCloud.org from Mobile Core configuration. Check these in order:

• The Mobile App ID points to the correct Data Collection mobile property and environment.
• That environment is published after adding Assurance plus the Edge/Identity extensions required by your architecture.
• The Assurance session was created in the same Adobe organization as the mobile property.
• The app waits briefly after initialization before starting Assurance; this package defaults to a 2 second AssuranceSessionStartDelay.
• As a fallback, provide AdobeAnalyticsOptions.ExperienceCloudOrgId from environment-specific configuration. This calls MobileCore.updateConfiguration with experienceCloud.org before starting Assurance.

Build And Test

dotnet restore AdobeAnalyticsMaui.slnx
dotnet build src\AdobeAnalytics.Maui.Android\AdobeAnalytics.Maui.Android.csproj -c Debug
dotnet build src\AdobeAnalytics.Maui\AdobeAnalytics.Maui.csproj -c Debug -f net10.0-android
dotnet build src\AdobeAnalytics.Maui\AdobeAnalytics.Maui.csproj -c Debug -f net10.0-ios
dotnet build samples\AdobeAnalytics.Maui.Sample\AdobeAnalytics.Maui.Sample.csproj -c Debug -f net10.0-android
dotnet test AdobeAnalyticsMaui.slnx -c Debug
powershell -ExecutionPolicy Bypass -File build\pack.ps1 -Configuration Release

Known Limitations And Binding Risks

• iOS IdentityMap update is documented but not yet implemented in the shared iOS adapter; generated AEPEdgeIdentity coverage should be expanded before production identity stitching on iOS.
• Building an iOS app from source still requires a Mac, Xcode, and the .NET iOS workload. Consuming the published NuGet does not require rebuilding Adobe's XCFrameworks.
• Android Assurance includes Services UI internals. The managed binding intentionally removes those UI internals while preserving native binaries.
• Adobe SDK Kotlin internals expose generated members that are not useful from C#; metadata transforms suppress or remove problematic managed surfaces.
• App Store and Play Store release builds still require normal app signing configuration outside this repo.
• iOS archive validation requires a macOS runner with Xcode and the .NET iOS workload; package validation rejects an iOS NuGet that omits any required Adobe XCFramework.
• Android Release AAB builds with trimming and AOT can emit XA4301 warnings for duplicate libandroidx.graphics.path.so files from the AndroidX graphics package graph. .NET Android ignores the duplicate entries and the sample Release AAB build succeeds; do not treat XA4301 as an error unless you first remove the duplicate native asset source.

Licensing And Redistribution

This repository is MIT licensed. Adobe SDKs are third-party dependencies distributed by Adobe under their own licenses, currently Apache 2.0 in the public SDK repositories. Review Adobe repository LICENSE files before publishing a package that redistributes native binaries. Adobe and Adobe Experience Platform names are Adobe trademarks; package descriptions should state interoperability and must not imply Adobe endorsement.

If publishing public NuGet packages, prefer packages that restore official Maven artifacts and document how iOS XCFrameworks are obtained. Do not upload Adobe credentials, Adobe organisation secrets, signing certificates, or private configuration.