Push Notifications - Zixflow Docs

Complete guide to implementing push notifications with Zixflow using Firebase Cloud Messaging (FCM).

Track your campaigns: With the default FCM module, the SDK auto-tracks delivered and body opened. Action-button clicks are never automatic — use a receiver + track(...). For the dual-path custom FCM service used in the Android example, see Push Notification Tracking.

Prerequisites

Before implementing push notifications:

Configure FCM in Zixflow dashboard - Add your FCM Server Key in the Zixflow dashboard first
Firebase Project Setup - Create Firebase project and add your Android app
Install the push messaging module - Add messaging-push-fcm dependency

Important: FCM setup is required before implementing push notifications. This integration serves as the foundation for all push messaging capabilities.

Step 1: Firebase Project Setup

1. Create Firebase Project

Go to https://console.firebase.google.com
Click Add project or select existing project
Follow the setup wizard

2. Add Android App to Firebase

In Firebase console, click Add app → Select Android
Enter your app’s package name (e.g., com.yourcompany.app)
(Optional) Add SHA-1 certificate for debugging
Download google-services.json

3. Add google-services.json to Project

Place google-services.json in your app/ directory
Verify the file is at: app/google-services.json

Step 2: Add Dependencies

1. Add Google Services Plugin

Project-level build.gradle.kts:

plugins {
    id("com.android.application") version "8.9.1" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
    id("com.google.gms.google-services") version "4.4.2" apply false
}

Project-level build.gradle (Groovy):

plugins {
    id 'com.android.application' version '8.9.1' apply false
    id 'org.jetbrains.kotlin.android' version '2.0.21' apply false
    id 'com.google.gms.google-services' version '4.4.2' apply false
}

2. Apply Plugin in App Module

App-level build.gradle or build.gradle.kts:

// build.gradle.kts (Kotlin DSL)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.gms.google-services")  // Add this line
}

// build.gradle (Groovy DSL)
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
    id 'com.google.gms.google-services'  // Add this line
}

3. Add Zixflow and Firebase Dependencies

Kotlin DSL:

dependencies {
    // Zixflow core and push module
    implementation("com.zixflow.com.android:datapipelines:1.1.3")
    implementation("com.zixflow.com.android:messaging-push-fcm:1.1.3")

    // Firebase (if not already included)
    implementation(platform("com.google.firebase:firebase-bom:32.7.0"))
    implementation("com.google.firebase:firebase-messaging")
}

Groovy DSL:

dependencies {
    // Zixflow core and push module
    implementation 'com.zixflow.com.android:datapipelines:1.1.3'
    implementation 'com.zixflow.com.android:messaging-push-fcm:1.1.3'

    // Firebase
    implementation platform('com.google.firebase:firebase-bom:32.7.0')
    implementation 'com.google.firebase:firebase-messaging'
}

Step 3: Initialize Zixflow with Push Support

Basic Initialization (Kotlin)

import android.app.Application
import com.zixflow.sdk.Zixflow
import com.zixflow.sdk.ZixflowConfigBuilder
import com.zixflow.sdk.core.util.ZixflowLogLevel
import com.zixflow.messagingpush.ModuleMessagingPushFCM

class MainApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        // Initialize Zixflow SDK
        val config = ZixflowConfigBuilder(
            applicationContext = this,
            apiKey = "YOUR_API_KEY"
        )
            .autoTrackDeviceAttributes(true)
            .autoTrackActivityScreens(true)
            .trackApplicationLifecycleEvents(true)
            .logLevel(ZixflowLogLevel.DEBUG)

            // Add push notifications module
            .addZixflowModule(ModuleMessagingPushFCM())

            .build()

        Zixflow.initialize(config)
    }
}

Basic Initialization (Java)

import android.app.Application;
import com.zixflow.sdk.Zixflow;
import com.zixflow.sdk.ZixflowConfig;
import com.zixflow.sdk.ZixflowConfigBuilder;
import com.zixflow.sdk.core.util.ZixflowLogLevel;
import com.zixflow.messagingpush.ModuleMessagingPushFCM;

public class MainApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        // Initialize Zixflow SDK
        ZixflowConfig config = new ZixflowConfigBuilder(this, "YOUR_API_KEY")
            .autoTrackDeviceAttributes(true)
            .autoTrackActivityScreens(true)
            .trackApplicationLifecycleEvents(true)
            .logLevel(ZixflowLogLevel.DEBUG)
            .addZixflowModule(new ModuleMessagingPushFCM())
            .build();

        Zixflow.initialize(config);
    }
}

