ARBook a Demo
Developer documentation

KePixel Mobile Tracking for Android

Follow the Android implementation path, send only the events that matter for your business model, and verify the signal before release.

1 · Add Firebase to this app
↓
2 · Install Firebase Analytics SDK + Mobile GTM
↓
3 · Add the KePixel Mobile GTM container file
↓
4 · Paste the Server Tagging URL
↓
5 · Implement events + verify

Implementation flow

This is the work the app developer must do. Complete it in order.

Add Firebase to this app

Register the exact Android package name or iOS Bundle ID and add the correct Firebase configuration file to this app target.

Install Firebase Analytics and verify DebugView

Install Analytics, run a development build, log one event, and confirm it appears in Firebase / GA4 DebugView.

Set authenticated User-ID when accounts exist

After sign-in, set one stable internal non-PII user_id. Clear it on logout. Never use email or phone as the User-ID.

Install Google Tag Manager Mobile

Install Mobile GTM for this platform and add the exact container file downloaded from KePixel → Sources → this mobile app → Setup.

Enable mobile server-side upload

Apply the platform-specific setting below, then paste the Server Tagging URL from KePixel Setup into the matching GA4 App Data Stream.

Implement the Essential business events

Start with the Essential events for the app's actual business model. Add Recommended events only when they add reliable funnel, product, revenue, or attribution context.

Preserve campaign attribution and verify

Keep Firebase automatic campaign signals intact. If the app explicitly receives campaign or deep-link metadata, use campaign_details. Verify an Essential event in DebugView, then confirm Test event received in KePixel.

Find the KePixel values in Source Setup

Open KePixel → Sources → this mobile app → Setup. You do not need KePixel GTM account access and you do not need to request these values manually.

KePixel Android Tracking ContainerKePixel iOS Tracking Container

In the KePixel Mobile Container card, click Download container file when the backend has prepared the installable container.

KePixel Server Tagging URL

In the KePixel Server Connection card, click Copy beside the exact KePixel Server Tagging URL.

Both values appear automatically for this source after KePixel provisioning completes. If a card still shows Preparing, open the source Overview tab and use Refresh source status; do not copy a file or URL from another app, tenant, or environment.

Before you start

Use a Firebase Project owned by the customer organization. Register the real app identifier used by this build and use only the configuration file for the platform selected above. KePixel does not require Firebase ownership, GTM account access, or destination credentials from the app developer.

Android

Android prerequisites

Use the real Android package name and Firebase's google-services.json. Place the file in the app module, normally app/google-services.json.

iOS

iOS prerequisites

Use the real case-sensitive Bundle ID and Firebase's GoogleService-Info.plist. Add the file to the Xcode project and the exact app target being integrated.

Open KePixel → Sources → this mobile app → Setup. The KePixel Mobile Container card exposes the platform-specific Download container file action, and the KePixel Server Connection card exposes the source-specific KePixel Server Tagging URL with Copy. These controls are populated automatically by KePixel provisioning.

Installation

Android

Android setup

Add the Android app to Firebase

Register the app with its real package name. Download google-services.json and place it in the app-module root, normally app/google-services.json. Apply the com.google.gms.google-services Gradle plugin so Firebase can read the configuration file.

Install Firebase Analytics

Use the Firebase Android BoM and add Analytics in the app module. Make sure the Google services plugin is applied in that same app module.

plugins { id("com.google.gms.google-services") } dependencies { implementation(platform("com.google.firebase:firebase-bom:34.16.0")) implementation("com.google.firebase:firebase-analytics") }

Install Google Tag Manager for Android

Add the current Google Play services Tag Manager dependency documented by Google.

dependencies { implementation("com.google.android.gms:play-services-tagmanager:18.3.0") }

Add the KePixel Android Tracking Container

Open KePixel → Sources → this Android app → Setup → KePixel Mobile Container and click Download container file. Create app/src/main/assets/containers if it does not exist, copy the downloaded container file into that folder, and keep its downloaded filename unchanged. GTM account access is not required.

Enable server-side GTM upload

Inside the <application> element of AndroidManifest.xml, add the Google Analytics server preview activity and the sGTM upload metadata. Replace the package placeholder with the lowercase application package ID.

<activity android:name="com.google.firebase.analytics.GoogleAnalyticsServerPreviewActivity" android:exported="true" android:noHistory="true"> <intent-filter> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="tagmanager.sgtm.c.com.example.app" /> </intent-filter> </activity> <meta-data android:name="google_analytics_sgtm_upload_enabled" android:value="true" />

Configure the GA4 Android App Data Stream

Copy the URL from KePixel → Sources → this Android app → Setup → KePixel Server Connection → KePixel Server Tagging URL → Copy. Then open Google Analytics → Admin → Data streams → Android app → Configure SDK settings → Configure server-side Tag Manager, enable sending to a server-side container, and paste that exact URL. Start with debug devices or a controlled traffic percentage if your rollout policy requires validation first.

