Android Uninstall Tracking Setup

Track app uninstalls on Android to measure user retention, identify low-quality traffic sources, and optimize campaign performance using Firebase Cloud Messaging integration with Singular SDK.

Overview

How Uninstall Tracking Works

Singular detects app uninstalls by sending silent push notifications via Firebase Cloud Messaging and monitoring delivery responses to determine if the app remains installed on devices.

Technical Process:

1. Token Registration: Singular SDK registers FCM tokens with Singular servers
2. Silent Notifications: Singular sends periodic silent push notifications to registered devices
3. Delivery Feedback: FCM reports delivery success or failure
4. Uninstall Detection: Failed deliveries indicate app uninstall
5. Event Recording: Uninstall event attributed to original install source

Requirements

• SDK Version: Android SDK 7.0+ required for uninstall tracking
• Firebase Setup: Active Firebase project with Cloud Messaging enabled
• Google Play Services: Devices must have Google Play Services installed
• App Update: Users must install updated app version with uninstall tracking enabled
• Permissions: Android 13+ requires explicit notification permission for FCM token generation

Important Considerations

Domain Restricted Sharing

If your Google Organization has Domain Restricted Sharing enabled, grant Singular Organization access to enable uninstall tracking functionality.

Configuration Steps:

1. Access Organization Policies: Navigate to Organization Policies page in Google Cloud Console
2. Select Resource: Choose the organization where policy is configured
3. Find Constraint: Locate "Domain Restricted Sharing" constraint
4. Manage Policy: Click "Manage policy" button
5. Add Singular Organization: Under Policy Values, select Custom and add the following:

is:principalSet://iam.googleapis.com/organizations/626787461583

This grants Singular's service account access to send FCM notifications for uninstall detection.

HTTP v1 API Setup (Recommended)

Configure uninstall tracking using Firebase Cloud Messaging HTTP v1 API with improved security via OAuth 2.0 access tokens and enhanced cross-platform messaging support.

Step 1: Integrate Android SDK 7.x+

Update SDK Version

Upgrade to Android SDK 7.0 or higher to enable uninstall tracking functionality.

Gradle Configuration:

dependencies {
    // Singular Android SDK 7.x+
    implementation("com.singular.sdk:singular_sdk:12.6.2")
}

Complete integration guide: Android SDK Integration Guide

Step 2: Configure AndroidManifest.xml

Add FCM Receiver

Configure Android manifest to receive FCM notifications for uninstall detection.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.your.package">

    <!-- FCM Permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <application>
        
        <!-- Singular FCM Receiver Service -->
        <service
            android:name="com.singular.sdk.SingularFcmService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT" />
            </intent-filter>
        </service>

    </application>

</manifest>

Detailed manifest configuration: Android SDK Uninstall Tracking Guide

Step 3: Create Firebase Project

Initialize Firebase

Set up a Firebase project and retrieve the Project ID required for Singular configuration.