Important: The SDK automatically:

Registers a FirebaseMessagingService in your manifest
Fetches and registers FCM device tokens
Handles push notification display and tracking

Step 4: Register Application in AndroidManifest.xml

Ensure your custom Application class is registered:

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

    <!-- Required for push notifications -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <application
        android:name=".MainApplication"
        android:label="@string/app_name">
        <!-- Your activities -->
    </application>
</manifest>

Step 5: Request Push Notification Permission (Android 13+)

Android 13 (API 33) and higher requires runtime permission for notifications.

Request Permission in Activity

import android.Manifest
import android.os.Build
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat
import android.content.pm.PackageManager

class MainActivity : AppCompatActivity() {

    private val requestPermissionLauncher = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { isGranted ->
        if (isGranted) {
            // Permission granted - push notifications enabled
            println("Push notification permission granted")
        } else {
            // Permission denied - explain value to user
            println("Push notification permission denied")
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Request permission for Android 13+
        requestNotificationPermission()
    }

    private fun requestNotificationPermission() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            when {
                ContextCompat.checkSelfPermission(
                    this,
                    Manifest.permission.POST_NOTIFICATIONS
                ) == PackageManager.PERMISSION_GRANTED -> {
                    // Permission already granted
                    println("Notification permission already granted")
                }
                shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS) -> {
                    // Show explanation to user why you need this permission
                    showPermissionRationale()
                }
                else -> {
                    // Request permission
                    requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
                }
            }
        }
    }

    private fun showPermissionRationale() {
        // Show dialog explaining why push notifications are valuable
        // Then request permission
        requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
    }
}

Step 6: Identify Users

Critical: Device tokens must be associated with a user before push notifications can be delivered.

// Identify user when they log in
Zixflow.instance().identify(
    userId = "user@example.com",
    traits = mapOf(
        "email" to "user@example.com",
        "first_name" to "John",
        "last_name" to "Doe",
        "plan" to "premium"
    )
)

Important Notes:

When users start the app, they automatically generate a device token
This token links to their Zixflow profile when you call identify()
This ensures notifications are delivered to the correct user

Configuration Options

Configure push notification behavior with MessagingPushModuleConfig:

import com.zixflow.messagingpush.MessagingPushModuleConfig
import com.zixflow.messagingpush.ModuleMessagingPushFCM
import com.zixflow.messagingpush.config.PushClickBehavior

val pushConfig = MessagingPushModuleConfig.Builder()
    .setAutoTrackPushEvents(true)           // Auto-track delivered/opened
    .setPushClickBehavior(                   // Control app navigation
        PushClickBehavior.ACTIVITY_PREVENT_RESTART
    )
    .build()

val config = ZixflowConfigBuilder(this, "YOUR_API_KEY")
    .addZixflowModule(ModuleMessagingPushFCM(moduleConfig = pushConfig))
    .build()

Configuration Options

Option	Type	Default	Description
`autoTrackPushEvents`	Boolean	`true`	Automatically track `delivered` and `opened` metrics
`pushClickBehavior`	PushClickBehavior	`ACTIVITY_PREVENT_RESTART`	Define behavior when notification is clicked
`notificationCallback`	ZixflowPushNotificationCallback	`null`	Override default push behavior

Push Click Behaviors

Three strategies control app navigation when notifications are tapped: ACTIVITY_PREVENT_RESTART (Default - Recommended)

Reuses existing activities when possible
Ideal for apps with sensitive screens (checkout, payment)
Prevents interrupting user workflows

ACTIVITY_NO_FLAGS

Creates new activity instance on every notification tap
Standard Android behavior

RESET_TASK_STACK

Clears entire app state
Prevents back navigation to previous screens
Use when you want fresh app start

import com.zixflow.messagingpush.config.PushClickBehavior

val pushConfig = MessagingPushModuleConfig.Builder()
    .setPushClickBehavior(PushClickBehavior.ACTIVITY_PREVENT_RESTART)
    .build()

Advanced Features

Customize Notification Appearance

Override notification appearance using ZixflowPushNotificationCallback:

import com.zixflow.messagingpush.data.communication.ZixflowPushNotificationCallback
import com.zixflow.messagingpush.data.model.ZixflowParsedPushPayload
import androidx.core.app.NotificationCompat

