Android Developer Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Overview

This guide provides implementation requirements for integrating Engage Studio Mobile Push notifications in your Android app using the Treasure Data Android SDK. Your development team must implement the following functionality:

1. FCM Integration: Receive push notifications via Firebase Cloud Messaging
2. Token Management: Register and update device tokens with Treasure Data
3. Notification Display: Show notifications with images, action buttons, and deep links
4. Event Tracking: Track user interactions (delivery, open, dismiss, links) using Treasure Data SDK
5. Automated Data Upload: Treasure Data SDK automatically handles event upload to Treasure Data

Requirements

Architecture Overview

┌─────────────────────┐
│   Engage Studio     │
│     Campaign        │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Firebase Cloud      │
│   Messaging (FCM)   │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Your Android App   │
├─────────────────────┤
│ MyFirebaseMessaging │ ← Receives notifications
│      Service        │
├─────────────────────┤
│  PushEventReceiver  │ ← Handles user actions
├─────────────────────┤
│ Treasure Data SDK   │ ← Tracks and uploads events
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Treasure Data      │
│   Ingest API        │
└─────────────────────┘

Implementation Components

Your Android app must implement the following components:

1. Application Class

Purpose: Initialize Treasure Data SDK and configure app-wide settings

Key Responsibilities:

• Initialize Treasure Data SDK with API endpoint and database configuration
• Configure automatic data collection settings
• Enable debug logging (optional)

Reference: See MyApplication.kt in the sample repository

2. Firebase Messaging Service

Purpose: Receive and display push notifications from FCM

Key Responsibilities:

• Listen for incoming FCM messages
• Extract notification payload (title, body, image, links)
• Display notification with action buttons
• Track delivery events using Treasure Data SDK when notification is received
• Handle FCM token updates

Reference: See MyFirebaseMessagingService.kt in the sample repository

3. Push Event Receiver

Purpose: Handle user interactions with notifications

Key Responsibilities:

• Handle notification tap (main content)
• Handle action button taps (web link, deep link)
• Handle notification dismiss
• Track corresponding events (open, dismiss, link_open, deeplink_open) using Treasure Data SDK
• Open web URLs using Chrome Custom Tabs
• Open deep links within the app

Reference: See PushEventReceiver.kt in the sample repository

4. FCM Token Service

Purpose: Manage device token registration with Treasure Data

Key Responsibilities:

• Obtain current FCM token
• Register token with Treasure Data when app launches using SDK
• Re-register token when it's refreshed by FCM
• Associate token with user ID when user logs in
• Track token_register events

Reference: See FcmTokenService.kt in the sample repository

5. MainActivity Integration

Purpose: Handle notification taps and deep links

Key Responsibilities:

• Receive notification tap intents
• Track open events using Treasure Data SDK
• Navigate to appropriate screen based on deep link
• Open web URLs when specified

Reference: See MainActivity.kt in the sample repository

Data Payload Schema

Your app will receive the following JSON structure in the FCM data payload:

{
  "td_campaign_id": "cmp_20251214_promo",
  "title": "Special Offer!",
  "body": "Get 20% off your next purchase",
  "image_url": "https://cdn.example.com/banner.png",
  "link": "https://example.com/promo"
}

Event Tracking

Your app must track the following events and send them to Treasure Data:

All events are automatically sent by the Treasure Data SDK to the configured Treasure Data endpoint. The SDK handles batching, queuing, and retry logic automatically.

See the Push Events Table documentation for complete schema details.

Configuration Requirements

AndroidManifest.xml

Your app must declare:

• INTERNET permission
• POST_NOTIFICATIONS permission (Android 13+)
• Firebase Messaging Service
• Broadcast Receiver for notification actions
• Deep link intent filters

build.gradle.kts

Required dependencies:

• Firebase BoM: 34.7.0 or later
• Firebase Messaging (version managed by BoM)
• Treasure Data Android SDK: 1.1.0 or later
• WorkManager: 2.9.1 or later
• Chrome Custom Tabs: 1.8.0 or later

Example dependency configuration:

dependencies {
    // Firebase
    implementation(platform("com.google.firebase:firebase-bom:34.7.0"))
    implementation("com.google.firebase:firebase-messaging")
    implementation("com.google.firebase:firebase-analytics")

    // Treasure Data SDK
    implementation("com.treasuredata:td-android-sdk:1.1.0")

    // Background tasks
    implementation("androidx.work:work-runtime-ktx:2.9.1")

    // Web links
    implementation("androidx.browser:browser:1.8.0")
}

local.properties

Configure Treasure Data settings in local.properties (this file should be excluded from version control):

TD_WRITE_KEY=your_write_api_key_here
TD_DATABASE=mobile
TD_TABLE=push_events
TD_ENDPOINT=https://in.treasuredata.com