1. Open Firebase Console: Navigate to Firebase Console
2. Create Project: Select or create a new Firebase project for your app
3. Locate Project Settings: Click gear icon → Project Settings
4. Copy Project ID: Copy your Project ID from General tab (you'll enter this in Singular later)

Step 4: Enable Firebase Cloud Messaging API

Activate HTTP v1 API

Enable the Firebase Cloud Messaging API (v1) for your project to use the modern HTTP v1 protocol.

1. Navigate to Cloud Messaging: In Firebase Console, go to Project Settings → Cloud Messaging tab
2. Enable API: Click "Enable" next to Firebase Cloud Messaging API (V1)
3. Verify Activation: Confirm API status shows as "Enabled"

Step 5: Create Custom IAM Role

Configure Service Account Permissions

Create a custom IAM role with specific permissions for Singular to send FCM notifications for uninstall detection.

1. Access IAM: In Firebase Project Settings → Service Accounts → Manage service account permissions
2. Open Roles: Select "Roles" in left navigation menu
3. Create Role: Click "Create Role" button
4. Configure Role Details:
   • Title: Singular Uninstall Tracking
   • ID: singular_uninstalls
   • Role launch stage: General Availability

Add Required Permission

Grant the custom role permission to send FCM messages.

1. Add Permissions: Click "Add Permissions" button
2. Filter Permissions: Search for "Firebase Cloud Messaging API Admin"
3. Select Permission: Check cloudmessaging.messages.create
4. Add to Role: Click "Add" button
5. Create Role: Click "Create" to finish role creation

Step 6: Assign Singular Service Account

Grant Access to Singular

Assign the custom role to Singular's service account to authorize uninstall tracking operations.

1. Open IAM Page: Select "IAM" in left navigation menu
2. Grant Access: Click "Grant Access" button in Permissions tab
3. Add Principal: Under "New principals" field, enter:

   singular-uninstall-tracking@singular-uninstall-tracking.iam.gserviceaccount.com

Assign Custom Role

Select the "Singular Uninstall Tracking" role created in previous steps.

1. Select Role: Under "Assign roles", search for and select "Singular Uninstall Tracking"
2. Verify Configuration: Confirm setup matches the screenshot below
3. Save: Click "Save" button to apply permissions

Final Configuration:

Step 7: Configure Singular App Settings

Add Project ID to Singular

Enter your Firebase Project ID in Singular's app configuration to enable uninstall tracking.

1. Open Singular Apps: Navigate to Singular Apps Page
2. Select App: Choose your Android app from the list
3. Advanced Settings: Scroll to Advanced Settings section
4. Uninstall Tracking: Locate Uninstall Tracking configuration
5. Enter Project ID: Paste your Firebase Project ID from Step 3
6. Save: Click Save to apply configuration

Testing Uninstall Tracking

Verify uninstall tracking is configured correctly before releasing updated app to production.

Test Procedure

Validation Steps

1. Install Test Build: Deploy app with uninstall tracking enabled to test device
2. Launch App: Open app to trigger SDK initialization and FCM token registration
3. Verify Token Registration: Check SDK logs for successful FCM token registration with Singular
4. Wait for Batch Process: Allow 24-48 hours for Singular to send first silent notification
5. Uninstall App: Remove app from test device
6. Monitor Dashboard: Check Singular dashboard after 24-48 hours for uninstall event

SDK Log Verification

Check Android logcat for Singular SDK messages confirming proper configuration.

Expected Log Messages:

D/SingularSDK: FCM token registered successfully
D/SingularSDK: Uninstall tracking enabled
D/SingularSDK: Token sent to Singular servers

Common Issues

Legacy HTTP API (Deprecated)

Legacy HTTP API was shut down on July 22, 2024. All implementations must migrate to HTTP v1 API.

Migration Required

If your app currently uses the legacy HTTP API with Server Key and Sender ID configuration, follow these migration steps:

1. Review Current Configuration: Check if Singular app settings show "Server Key" field instead of "Project ID"
2. Follow HTTP v1 Setup: Complete all steps in HTTP v1 API Setup section above
3. Update App Configuration: Replace Server Key with Firebase Project ID in Singular settings
4. Test Implementation: Verify uninstall tracking works with new v1 API configuration
5. Release Update: Deploy updated app to production users

Migration guide: Firebase HTTP v1 API Migration

Benefits of HTTP v1 API

• Enhanced Security: Uses short-lived OAuth 2.0 access tokens instead of static server keys
• Better Cross-Platform Support: Unified message structure for Android, iOS, and web
• Platform-Specific Overrides: Customize notification behavior per platform in single request
• Future-Proof: Ongoing Firebase support and new features only available in v1
• Improved Error Handling: More detailed error responses for troubleshooting

Analyzing Uninstall Data

Use uninstall data in Singular reports to optimize campaign performance and identify traffic quality issues.

Available Metrics

Uninstall Tracking Metrics

• Uninstall Count: Total number of app uninstalls detected
• Uninstall Rate: Percentage of installs that resulted in uninstalls
• Days to Uninstall: Average time between install and uninstall events
• Uninstalls by Source: Breakdown of uninstalls by campaign, publisher, creative
• Cohort Analysis: Uninstall patterns across different user cohorts

Use Cases

Campaign Optimization:

• Identify campaigns driving low-quality traffic with high uninstall rates
• Compare uninstall rates across different traffic sources
• Optimize bidding strategies based on predicted user retention

Fraud Detection:

• Detect abnormal uninstall patterns indicating install fraud
• Flag publishers with suspiciously high uninstall rates
• Monitor time-to-uninstall for signs of bot traffic

User Retention Analysis:

• Track app stickiness and engagement over time
• Correlate uninstalls with app updates or feature releases
• Identify factors contributing to user churn

Best Practices

Optimization Strategies

• Set Benchmarks: Establish acceptable uninstall rate thresholds for different campaign types
• Monitor Trends: Track uninstall rates over time to identify seasonal patterns or anomalies
• Segment Analysis: Compare uninstall rates across user demographics, geographies, and devices
• Attribution Windows: Consider uninstall timing when evaluating campaign performance
• Quality Scoring: Incorporate uninstall rates into traffic quality scoring models