val pushConfig = MessagingPushModuleConfig.Builder()
    .setNotificationCallback(object : ZixflowPushNotificationCallback {
        override fun onNotificationComposed(
            payload: ZixflowParsedPushPayload,
            builder: NotificationCompat.Builder
        ) {
            // Customize notification appearance in place
            builder
                .setColor(getColor(R.color.notification_accent))
                .setSound(Uri.parse("android.resource://${packageName}/${R.raw.notification_sound}"))
                .setPriority(NotificationCompat.PRIORITY_HIGH)
        }
    })
    .build()

Attach action buttons

The SDK builds title, body, and image but does not auto-attach action buttons. Parse action_buttons from payload.extras inside onNotificationComposed and call builder.addAction with PendingIntents that your app handles (for example a BroadcastReceiver).

import android.app.PendingIntent
import android.content.Context
import android.content.Intent
import android.os.Build
import androidx.core.app.NotificationCompat
import com.zixflow.messagingpush.config.MessagingPushModuleConfig
import com.zixflow.messagingpush.data.communication.ZixflowPushNotificationCallback
import com.zixflow.messagingpush.data.model.ZixflowParsedPushPayload
import org.json.JSONArray

val pushConfig = MessagingPushModuleConfig.Builder()
    .setNotificationCallback(object : ZixflowPushNotificationCallback {
        override fun onNotificationComposed(
            payload: ZixflowParsedPushPayload,
            builder: NotificationCompat.Builder
        ) {
            val context = /* your Application or Activity context */
            attachActionButtons(context, payload, builder)
        }
    })
    .build()

fun attachActionButtons(
    context: Context,
    payload: ZixflowParsedPushPayload,
    builder: NotificationCompat.Builder
) {
    val raw = payload.extras.getString("action_buttons") ?: return
    val buttons = try {
        JSONArray(raw)
    } catch (_: Exception) {
        return
    }

    val count = minOf(buttons.length(), 2) // max 2 buttons
    for (index in 0 until count) {
        val button = buttons.getJSONObject(index)
        val name = button.optString("name", "Action ${index + 1}")
        val deeplink = button.optString("deeplink", "")

        val intent = Intent(context, NotificationActionReceiver::class.java).apply {
            action = "com.yourcompany.app.PUSH_NOTIFICATION_ACTION"
            putExtra("Zixflow-Delivery-ID", payload.zixflowDeliveryId)
            putExtra("Zixflow-Delivery-Token", payload.zixflowDeliveryToken)
            putExtra("action_index", index)
            putExtra("action_name", name)
            putExtra("action_deeplink", deeplink)
            // Same ID used in NotificationManagerCompat.notify() — required to cancel on action press
            putExtra("notification_id", notificationId)
        }

        val flags = PendingIntent.FLAG_UPDATE_CURRENT or
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) PendingIntent.FLAG_IMMUTABLE else 0

        val pendingIntent = PendingIntent.getBroadcast(
            context,
            index,
            intent,
            flags
        )

        builder.addAction(
            NotificationCompat.Action.Builder(0, name, pendingIntent).build()
        )
    }
}

Register a BroadcastReceiver (for example NotificationActionReceiver) with matching intent action. In the receiver: track Opened, then Push Notification Action Clicked, then NotificationManagerCompat.cancel(notificationId) (action presses do not auto-dismiss). See Push Notification Tracking and NotificationActionReceiver.kt.

Configure Default Icon and Color

Add metadata to AndroidManifest.xml:

<application>
    <!-- Default notification icon (should be white, transparent background) -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_icon"
        android:resource="@drawable/ic_notification" />

    <!-- Default notification color (accent color) -->
    <meta-data
        android:name="com.google.firebase.messaging.default_notification_color"
        android:resource="@color/notification_color" />
</application>

Rich Push Notifications

Rich push (images, videos, GIFs) is automatically supported by the SDK. No additional configuration needed. Send rich media from Zixflow dashboard:

Create push notification campaign
Add image URL or video URL
SDK automatically downloads and displays media

Custom FirebaseMessagingService (dual-path)

Android routes FCM to one FirebaseMessagingService. If you declare your own, remove the SDK service from the merged manifest, then try the SDK helper first and fall back to manual display + metrics when it returns false. Reference: CustomFirebaseMessagingService.kt.

<!-- AndroidManifest.xml inside <application> -->
<service
    android:name="com.zixflow.messagingpush.ZixflowFirebaseMessagingService"
    tools:node="remove" />