Access these properties in your build.gradle.kts:

val localProperties = Properties()
localProperties.load(FileInputStream(rootProject.file("local.properties")))

android {
    defaultConfig {
        buildConfigField("String", "TD_WRITE_KEY", "\"${localProperties["TD_WRITE_KEY"]}\"")
        buildConfigField("String", "TD_DATABASE", "\"${localProperties["TD_DATABASE"]}\"")
        buildConfigField("String", "TD_TABLE", "\"${localProperties["TD_TABLE"]}\"")
        buildConfigField("String", "TD_ENDPOINT", "\"${localProperties["TD_ENDPOINT"]}\"")
    }
}

Notification Permissions

For Android 13+ (API 33), request POST_NOTIFICATIONS permission at runtime.

User ID Association

To link push notification events with specific users:

1. Logged-in users: Include user_id (e.g., customer ID, email hash) in all events
2. Anonymous users: Pass null for user_id in events
3. On login: Send new token_register event with user_id to associate the device

Treasure Data will link all previous events from the same fcm_token to the user.

Testing

Test Notification Delivery

1. Run your app on a device with Google Play Services
2. Check logcat for FCM token
3. Send test notification from Firebase Console
4. Verify notification appears on device

Verify Event Tracking

Query Treasure Data to confirm events are being logged:

SELECT
  time,
  type,
  campaign_id,
  platform
FROM mobile.push_events
WHERE platform = 'android'
ORDER BY time DESC
LIMIT 100

Security Best Practices

1. API Keys:

   • Never commit local.properties to source control
   • Add local.properties to .gitignore
   • Use write-only keys (not master keys)
   • Store sensitive configuration in local.properties, not in code

2. Deep Links:

   • Always validate deep link destinations
   • Implement URL allowlists for sensitive actions
   • Sanitize parameters before navigation

3. Event Data:

   • Do not include PII in event payloads
   • Use hashed or anonymized user IDs when possible

4. Network Security:

   • Always use HTTPS for API endpoints
   • Consider certificate pinning for production

Troubleshooting

Notifications Not Received

• Verify FCM token is generated and uploaded
• Check Google Play Services is installed and updated
• Verify notification permissions (Android 13+)
• Check google-services.json is in app/ directory

Events Not Appearing in Treasure Data

• Verify TD_WRITE_KEY in local.properties is correct
• Check TD_ENDPOINT matches your region
• Verify database and table exist in Treasure Data
• Check Treasure Data SDK is properly initialized in MyApplication
• Enable debug logging to see SDK activity: TreasureData.enableLogging()

Deep Links Not Working

• Verify intent filter in AndroidManifest.xml
• Test with: adb shell am start -W -a android.intent.action.VIEW -d "myapp://test"
• Check URI format matches registered scheme

Sample Repository

Complete, production-ready implementation:

https://github.com/treasure-data/engage-push-notification-sample/tree/main/android

The repository includes:

• Full source code with inline documentation
• Gradle configuration with Treasure Data SDK integration
• AndroidManifest.xml setup
• Testing instructions
• Security best practices
• Example configuration files

Implementation Guide

This section provides detailed instructions for building and testing the sample application.

Project Structure

The sample repository follows this directory structure:

android/
├── app/
│   ├── src/main/
│   │   ├── java/com/treasuredata/pushsample/
│   │   │   ├── MainActivity.kt              # Deep link and notification handling
│   │   │   ├── MyApplication.kt             # App initialization & TD SDK setup
│   │   │   ├── CategoryActivity.kt          # Category view example
│   │   │   ├── ProductDetailActivity.kt     # Product detail example
│   │   │   ├── fcm/
│   │   │   │   ├── MyFirebaseMessagingService.kt  # FCM message receiver
│   │   │   │   ├── PushEventReceiver.kt     # Notification action handler
│   │   │   │   ├── PushAction.kt            # Action constants
│   │   │   │   └── FcmTokenService.kt       # Token management
│   │   │   └── utils/                       # Utility classes
│   │   ├── res/
│   │   │   ├── layout/
│   │   │   ├── drawable/
│   │   │   └── values/
│   │   └── AndroidManifest.xml
│   ├── build.gradle.kts
│   └── google-services.json.example         # Firebase config template
├── gradle/
├── build.gradle.kts
├── local.properties.example                 # TD configuration template
└── settings.gradle.kts

Build and Run Instructions

Prerequisites

• Android Studio Hedgehog (2023.1.1) or later
• JDK 17 or later
• Android SDK 26 (Android 8.0) or later

Setup Steps

1. Clone the repository:

git clone https://github.com/treasure-data/engage-push-notification-sample.git
cd engage-push-notification-sample/android

2. Open project in Android Studio:

# Open Android Studio and select "Open an Existing Project"
# Navigate to the android/ directory

3. Configure Firebase:

   • Download google-services.json from your Firebase project
   • Copy it to app/google-services.json
   • Update applicationId in app/build.gradle.kts to match your Firebase app

4. Configure Treasure Data:

   • Copy local.properties.example to local.properties
   • Edit local.properties with your Treasure Data configuration:
   TD_WRITE_KEY=your_write_api_key_here
   TD_DATABASE=mobile
   TD_TABLE=push_events
   TD_ENDPOINT=https://in.treasuredata.com

   • Important: Do not commit local.properties to version control

5. Sync Gradle:

   • Click "Sync Now" when prompted
   • Or File > Sync Project with Gradle Files

6. Build and run:

# Via Gradle command line
./gradlew assembleDebug

# Or use Android Studio Run button (Shift+F10)

Testing Workflow

Prerequisites

Before testing, ensure you have:

• Firebase project with Android app registered
• google-services.json downloaded and placed in app/ directory
• Treasure Data database and table created
• Write-only API key obtained
• Android emulator or physical device with Google Play Services

Test on Emulator

1. Create/start Android emulator:

# List available emulators
emulator -list-avds

# Start emulator
emulator -avd Pixel_5_API_34

2. Install and run app:

./gradlew installDebug
adb shell am start -n com.treasuredata.pushsample/.MainActivity

3. Monitor logs for FCM token:

adb logcat | grep -E "FCM token|FCMService"

Expected output:

I/FcmTokenService: FCM token: [your-device-token]
I/FcmTokenService: Registering FCM token: [token]

4. Send test notification from Firebase Console:

   • Open Firebase Console > Cloud Messaging
   • Click "Send your first message"
   • Enter title: "Test Notification"
   • Enter body: "This is a test"
   • Click "Send test message"
   • Paste your FCM token
   • Click "Test"

5. Verify notification appears in system tray

6. Tap notification and verify:

   • App opens (if closed)
   • open event is tracked
   • Deep link navigates correctly (if configured)

Test on Physical Device

1. Enable Developer Options:

   • Settings > About phone > Tap "Build number" 7 times

2. Enable USB Debugging:

   • Settings > System > Developer options > USB debugging

3. Connect device via USB and install:

# Verify device is connected
adb devices

# Install app
./gradlew installDebug

# Launch app
adb shell am start -n com.treasuredata.pushsample/.MainActivity

4. Follow steps 3-6 from emulator testing above

Test Notification Actions

1. Create test payload with actions in Firebase Console:

   • Add custom data fields:
     • campaign_id: test_campaign_001
     • message_id: msg_001
     • deeplink: myapp://product/12345
     • link: https://example.com/promo

2. Send notification and test:

   • Tap notification body → Verify open event
   • Tap web link → Verify Chrome Custom Tab opens
   • Tap deep link → Verify app navigation
   • Dismiss notification → Verify dismiss event

Verify Event Tracking

Query Treasure Data to confirm events are being logged:

SELECT
  time,
  type,
  campaign_id,
  platform,
  user_id,
  value
FROM mobile.push_events
WHERE platform = 'android'
  AND time > td_time_add(now(), '-1h', 'JST')
ORDER BY time DESC
LIMIT 20

Expected event sequence:

1. token_register - When app launches
2. delivery - When notification is received
3. open - When user taps notification
4. link_open - When user taps web link
5. deeplink_open - When user taps deep link
6. dismiss - When user dismisses notification

Test Deep Links

Test deep link handling using ADB:

# Test product deep link
adb shell am start \
  -W -a android.intent.action.VIEW \
  -d "myapp://product/12345" \
  com.treasuredata.pushsample

# Test category deep link
adb shell am start \
  -W -a android.intent.action.VIEW \
  -d "myapp://category/electronics" \
  com.treasuredata.pushsample

Verify app opens and navigates to correct screen.

Implementation Checklist

Use this checklist when implementing push notifications in your own app:

Phase 1: Project Setup

• Create Android project with minimum SDK 26 (Android 8.0)
• Add Firebase dependencies in build.gradle.kts
• Add WorkManager, OkHttp, Chrome Custom Tabs dependencies
• Download and add google-services.json to app/ directory
• Apply com.google.gms.google-services plugin
• Add required permissions in AndroidManifest.xml

Phase 2: Manifest Configuration

• Declare INTERNET permission
• Declare POST_NOTIFICATIONS permission (Android 13+)
• Register MyFirebaseMessagingService in manifest
• Register PushEventReceiver broadcast receiver
• Add intent filter for deep links in MainActivity
• Configure notification channels (Android 8+)

