Skip to main content

Android

FalconMetrics Android sdk

FalconMetrics is a lightweight analytics and attribution tracking SDK for Android applications. This SDK allows you to track various user events and conversions in your Android app to measure marketing effectiveness and user engagement.

Features​

  • Easy integration with minimal setup
  • Event tracking for user actions (sign-ups, purchases, etc.)
  • Privacy-compliant with opt-out capabilities
  • Efficient background processing with minimal battery impact
  • Automatic install referrer tracking

Installation​

Gradle​

Add the FalconMetrics SDK to your app's build.gradle file:

dependencies {
    implementation 'io.falconmetrics:falconmetrics:1.1.1'
}

Usage​

Initialization​

Initialize the SDK in your Application class or main activity:

// In your Application class
class MyApp : Application() {
    
    lateinit var falconMetrics: FalconMetrics
    
    override fun onCreate() {
        super.onCreate()
        
        // Create the FalconMetrics instance
        falconMetrics = FalconMetricsSdk.create(applicationContext)
        
        // Configure IP address tracking (choose from: full, anonymised, disabled)
        val config = FalconMetricsConfig(ipAddressTracking = IpAddressTracking.full)
        
        // Initialize with your API key, optional fbAppId, and config
        falconMetrics.init(
            apiKey = "YOUR_API_KEY",
            fbAppId = null, // or your Facebook App ID if available
            falconMetricsConfig = config
        )
    }
}

#### IP Address Tracking configuration

You can control how the SDK handles IP addresses for attribution at initialization time using `FalconMetricsConfig` and the `IpAddressTracking` setting.

Options (`io.falconmetrics.sdk.IpAddressTracking`):

- `full` — Send full IP address for most accurate attribution.
- `anonymised` — Send an anonymized IP (privacy-preserving, balances accuracy and privacy).
- `disabled` — Do not send IP address.

Example:

```kotlin
// Create a config that anonymizes IP addresses
val config = FalconMetricsConfig(ipAddressTracking = IpAddressTracking.anonymised)

// Initialize with API key, optional fbAppId (for Meta Referrer), and config
falconMetrics.init(
    apiKey = "YOUR_API_KEY",
    fbAppId = null, // or your Facebook App ID if available
    falconMetricsConfig = config
)

Tracking Events​

The SDK supports tracking various event types:

User Sign-Up or Login​

// Track when a completes registration or onboarding
falconMetrics.trackEvent(CompleteRegistrationEvent())

Add to Cart Event​

// Track when a user adds an item to cart
falconMetrics.trackEvent(
    AddedToCartEvent(
        itemId = "product-123",
        quantity = 2,
        productPriceInCents = 1099, // $10.99
        currency = "USD",
        productCategory = "Electronics",
        cartId = "cart-456"
    )
)

SubscribeEvent Event​

// Track when a user subscribes to a product or service (optionally include user data)
falconMetrics.trackEvent(
    SubscribeEvent(
        currency = "USD",
        predictedLtvValueInCents = 10000
    ),
    userData = UserData(
        email = "[email protected]",
        phoneNumber = "+1 23456789",
        firstName = "Jane",
        lastName = "Doe",
        dateOfBirth = "19900115", // YYYYMMDD
        city = "San Francisco",
        state = "CA",
        postalCode = "94107",
        country = "US"
    )
)

Purchase Event​

// Track when a user completes a purchase
falconMetrics.trackEvent(
    PurchaseEvent(
        itemIds = listOf("product-123", "product-456"),
        quantity = 2,
        transactionId = "order-789",
        productPriceInCents = 1099, // $10.99
        currency = "USD",
        revenueInCents = 2198, // $21.98
        productCategory = "Electronics",
        cartId = "cart-456",
        paymentMethod = "credit_card",
        taxInCents = 175, // $1.75
        shippingCostInCents = 499, // $4.99
        discountInCents = 220 // $2.20
    )
)

Custom Event​

Custom events are powerful and provide a lot of flexibility. Yoy need to make sure that the eventName matches the event in the ad network.

You can add optionally revenue and a currency to the event to write revenue to the ad network.

// Track a custom event
falconMetrics.trackEvent(
    CustomEvent(
        eventName = "MyEvent",
        revenueInCents = 1000,
        currency = "USD",
        attributes= mapOf<String, Any>("key1" to "value1", "key2" to 2)
    )
)

Google advertising ID​

For a more accurate attribution it is recommended to enable Google advertising ID tracking. To do this, add the following permission to your AndroidManifest.xml file:

  <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

The FalconMetrics sdk automatically tracks the Google advertising ID for you and takes into account the users consent to use the ID.

Meta Referrer​

The meta refferer is more elaborate thant the Google Play Install referrer. Google Play Install referrer only provides info for same session click through installs, while the Meta Referrer provides info for view through installs, click through installs and multiple session click through installs. The FalconMetrics sdk automatically retrieves and processes the meta referrer in order to provide the most accurate attribution possible.

Add the following <queries> element inside the root <manifest> tag to enable Meta Referrer support:

<queries>
  <package android:name="com.facebook.katana" />
</queries>

<queries>
  <package android:name="com.instagram.android" />
</queries>

<queries>
  <package android:name="com.facebook.lite" />
</queries>

Privacy Control​

Disable or enable tracking​

The SDK provides methods to enable or disable tracking based on user consent:

// Disable tracking
falconMetrics.setTracking(context, false)

// Check if tracking is enabled
val isEnabled = falconMetrics.isTrackingEnabled(context)

// Re-enable tracking
falconMetrics.setTracking(context, true)

By default, tracking is enabled when the SDK is initialized.

Update Tracking options​

The SDK provides options to update trackingoptions based on user consent. The trackingoptions are not persisted across app launches.

// New config object
val config = FalconMetricsConfig(ipAddressTracking = IpAddressTracking.anonymised)
// set the new tracking options
falconMetrics.updateTrackingOptions(config)

ProGuard Configuration​

The SDK includes consumer ProGuard rules, so you don't need to add any additional ProGuard configuration to your project.

Requirements​

  • Android API level 21 (Android 5.0) or higher
  • Kotlin 1.5 or higher

License​

© 2025 FalconMetrics LLC. All rights reserved.

This SDK is licensed under the FalconMetrics SDK License Addendum. Use of this SDK is subject to the FalconMetrics Terms of Use and SDK License, available at: https://www.falconmetrics.io/terms

Support​

For questions or support, please contact [email protected] or visit our documentation at https://docs.falconmetrics.io