<service
    android:name=".CustomFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage
import com.zixflow.messagingpush.ZixflowFirebaseMessagingService
import com.zixflow.sdk.Zixflow
import com.zixflow.sdk.events.Metric
import com.zixflow.sdk.events.TrackMetric

class CustomFirebaseMessagingService : FirebaseMessagingService() {

    override fun onMessageReceived(message: RemoteMessage) {
        val sdkHandled = try {
            ZixflowFirebaseMessagingService.onMessageReceived(
                applicationContext,
                message,
                true // handleNotificationTrigger — display + track when recognized
            )
        } catch (_: Exception) {
            false
        }

        if (sdkHandled) return

        // SDK did not handle — track Delivered and display yourself
        val data = message.data
        val deliveryId = data["Zixflow-Delivery-ID"]
            ?: data["ZIXFLOW-Delivery-ID"]
            ?: ""
        val deliveryToken = data["Zixflow-Delivery-Token"]
            ?: data["ZIXFLOW-Delivery-Token"]
            ?: Zixflow.instance().registeredDeviceToken
            ?: ""

        if (deliveryId.isNotEmpty() && deliveryToken.isNotEmpty()) {
            Zixflow.instance().trackMetric(
                TrackMetric.Push(
                    metric = Metric.Delivered,
                    deliveryId = deliveryId,
                    deviceToken = deliveryToken
                )
            )
        }

        // show notification, attach action buttons, put delivery extras on content Intent
        handlePushManually(message, deliveryId, deliveryToken)
    }

    override fun onNewToken(token: String) {
        super.onNewToken(token)
        try {
            ZixflowFirebaseMessagingService.onNewToken(applicationContext, token)
        } catch (_: Exception) { }
        Zixflow.instance().registerDeviceToken(token)
    }
}

Accept both Zixflow- and ZIXFLOW- delivery key casings. For body opens on the manual path, put delivery ID/token on the content PendingIntent extras and call trackMetric(Opened) in your Activity — see the example MainActivity.handlePushOpenIntent.

Tracking Push Metrics

Event	Default FCM module	Custom dual-path (example)
Delivered	Automatic when SDK handles the message	Call `trackMetric(Delivered)` when `onMessageReceived` returns `false`
Opened (body)	Automatic	Track from Activity extras on content-intent launch
Action clicked	Never automatic — receiver + `track(...)`	Same

Full details: Push Notification Tracking.

Deep Links and Custom Actions

For Zixflow campaign taps, the Android example does not rely on https intent filters alone. It:

Puts deeplink_url on the content PendingIntent (body) and per-button deeplink on action intents
Tracks Opened / Action Clicked (see Push Notification Tracking)
Opens the URL via DeeplinkRouter — custom scheme hosts → Activities; otherwise ACTION_VIEW

// After body Opened tracking in MainActivity:
DeeplinkRouter.open(this, intent.getStringExtra("deeplink"))

// After action tracking in NotificationActionReceiver:
if (actionDeeplink.isNotEmpty()) {
    DeeplinkRouter.open(context, actionDeeplink)
}

You can still add HTTPS / app-link intent filters for cold starts from the browser:

<activity android:name=".MainActivity">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="yourapp.com" />
    </intent-filter>
    <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="zixflowdemo" android:host="sale" />
        <data android:scheme="zixflowdemo" android:host="dashboard" />
    </intent-filter>
</activity>

Full open / action / deeplink contract: Push Notification Tracking.

Testing Push Notifications

1. Verify Device Token Registration

Check if device token is registered:

val deviceToken = Zixflow.instance().registeredDeviceToken
if (deviceToken != null) {
    println("Device token registered: $deviceToken")
} else {
    println("Device token not yet registered")
}

2. Enable Debug Logging

Use debug logging to troubleshoot:

val config = ZixflowConfigBuilder(this, "YOUR_API_KEY")
    .logLevel(ZixflowLogLevel.DEBUG)  // Enable verbose logging
    .build()

View logs in Android Studio Logcat (filter by “Zixflow”).

3. Test on Physical Device or Emulator

Physical Device: Always works with valid google-services.json Emulator: Requires:

Google Play Services installed
Signed in with Google account
Internet connectivity

4. Send Test Push from Zixflow

Log into Zixflow dashboard
Navigate to Messaging → Push Notifications
Create test push notification
Send to specific user (using userId from identify())