Phase 3: Core Components

• Create MyApplication class for app initialization
• Initialize Firebase in onCreate
• Initialize Treasure Data SDK with endpoint, database, and API key
• Configure TD SDK auto-tracking features (optional)
• Implement MyFirebaseMessagingService
• Implement onMessageReceived to handle FCM messages
• Implement onNewToken to handle token refresh
• Create FcmTokenService for token management

Phase 4: Notification Display

• Create notification channel with importance level
• Build notification with title, body, icon
• Add PendingIntent for notification tap
• Add PendingIntent for notification dismiss
• Download and attach images (if image_url present)
• Add action buttons for links (if configured)
• Show notification with NotificationManager

Phase 5: Event Tracking

• Track delivery event in onMessageReceived using TD SDK
• Track open event when notification is tapped using TD SDK
• Track dismiss event when notification is dismissed using TD SDK
• Track link_open event for web link taps using TD SDK
• Track deeplink_open event for app link taps using TD SDK
• Track token_register event on app launch and token refresh using TD SDK

Phase 6: User Interaction Handling

• Create PushEventReceiver to handle broadcast intents
• Handle PUSH_OPEN action in receiver
• Handle PUSH_DISMISS action in receiver
• Handle PUSH_ACTION_LINK action in receiver
• Handle PUSH_ACTION_DEEPLINK action in receiver
• Open Chrome Custom Tab for web links
• Parse and navigate deep links in MainActivity

Phase 7: Configuration and Security

• Create local.properties with TD configuration
• Add local.properties to .gitignore
• Add google-services.json to .gitignore
• Configure BuildConfig fields from local.properties
• Implement error handling for TD SDK operations
• Add ProGuard rules for Treasure Data SDK if using R8/ProGuard

Phase 8: Testing

• Request POST_NOTIFICATIONS permission at runtime (Android 13+)
• Test notification delivery on emulator
• Test notification delivery on physical device
• Test notification images
• Test notification action buttons
• Test deep link navigation
• Test web link opening with Chrome Custom Tabs
• Verify events appear in Treasure Data
• Test background notification handling
• Test foreground notification handling

Build Troubleshooting

"google-services.json is missing" Error

# Ensure file is in correct location
ls app/google-services.json

# Sync Gradle files
./gradlew --refresh-dependencies

"Manifest merger failed" Error

• Check for duplicate permissions or activities in AndroidManifest.xml
• Verify all library versions are compatible
• Run ./gradlew clean and rebuild

Treasure Data SDK Not Uploading Events

# Check SDK initialization logs
adb logcat | grep TreasureData

# Enable debug logging in MyApplication.kt:
TreasureData.enableLogging()

# Verify BuildConfig values are set correctly
# Check build/generated/source/buildConfig/debug/.../BuildConfig.java

Notifications Not Appearing

• Verify Google Play Services is installed on device/emulator
• Check notification permission is granted (Android 13+)
• Verify notification channel is created with correct importance
• Check logcat for FCM errors: adb logcat | grep FCM

Events Not Uploading to Treasure Data

• Verify TD_WRITE_KEY in local.properties is correct
• Check network connectivity
• Verify TD_ENDPOINT matches your region
• Check Treasure Data SDK logs: adb logcat | grep TreasureData
• Verify SDK is initialized correctly in MyApplication.onCreate()
• Try calling TreasureData.sharedInstance().uploadEvents() manually to force upload

Deep Links Not Working

# Verify intent filter is registered
adb shell dumpsys package com.treasuredata.pushsample | grep -A 5 "scheme"

# Test deep link manually
adb shell am start -W -a android.intent.action.VIEW -d "myapp://test"

Gradle Commands Reference

# Clean build
./gradlew clean

# Build debug APK
./gradlew assembleDebug

# Build release APK (requires signing config)
./gradlew assembleRelease

# Install on connected device
./gradlew installDebug

# Run unit tests
./gradlew testDebugUnitTest

# Run instrumented tests
./gradlew connectedDebugAndroidTest

# Check for dependency updates
./gradlew dependencyUpdates

# Lint check
./gradlew lintDebug

# Generate dependency tree
./gradlew app:dependencies

Next Steps

1. Clone the sample repository and review the implementation
2. Configure Firebase following the Mobile Push Setup guide
3. Implement the components in your Android app
4. Test notification delivery and event tracking
5. Review event data in the Push Events Table
6. Create your first campaign in Engage Studio

Related Documentation

• Mobile Push Setup - Firebase and Treasure Data configuration
• iOS Developer Guide - iOS implementation guide
• Push Events Table - Event schema and analytics queries
• Campaign Creation - Create Mobile Push campaigns