Implement events

Use the Event Catalog below. Prefer Google's recommended Firebase/GA4 names and prescribed parameters.

Build and test

Build the app on a test device, then complete the Test your KePixel Mobile connection section below before releasing the app update.

iOS

iOS setup

Add the iOS app to Firebase

Register the real, case-sensitive Bundle ID. Download GoogleService-Info.plist, move it into the root of the Xcode project, and make sure it is included in the app target you are integrating.

Install Firebase Analytics

For new projects, use Swift Package Manager. Add https://github.com/firebase/firebase-ios-sdk.git in Xcode and select FirebaseAnalytics. Initialize Firebase when the app launches by calling FirebaseApp.configure() from your app delegate. SwiftUI apps should attach that app delegate with @UIApplicationDelegateAdaptor.

Install Google Tag Manager for iOS

With Swift Package Manager, add https://github.com/googleanalytics/google-tag-manager-ios-sdk.git and use the latest supported version. Add -ObjC to Other Linker Flags. If your project uses CocoaPods, Google's current guide documents pod 'GoogleTagManager', '~> 6.0'.

Add the KePixel iOS Tracking Container

Open KePixel → Sources → this iOS app → Setup → KePixel Mobile Container and click Download container file. Create PROJECT_ROOT/container, place the downloaded GTM-XXXXXX.json file inside it, then in Xcode choose File → Add Files to…, select the container folder, open Options, and make sure Create folder references is selected before finishing. You do not need access to KePixel's GTM account.

Enable server-side GTM upload

In Info.plist, configure the custom preview URL scheme tagmanager.sgtm.c.BUNDLE_ID and set GOOGLE_ANALYTICS_SGTM_UPLOAD_ENABLED to true. For SwiftUI/UIScene apps, forward the opened preview URL to Analytics.handleOpen(url) as documented by Google.

<key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleTypeRole</key> <string>None</string> <key>CFBundleURLName</key> <string>com.example.app</string> <key>CFBundleURLSchemes</key> <array> <string>tagmanager.sgtm.c.com.example.app</string> </array> </dict> </array> <key>GOOGLE_ANALYTICS_SGTM_UPLOAD_ENABLED</key> <true/>

SwiftUI preview handling: forward the opened server-side preview URL to Firebase Analytics.

import FirebaseAnalytics .onOpenURL { url in Analytics.handleOpen(url) }

Configure the GA4 iOS App Data Stream

Copy the URL from KePixel → Sources → this iOS app → Setup → KePixel Server Connection → KePixel Server Tagging URL → Copy. Then open Google Analytics → Admin → Data streams → iOS app → Configure SDK settings → Configure server-side Tag Manager, enable sending to a server-side container, and paste that exact URL.

Implement events

Use the same event contract below. Only installation code differs between Android and iOS.

Build and test

Run the app on a test device, then complete the Test your KePixel Mobile connection section below before releasing the app update.

Implement events

Start with the smallest signal set that represents the real customer journey.

More events do not automatically mean better tracking. Duplicate, premature or low-context events create noise. Implement an event only when the user action actually happens and use the same semantic event name on Android and iOS.

EssentialDo not skip when the flow applies

These events or fields carry the conversion/funnel signal KePixel needs for high-quality routing and optimization.

RecommendedStrong quality improvement

Send when the app knows the value reliably. They improve product context, funnel diagnosis and downstream reporting.

OptionalSafe to omit when irrelevant

Do not manufacture values just to fill them. Missing optional context is better than inaccurate context.

Ecommerce / Marketplace minimum

Essential events: view_item → add_to_cart → begin_checkout → purchase.

Add list, cart, shipping and payment-step events when those steps exist and can be logged reliably.

Lead Generation minimum

Essential: generate_lead after a successful submission. Add sign_up only when account creation is a meaningful conversion.

Never put email, phone or full name in Firebase event parameters.

Booking / Appointments minimum

Essential: begin_booking and booking_complete. view_service is Recommended. Location/staff selection events are Optional unless they are important funnel steps.

Subscription minimum

Essential when applicable: start_trial and/or subscribe. If money is actually charged, also send purchase as the monetary transaction with a unique transaction_id.

Lifecycle events and purchase revenue are different signals; do not use the same destination conversion twice.

Parameter rule: the Event Catalog separates Essential for KePixel quality, Recommended, and Optional / can skip. If an Essential field is unavailable, fix the source data before relying on that event for optimization. Never invent IDs, prices, currency, attribution values, or customer identity.
Native store purchases are a separate case. Firebase distinguishes ecommerce purchase from automatically collected native-store purchase signals. Google states that automatically logged Google Play in-app purchases are not sent to the Android server container through the mobile sGTM path. KePixel Mobile V1 therefore does not claim automatic App Store / Google Play purchase delivery through this route until a dedicated store-purchase contract is validated. Do not create a manual duplicate just to force it through Server GTM.