Troubleshooting

google-services.json Not Found

Error: File google-services.json is missing Solution:

Verify google-services.json is in app/ directory
Sync Gradle: File → Sync Project with Gradle Files
Clean and rebuild: Build → Clean Project → Rebuild Project

Push Notifications Not Received

Symptoms: Notifications sent but not delivered Solutions:

Verify FCM Server Key configured in Zixflow dashboard
Ensure user is identified: Zixflow.instance().identify(userId = ...)
Check POST_NOTIFICATIONS permission granted (Android 13+)
Verify device token registered: Zixflow.instance().registeredDeviceToken
Test on physical device or emulator with Google Play Services
Check Firebase console for delivery status

Device Token Not Registering

Symptoms: registeredDeviceToken returns null Solutions:

Verify google-services.json is correct and in app/ directory
Ensure google-services plugin is applied
Check Google Play Services available on device
Verify app package name matches Firebase configuration
Check logs for FCM token generation errors

Notification Not Displayed

Symptoms: Push delivered but not shown Solutions:

Check notification channels (Android 8.0+)
Verify notification permission granted
Ensure app not in “Do Not Disturb” mode
Check notification settings for your app
Verify custom notification callback isn’t blocking display

Rich Media Not Loading

Symptoms: Images/videos not appearing in notifications Solutions:

Verify media URL is accessible from device
Check internet connectivity
Ensure media format is supported (JPEG, PNG, GIF for images)
Check file size (large files may timeout)

Best Practices

Always identify users before sending push notifications
Request permission thoughtfully - explain value before requesting
Use ACTIVITY_PREVENT_RESTART for better user experience
Test on multiple devices and Android versions
Enable debug logging during development
Monitor metrics in Zixflow dashboard
Handle permission denial gracefully
Test deep links thoroughly
Customize notification appearance to match app branding
Keep google-services.json secure - don’t commit to version control

​Prerequisites

​Step 1: Firebase Project Setup

​1. Create Firebase Project

​2. Add Android App to Firebase

​3. Add google-services.json to Project

​Step 2: Add Dependencies

​1. Add Google Services Plugin

​2. Apply Plugin in App Module

​3. Add Zixflow and Firebase Dependencies

​Step 3: Initialize Zixflow with Push Support

​Basic Initialization (Kotlin)

​Basic Initialization (Java)

​Step 4: Register Application in AndroidManifest.xml

​Step 5: Request Push Notification Permission (Android 13+)

​Request Permission in Activity

​Step 6: Identify Users

​Configuration Options

​Configuration Options

​Push Click Behaviors

​Advanced Features

​Customize Notification Appearance

​Attach action buttons

​Configure Default Icon and Color

​Rich Push Notifications

​Custom FirebaseMessagingService (dual-path)

​Tracking Push Metrics

​Deep Links and Custom Actions

​Testing Push Notifications

​1. Verify Device Token Registration

​2. Enable Debug Logging

​3. Test on Physical Device or Emulator

​4. Send Test Push from Zixflow

​Troubleshooting

​google-services.json Not Found

​Push Notifications Not Received

​Device Token Not Registering

​Notification Not Displayed

​Rich Media Not Loading

​Best Practices

Prerequisites

Step 1: Firebase Project Setup

1. Create Firebase Project

2. Add Android App to Firebase

3. Add google-services.json to Project

Step 2: Add Dependencies

1. Add Google Services Plugin

2. Apply Plugin in App Module

3. Add Zixflow and Firebase Dependencies

Step 3: Initialize Zixflow with Push Support

Basic Initialization (Kotlin)

Basic Initialization (Java)

Step 4: Register Application in AndroidManifest.xml

Step 5: Request Push Notification Permission (Android 13+)

Request Permission in Activity

Step 6: Identify Users

Configuration Options

Configuration Options

Push Click Behaviors

Advanced Features

Customize Notification Appearance

Attach action buttons

Configure Default Icon and Color

Rich Push Notifications

Custom FirebaseMessagingService (dual-path)

Tracking Push Metrics

Deep Links and Custom Actions

Testing Push Notifications

1. Verify Device Token Registration

2. Enable Debug Logging

3. Test on Physical Device or Emulator

4. Send Test Push from Zixflow

Troubleshooting

google-services.json Not Found

Push Notifications Not Received

Device Token Not Registering

Notification Not Displayed

Rich Media Not Loading

Best Practices