Signal quality, identity and attribution

Firebase automatic context

Firebase Analytics already supplies app-instance, app, platform, device and session context. Do not duplicate those values as custom parameters just to make events look fuller.

Authenticated user_id

Recommended when accounts exist: set one stable internal non-PII account ID after successful sign-in and clear it on logout.

Set it with Firebase Analytics' User-ID API. Do not pass it as a normal event parameter, and never use an email address or phone number as the User-ID.

Email and phone

Do not put raw or hashed email/phone into normal Firebase Analytics event parameters.

Mobile V1 currently has no KePixel identity-enrichment endpoint in Source Setup. Cross-destination email/phone matching requires a separate reviewed identity channel with consent and app-attestation controls; it is not another event parameter.

Commerce quality

Essential on purchase: transaction_id, currency, value, and items.

Whenever an event carries value, also send the correct ISO currency. Keep transaction and item identifiers stable across retries.

Item quality

Prefer a stable item_id for each product, plan, service, or marketplace item. Add price and quantity when the event carries value.

item_name, brand, category and variant are useful context, but should not replace a stable ID when one exists.

Campaign context

Keep Firebase's automatic campaign/referrer signals intact. When the app explicitly receives trustworthy campaign or deep-link metadata that is not already handled automatically, log campaign_details.

Provide at least one of source, medium, or campaign. Add campaign_id, source_platform, term, content, creative_format, and marketing_tactic only when genuinely known.

Android attribution

Preserve Firebase / Google Play attribution.

Keep Google Play and deep-link/referrer measurement intact. Do not manually copy the Android Advertising ID into custom event parameters and do not invent Google or ad-network click IDs.

iOS attribution

Enable only the Apple attribution features the app actually uses.

Add AdSupport when Firebase advertising features that depend on IDFA are intentionally enabled. Use Apple attribution frameworks where relevant, and request App Tracking Transparency authorization before accessing data used for cross-app tracking.

Platform click IDs are integration-specific.

Firebase does not create Meta, TikTok, Snapchat, or other networks' proprietary click IDs for you. Only use a network click ID when an approved SDK, MMP, or deep-link/referrer integration actually supplies it. If the signal is unavailable, leave it absent rather than fabricating it.

KePixel event ID

kpx_event_id is not a required developer field in Mobile V1 unless KePixel Source Setup explicitly exposes an approved contract for it.

Do not invent an app-side event-ID algorithm for Mobile V1.

Native identifiers

browser cookies such as _fbp and _fbc are web/browser concepts and must not be fabricated inside a native app.

Use only identifiers produced by the native platform or an approved attribution integration and only when the app's consent state allows it.

Current KePixel Setup is enough for event transport: the KePixel Mobile GTM container file and Server Tagging URL are the two values the developer needs. You do not configure KePixel Server GTM or destination credentials in the app. Maximum consented email/phone match quality requires a separate KePixel Identity Enrichment capability; that is a product/backend feature, not another Firebase event parameter or a secret to embed in the app.

Privacy and consent

Do not send personal information as Firebase Analytics event parameters.

Do not send raw or hashed email, phone number, full name, postal address, payment details, IDFA, Android Advertising ID, access tokens, Firebase secrets, GTM credentials, or destination credentials as ordinary custom event parameters.

Use the correct identity channel: user_id may be a stable internal non-PII account identifier and must be set through Firebase's User-ID API. Email/phone matching needs a dedicated consented user-data mechanism.
Consent stays app-owned: the app remains responsible for consent, App Tracking Transparency where applicable, advertising/data-sharing choices, and privacy disclosures. Do not bypass a denied or unavailable consent signal.

Event Catalog

Copy-ready examples

Android / Kotlin

Set authenticated User-ID

val analytics = FirebaseAnalytics.getInstance(context) // After successful sign-in: use an internal non-PII account ID. analytics.setUserId(currentUser.internalId) // On logout. analytics.setUserId(null)
iOS / Swift

Set authenticated User-ID

import FirebaseAnalytics // After successful sign-in: use an internal non-PII account ID. Analytics.setUserID(currentUser.internalId) // On logout. Analytics.setUserID(nil)
Android / Kotlin

Campaign details

val campaign = Bundle().apply { putString(FirebaseAnalytics.Param.SOURCE, "newsletter") putString(FirebaseAnalytics.Param.MEDIUM, "email") putString(FirebaseAnalytics.Param.CAMPAIGN, "summer_launch") putString(FirebaseAnalytics.Param.CAMPAIGN_ID, "cmp_2026_08") putString(FirebaseAnalytics.Param.SOURCE_PLATFORM, "owned") } analytics.logEvent(FirebaseAnalytics.Event.CAMPAIGN_DETAILS, campaign)

Use only campaign data that the app actually receives. Do not fabricate click IDs.

iOS / Swift

Campaign details

Analytics.logEvent(AnalyticsEventCampaignDetails, parameters: [ AnalyticsParameterSource: "newsletter", AnalyticsParameterMedium: "email", AnalyticsParameterCampaign: "summer_launch", AnalyticsParameterCampaignID: "cmp_2026_08", AnalyticsParameterSourcePlatform: "owned" ])

Use only campaign data that the app actually receives. Do not fabricate click IDs.

Purchase

This example uses the KePixel high-quality purchase baseline: unique transaction_id, ISO currency, accurate value, and an items array with a stable product ID, name, unit price and quantity. value equals the sum of item price × quantity and does not include shipping or tax.

Android / Kotlin

Purchase

import android.os.Bundle import com.google.firebase.analytics.FirebaseAnalytics val analytics = FirebaseAnalytics.getInstance(context) val item = Bundle().apply { putString(FirebaseAnalytics.Param.ITEM_ID, "SKU_1") putString(FirebaseAnalytics.Param.ITEM_NAME, "Example") putDouble(FirebaseAnalytics.Param.PRICE, 29.99) putLong(FirebaseAnalytics.Param.QUANTITY, 2) } val purchase = Bundle().apply { putString(FirebaseAnalytics.Param.TRANSACTION_ID, "T_12345") putString(FirebaseAnalytics.Param.CURRENCY, "USD") putDouble(FirebaseAnalytics.Param.VALUE, 59.98) putParcelableArray(FirebaseAnalytics.Param.ITEMS, arrayOf(item)) } analytics.logEvent(FirebaseAnalytics.Event.PURCHASE, purchase)
iOS / Swift

Purchase

import FirebaseAnalytics Analytics.logEvent(AnalyticsEventPurchase, parameters: [ AnalyticsParameterTransactionID: "T_12345", AnalyticsParameterCurrency: "USD", AnalyticsParameterValue: 59.98, AnalyticsParameterItems: [[ AnalyticsParameterItemID: "SKU_1", AnalyticsParameterItemName: "Example", AnalyticsParameterPrice: 29.99, AnalyticsParameterQuantity: 2 ]] ])
Do not fire purchase on a button tap alone. Log it only after the app or backend confirms the transaction. Reuse the same business transaction ID for retries of the same transaction so the purchase can be deduplicated correctly.

Test your KePixel Mobile connection

Android

Enable Firebase DebugView

Connect the test device, replace PACKAGE_NAME, then run:

adb shell setprop debug.firebase.analytics.app PACKAGE_NAME

Disable it after testing with:

adb shell setprop debug.firebase.analytics.app .none.
iOS

Enable Firebase DebugView

In Xcode, edit the app scheme and add -FIRDebugEnabled under Arguments Passed On Launch.

Disable it after testing with -FIRDebugDisabled.

  1. Install and open the selected platform build on a development/test device.
  2. Open Firebase / GA4 DebugView and trigger one Essential event from the actual user flow.
  3. Confirm the exact event name plus all Essential parameters are present. For ecommerce, validate purchase with a unique test transaction ID and a populated items array.
  4. Return to KePixel → Sources → Mobile Source → Setup and click Refresh status.
  5. Confirm Test event received.
  6. If you initially routed only debug devices or a controlled traffic percentage to server-side GTM, increase the rollout only after this verification succeeds.
How to diagnose: if Firebase does not see the event, fix the app instrumentation first. If Firebase sees the event but KePixel does not, re-check the platform sGTM setting, the GA4 App Data Stream server-side Tag Manager configuration, and the source-specific KePixel Server Tagging URL. The developer does not need access to KePixel's GTM account.

Google Analytics / Firebase limits to respect

  • Up to 500 distinct event types are supported for an app.
  • Each event can carry up to 25 event parameters.
  • Event and parameter names can be up to 40 characters, must start with a letter, and should contain only letters, numbers, and underscores.
  • Do not use the reserved firebase_, google_, or ga_ prefixes.
  • Prefer Google's recommended event names and prescribed parameters when they represent the action accurately.

Android server-side tagging limitations

  • Automatically logged Google Play in-app purchases are not sent to the server container through this mobile sGTM path.
  • app_remove is not reported through this Android server-side setup.
  • Linking the GA4 app data stream to Google Ads is still required when GA4 app conversions or audiences must be available in Google Ads.

iOS preview note

For SwiftUI or UIScene apps, make sure the server-side preview URL is forwarded to Analytics.handleOpen(url). That preview handling is platform-specific and should not be copied from the Android setup.