# Flutter SDK Documentation Generated on: 4/17/2026 This documentation bundle contains the complete Flutter SDK documentation for use with LLMs and offline reference. --- ## Quick start guide **Source:** /integrations/sdk/flutter/quick-start-guide # Quick Start Guide Before you can take advantage of our SDK, you need to install and initialize the SDK.  Our MCP server can help you get started Our MCP server includes SDK-installation tools that can help you get integrated quickly with Customer.io and troubleshoot any issues you might have. See [Set up an MCP server](/ai/mcp-server/) to get started. ## Setup process overview[](#setup-process-overview) Flutter lets you build native mobile apps using Dart. Our Flutter SDK helps you integrate Customer.io to `identify` people, `track` their activity, and send both push notifications and in-app messages. 1. [Install and initialize the SDK.](#install-init) 2. [Identify and Track](#identify-and-track) 3. [Push Notifications](#push-notifications) 4. [In-App](#in-app) ## 1\. Install the SDK[](#install-init) 1. In your project folder install the `customer_io` package: ```shell flutter pub add customer_io ``` This adds a line to your package’s `pubspec.yaml` ```yaml dependencies: customer_io: ^4.0.0 ``` 2. Set up your project to support iOS and/or Android: iOS #### iOS[](#iOS) 1. Set up your iOS dependencies: * **CocoaPods**: Run `pod install --repo-update --project-directory=ios`. * **SPM**: Make sure SPM is enabled in your Flutter project (see [Flutter docs](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers)), and run `flutter pub get`. The SDK is automatically resolved. For full iOS setup details, including the Notification Service Extension for rich push, see [Set up push notifications](/integrations/sdk/flutter/push-notifications/push-setup/). Android #### Android[](#Android) 1. Go to the Android subfolder and include [google-services-plugin](https://developers.google.com/android/guides/google-services-plugin) by adding the following lines to the project-level `android/build.gradle` file: ```groovy buildscript { repositories { // Add this line if it isn't already in your build file: google() // Google's Maven repository } dependencies { // Add this line: classpath 'com.google.gms:google-services:' // Google Services plugin } } allprojects { repositories { // Add this line if it isn't already in your build file: google() // Google's Maven repository } } ``` 2. Add the following line to `android/app/build.gradle`: ```groovy apply plugin: 'com.google.gms.google-services' // Google Services plugin ``` 3. Download `google-services.json` from your Firebase project and copy the file to `android/app/google-services.json`. 3. Initialize the SDK: 1. Add your *CDP API key* and *site ID* to your configuration. * **CDP API Key**: You’ll find this key in your [*Flutter* connection](/integrations/sdk/flutter/getting-started/auth/#get-your-cdp-api-key). * **Site ID**: You’ll find this value in your workspace under **[Settings > Workspace Settings > API and webhook credentials](https://fly.customer.io/workspaces/last/settings/api_credentials)**. 2. Initialize the SDK in your app. In your `main.dart` file—or wherever you want to initialize the `CustomerIO` plugin—add the code below: ```dart import 'package:customer_io/customer_io.dart'; import 'package:customer_io/customer_io_config.dart'; import 'package:customer_io/customer_io_enums.dart'; await CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: 'cdpApiKey', region: Region.us, // Replace with Region.EU if your Customer.io account is in the EU. inAppConfig: InAppConfig(siteId: 'siteId'), ), ); ``` 3. Run your application to ensure everything is set up correctly. ## 2\. Identify and Track[](#identify-and-track) 1. Identify a user in your app using the `CustomerIO.identify` method. You *must* identify a user before you can send push notifications and personalized in-app messages. ```dart CustomerIO.instance.identify(userId: email, traits: { "name": user.displayName, "email": user.email, "age": user.age, }); ``` 2. Track a custom event using the `CustomerIO.track` method. Events help you trigger personalized campaigns and track user activity. ```dart CustomerIO.instance.track(name: "add-to-cart", properties: {"product": "shoes", "price": "29.99"}); ``` 3. Track screen views to trigger in-app messages associated with specific screens. ```dart CustomerIO.instance.screen(title: "screen-name", properties: {"property": "value"}); ``` ## 3\. Push Notifications[](#push-notifications) iOS #### iOS[](#iOS) 1. Set up your push notification credentials in Customer.io: [Upload your Firebase Cloud Messaging server key](https://fly.customer.io/workspaces/last/settings/actions/push/ios) (.json format). Our Flutter SDK uses FCM for both iOS and Android push notifications. 2. Request push notification permissions from the user. You can do this through [Firebase](https://firebase.google.com/docs/cloud-messaging/flutter/receive) or any other package. 3. To ensure that metrics are tracked, configure Background Modes. In Xcode, enable “Remote notifications” under Capabilities > Background Modes. Android #### Android[](#Android) 1. Set up your push notification credentials in Customer.io: [Upload your Firebase Cloud Messaging server key](https://fly.customer.io/workspaces/last/settings/actions/push/android) (.json format). 2. Request push notification permissions from the user. You can do this through [Firebase](https://firebase.google.com/docs/cloud-messaging/flutter/receive) or any other package. 3. Ensure that you: 1. [Add your Google Firebase Cloud Messaging (FCM) key to Customer.io and enable push notifications for Android](https://docs.customer.io/journeys/push-developer-guide/#fcm-setup). Our Flutter SDK receives push notifications from FCM. 2. Add notification icon resources: * Place a notification icon file named `ic_notification.png` in your drawable folders. * Make sure your app’s `AndroidManifest.xml` has the proper FCM permissions. ## 4\. In-App[](#in-app) 1. To enable in-app messaging, all you need to do is add your site ID. Remember, you’ll find your site ID under **[Data & Integrations > Integrations > Customer.io API: Track](https://fly.customer.io/workspaces/last/settings/api_credentials)** in the *Connections* tab. 2. Ensure that the SDK is initialized with the site ID in your app. You can call the `initialize` method from your components or services: ```dart import 'package:customer_io/customer_io.dart'; import 'package:customer_io/customer_io_config.dart'; import 'package:customer_io/customer_io_enums.dart'; await CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: 'cdpApiKey', region: Region.us, // Replace with Region.EU if your Customer.io account is in the EU. inAppConfig: InAppConfig(siteId: 'siteId'), pushConfig: PushConfig( android: PushConfigAndroid( pushClickBehavior: PushClickBehaviorAndroid.activityPreventRestart, ), ), ), ); ``` --- ## Getting started > Auth **Source:** /integrations/sdk/flutter/getting-started/auth # Authentication To use the SDK, you’ll need to get two kinds of keys: A [*CDP API Key*](#get-your-cdp-api-key) to send data to Customer.io and a [*Site ID*](#get-your-site-id) that tells the SDK which workspace your messages come from. ## Get your *CDP API Key*[](#get-your-cdp-api-key) You’ll use a *CDP API Key* to initialize the SDK and send data to Customer.io. You’ll get this key when you set up your mobile app as a data inAn integration that feeds data *into* Customer.io. integration in Customer.io. If you haven’t already set up your integration in Customer.io, you’ll need to [do that first](#set-up-a-new-source). 1. Go to *Data & Integrations* > *Integrations*. 2. Select your Flutter integration in the *Overview* tab. If you don’t see a Flutter integration, you’ll need to [set it up](#set-up-a-new-source). [![the connections page, showing an Flutter source connected to a journeys destination](https://customer.io/images/cdp-flutter-connected-destination.png)](#edc51817a2a0a610a00abf67036b480a-lightbox) 3. Go to **Settings** and find your **CDP API Key**. Copy this key into your initialization call. If you’re upgrading from a previous version of the SDK, you should set the `siteId` that you used in previous versions as the `migrationSiteId` in your config. [![get your CDP API Key from your source's settings page](https://customer.io/images/cdp-flutter-source-api-key.png)](#2c83f740c0d874640e927aa6b27aa0a9-lightbox) ```dart CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: '', //migrationSiteId is required if you're updating from a previous version migrationSiteId: '', region: Region.us, // Replace with Region.EU if your Customer.io account is in the EU. autoTrackDeviceAttributes: true, inAppConfig: InAppConfig(siteId: ''), ), ); ```  You’re not done yet You still need your [Site IDEquivalent to the *user name* you’ll use to interface with the Journeys Track API; also used with our JavaScript snippets. You can find your Site ID under *Workspace Settings* > *API Credentials*](https://fly.customer.io/env/last/settings/api_credentials) to initialize the `CioMessagingInApp` package and to support people updating your app from a previous version of Customer.io SDK. See [Get your Site ID](#get-your-site-id) below. ### Set up a new integration[](#set-up-a-new-source) If you don’t already have a write key, you’ll need to set up a new data inAn integration that feeds data *into* Customer.io. integration in Customer.io. The “integration” represents your app and the stream of data that you’ll send to Customer.io. 1. Go to [*Data & Integrations* > *Integrations*](https://fly.customer.io/workspaces/last/journeys/integrations/all/overview) and click **Add Integration**. 2. Select **Flutter**. [![set up your Flutter integration](https://customer.io/images/cdp-flutter-source.png)](#b313d06604f0b0ea2cab391b1806b3cd-lightbox) 3. Enter a *Name* for your integration, like “My Flutter App”. 4. We’ll present you with a code sample containing a `cdpApiKey` that you’ll use to initialize the SDK. Copy this key and keep it handy. 5. Test your connection and click **Complete Setup**. Or, if you don’t want to test your implementation yet, **Save & Complete Later** and then click **Install Source** to finish the setup process. In this case, *Complete Later* simply means that we haven’t seen any data from your Flutter app yet. [![Set your name, get your CDP API Key, and click Complete Setup](https://customer.io/images/cdp-flutter-source-setup.png)](#1d7ba11eb6f6a64e4b1e289803050598-lightbox) Remember, you can also [connect your Flutter app to services outside of Customer.io](/integrations/data-out/add-destination/)—like your analytics provider, data warehouse, or CRM. ## Get your Site ID[](#get-your-site-id) You’ll use your Site ID to send in-app messages from your workspace. If you’re upgrading from a previous version, my can also set your Site ID as your `migrationSiteId`. This key is used to send remaining tasks to Customer.io when your audience updates your app. 1. Go to and select **Workspace Settings** in the upper-right corner of the Customer.io app and go to [**API and Webhook Credentials**](https://fly.customer.io/workspaces/last/settings/api_credentials). 2. Copy the **Site ID** for the set of credentials that you want to send your in-app messages from. If you don’t have a set of credentials, click **Create Tracking API Key**. [![find your site ID](https://customer.io/images/cdp-js-site-id.png)](#64d2b27827ffddb00dc77b851a7a6854-lightbox) 3. You’ll use this key to initialize the `inApp` package. If you’re upgrading from a previous version, you’ll also use it as your `migrationSiteId`. ```dart CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: '', //required if you're updating from a previous version migrationSiteId: '', region: Region.us, // Replace with Region.EU if your Customer.io account is in the EU. autoTrackDeviceAttributes: true, inAppConfig: InAppConfig(siteId: ''), ), ); ``` ## Securing your credentials[](#securing-your-credentials) To simplify things, code samples in our documentation sometimes show API keys directly in your code. But you don’t have to hard-code your keys in your app. You can use environment variables, management tools that handle secrets, or other methods to keep your keys secure if you’re concerned about security. To be clear, the keys that you’ll use to initialize the SDK don’t provide read access to data in Customer.io; they only write data to Customer.io. A bad actor who found your credentials can’t use your keys to read data from our servers. --- ## Getting started > How it works **Source:** /integrations/sdk/flutter/getting-started/how-it-works # How it works Before you can take advantage of our SDK, you need to install the module(s) you want to use, initialize the SDK, and understand the order of operations. Our SDKs provide a ready-made integration to identify people who use mobile devices and send them notifications. Before you start using the SDK, you should understand a bit about how the SDK works with Customer.io. Before a person logs into your app, any activity they perform is associated with an anonymous person in Customer.io. In this state, you can track their activity, but you can’t send them messages through Customer.io. When someone logs into your app, you’ll send an `identify` call to Customer.io. This makes the person eligible to receive messages and reconciles their anonymous activity to their identified profile in Customer.io. You send messages to a person through the Customer.io campaign builder, broadcasts, etc. These messages are not stored on the device side. If you want to send an event-triggered campaign to a mobile device, the mobile device user must be identified and have a connection such that it can send an event back to Customer.io and receive a message payload. ## Your app is a data source and Customer.io is a destination[](#your-app-is-a-data-source-and-customerio-is-a-destination) Our SDK is a data inAn integration that feeds data *into* Customer.io. integration. It routes data from your app to both Customer.io *and* any other outbound services where you might use your mobile data. This makes it easy to use your app as a part of your larger data stack without using extra packages or code. When you set up your app, you’ll integrate our SDK. But you’ll also determine where you want to route your data to—your Customer.io workspace *and* destinations outside of Customer.io. ## Minimum support requirements[](#minimum-support-requirements) To support the Customer.io SDK, you must: * Use Gradle 8.0 or later. * Use Android Gradle plugin version 8.0 or later (8.2+ recommended). * Use Kotlin 1.9.20 or later (2.0+ required if using Kotlin Multiplatform or K2-specific features). * Set iOS 13 or later as your minimum deployment target in XCode * Have an Android device or emulator with Google Play Services enabled and a minimum OS version between Android 5.0 (API level 21) and Android 13.0 (API level 33). * Have an iOS 13+ device to test your implementation. You cannot test push notifications in a simulator. ## The Processing Queue[](#the-processing-queue) The SDK automatically adds all calls to a queue system, and waits to perform these calls until certain criteria is met. This queue makes things easier, both for you and your users: it handles errors and retries for you (even when users lose connectivity), and it can save users’ battery life by batching requests. The queue holds requests until any one of the following criteria is met: * There are 20 or more tasks in the queue. * 30 seconds have passed since the SDK performed its last task. * The app is closed and re-opened. For example, when you identify a new person in your app using the SDK, you won’t see the created/updated person immediately. You’ll have to wait for the SDK to meet any of the criteria above before the SDK sends a request to the Customer.io API. Then, if the request is successful, you’ll see your created/updated person in your workspace. --- ## Getting started > Packages options **Source:** /integrations/sdk/flutter/getting-started/packages-options # Configuration Options The SDK consists of a few packages. You’ll get the most value out of Customer.io when you use all our packages together, but this lets you omit packages for features you don’t intend to use. You’ll call configuration options before you initialize the SDK with `CustomerIOConfig`. When you initialize the SDK, you can pass configuration options. In most cases, you’ll want to stick with the defaults, but you might do things like change the `logLevel` when testing updates to your app. ```dart CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: "YOUR_CDP_API_KEY", // Required migrationSiteId: "YOUR_SITE_ID", // Required to migrate from a previous version autoTrackDeviceAttributes: true, region: Region.us, logLevel: CioLogLevel.error ) ); ``` Option Type Default Description `cdpApiKey` string **Required**: the key you'll use to initialize the SDK and send data to Customer.io `region` `eu` or `us` `us` **Required if your account is in the EU region**. `apiHost` string The domain you’ll proxy requests through. You’ll only need to set this (and `cdnHost`) if you’re [proxying requests](#proxying-requests). `autoTrackDeviceAttributes` boolean `true` Automatically gathers information about devices, like operating system, device locale, model, app version, etc `cdnHost` string The domain you’ll fetch configuration settings from. You’ll only need to set this (and `apiHost`) if you’re [proxying requests](#proxying-requests). `logLevel` string `error` Sets the level of logs you can view from the SDK. Set to `debug` or `info` to see more logging output. `migrationSiteId` string **Required if you're updating from 1.x**: the credential for previous versions of the SDK. We use this key to send remaining tasks to Customer.io when your audience updates your app. `screenViewUse` `All` or `inApp` `all` `ScreenView.all` (Default): Screen events are sent to Customer.io. You can use these events to build segments, trigger campaigns, and target in-app messages. `ScreenView.InApp`: Screen view events not sent to Customer.io. You’ll *only* use them to target in-app messages based on page rules. `trackApplicationLifecycleEvents` boolean `true` Set to `false` if you don’t want the app to send [lifecycle events](/integrations/sdk/flutter/tracking/lifecycle-events) like `Application Opened` `inApp.siteId` string Used to initialize the `inApp` package, and determines the workspace your in-app messages come from. `push.android.pushClickBehavior` string `activityPreventRestart` One of `resetTaskStack`, `activityPreventRestart`, `activityNoFlags`; determines how to handle push clicks. `locationConfig` object Enable [location tracking](/integrations/sdk/flutter/tracking/location/). Takes a `trackingMode` option using the `LocationTrackingMode` enum. ## Proxying requests[](#proxying-requests) By default, requests go through our domain at `cdp.customer.io`. You can proxy requests through your own domain to provide a better privacy and security story, especially when submitting your app to app stores. To proxy requests, you’ll need to set the `apiHost` and `cdnHost` properties in your `SDKConfigBuilder`. While these are separate settings, you should set them to the same URL. While you need to initialize the SDK with a `cdpApiKey`, you can set this to any value you want. You only need to pass your actual key when you send requests from your server backend to Customer.io. If you want to secure requests to your proxy server, you can set the `cdpApiKey` to a value representing basic authentication credentials that you handle on your own. See [proxying requests](/integrations/data-in/proxying-requests) for more information. ```dart CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: "YOUR_CDP_API_KEY", apiHost: "YOUR_PROXY_HOST", cdnHost: "YOUR_CDN_HOST", region: Region.us, logLevel: CioLogLevel.error ) ) ``` --- ## Getting started > Troubleshooting **Source:** /integrations/sdk/flutter/getting-started/troubleshooting # Troubleshooting If you’re having trouble with the SDK, here are some basic steps to troubleshoot your problems, and solutions to some known issues. ## Basic troubleshooting steps[](#basic-troubleshooting-steps) 1. **Make sure your app meets our [prerequisites](/integrations/sdk/flutter/getting-started/#prerequisites)**: Attempting to use our SDK in an environment that doesn’t match our supported versions may result in build errors. 1. **Update to the latest version**: When troubleshooting problems with our SDKs, we generally recommend that you try updating to the latest version. That helps us weed out issues that might have been seen in previous versions of the SDK. 2. **Try running our MCP server**: Our MCP server includes an `integration` tool that can provide immediate help with your implementation, including problems with push and in-app notifications. See [Use our MCP server to troubleshoot your implementation](#troubleshoot-with-mcp) below. 3. **Enable `debug` logging**: Reproducing your issue with `loglevel` set to `debug` can help you (or us) pinpoint problems.  Don’t use debug mode in your production app Debug mode is great for helping you find problems as you integrate with Customer.io, but we strongly recommend that you set `loglevel` to `error` in your publicly available, production app. 4. **Try our test image**: Using [an image](#image-display-issues) that we know works in push and in-app notifications can help you narrow down problems relating to images in your messages. ### If you need to contact support[](#if-you-need-to-contact-support) We’re here to help! If you contact us for help with an SDK-related issue, we’ll generally ask for the following information. Having it ready for us can help us solve your problem faster. 1. **Share information about your device and environment**: Let us know where you had an issue—the SDK and version of the SDK that you’re using, the specific device, operating system, message, use case, and so on. The more information you share with us, the easier it is for us to weed out externalities and find a solution. 2. **Provide comprehensive debug logs**: When sharing logs with our support team, please ensure your logs include: * **SDK initialization**: Show that the SDK was initialized with your site ID and API key * **Profile identification**: Show that a profile was identified in your app * **Issue reproduction**: Capture the exact issue you’re experiencing * **Unfiltered logs**: Provide complete, unfiltered logs—don’t remove or filter out any log entries * **Debug level enabled**: Make sure `loglevel` is set to `debug` when capturing logs for support 3. **For push notification issues**: * **Use live push examples**: If your issue relates to push notifications, provide logs from a **live push notification** sent through a campaign or API call, not a test send. Live pushes show the actual payload that was delivered to the profile. * **Test in different app states**: Test and document the issue in various app states: * **Foreground**: App is open and active * **Background**: App is running but not in focus * **Killed/Terminated**: App is completely closed * **Include the push payload**: Share the complete push notification payload that you sent. 4. **[Grant access to your workspace](/journeys/privacy/#support-team-access)**: It may help us to see exactly what triggers a campaign, what data is associated with devices you’re troubleshooting, etc. You can grant access for a limited time, and revoke access at any time. ### Troubleshooting issues with our MCP server[](#troubleshoot-with-mcp) Our [MCP server](/ai/mcp-server/) includes an `integration` tool that can help troubleshoot your implementation, including problems with push and in-app notifications. It has a deep understanding of our SDKs and provides an immediate way to get support with your implementation—without necessarily needing to capture debug logs, etc. You can ask the MCP server basic questions like, “My push notifications aren’t working. Can you help me troubleshoot the problem?” Or you can ask more specific questions like, “Deep links in push notifications don’t work for customers in my Android app.” Or “I’m not receiving metrics for push notifications for iOS users.” The tool will return detailed steps to help you find and troubleshoot problems. ### Capture logs[](#capture-logs) Logs help us pinpoint the problem and find a solution. To capture logs, you should [install Flutter DevTools](https://docs.flutter.dev/tools/devtools) if you haven’t already. 1. **Enable debug logging in your app**.  You should not use debug mode in your production app. Remember to disable debug logging before you release your app to the App Store. ```dart import 'package:customer_io/customer_io.dart'; import 'package:customer_io/customer_io_config.dart'; import 'package:customer_io/customer_io_enums.dart'; await CustomerIO.initialize( config: CustomerIOConfig( siteId: "919a7e12107bd03155f6", apiKey: "86344654754f1c48d32b", region: Region.us, //config options go here logLevel: CioLogLevel.debug ), ); ``` 2. Build and run your app on a physical device or emulator. 3. Open the *Logging* view in your development application. If you use *Android Studio*, select *View > Tool Windows > Logcat* to see your logs. 4. Filter for `CIO` in the top to find log messages specific to the Customer.io SDK. 5. Export your log and send it to our Support team at [win@customer.io](mailto:win@customer.io). In your message, describe your problem and provide relevant information about: * The version of the SDK you’re using. * The type of problem you’ve encountered. * An existing GitHub issue URL or existing support email so we know what these log files are in reference to. #### Capturing iOS logs[](#capturing-ios-logs) Logs for iOS are emitted via Apple’s Unified Logging system, so you’ll need to capture them using Xcode or the MacOS console, not just the Flutter debug console. The `logLevel` set in your `CustomerIOConfig` is forwarded to the native iOS SDK, but these logs won’t reliably appear in `flutter run` output. To capture iOS logs for troubleshooting: 1. **Run your iOS app via Xcode** or on a device/simulator attached to Xcode. 2. **Use the macOS Console** to capture logs. You might want ot filter for `CIO` to find log messages specific to the Customer.io SDK. ## NaN, infinite, or imaginary number values[](#nan-infinite-or-imaginary-number-values) Customer.io doesn’t handle invalid JSON values in your payloads, like `NaN`, infinite, or imaginary number values. If you send these values in `identify`, `track`, `screen`, or similar calls, we’ll drop them and record errors. While we drop invalid values, we don’t drop the entire payload. The operation itself will still succeed. For example, if you send an identify call with two attributes, one of which is a `NaN` value, we’ll drop the `NaN` value, but the identify call succeeds with the other attribute. ## Push notification issues[](#push-notification-issues) ### Problems with rich push notifications (images, delivered metrics, etc)[](#problems-with-rich-push-notifications-images-delivered-metrics-etc) If you have trouble with rich push features, like images not showing up in your push notifications, delivery metrics not being reported when a push notification is visible on the device, and so on, it’s possible that you either need to re-create your NSE target to support rich notifications your you may not have embeded the `NotificationServiceExtension` (NSE) at all. 1. Remove your current NSE extension. 1. In XCode, select your project. 2. Go to the *Signing & Capabilities* tab. 3. Click the NotificationServiceExtension target; it has a bell icon next to it. 4. Click the minus sign to remove the target 5. Confirm the **Delete** operation. [![an image illustrating the 5 clicks you'll perform to delete your NSE target.](https://customer.io/images/delete-nse-1.png)](#c66794617622894d2a61b5a026240a3b-lightbox) 2. Remove existing NSE files. 1. Right click the `NotificationServiceExtension` folder in your project and select **Delete**. 2. Confirm **Move to Trash**. [![an image illustrating the steps you'll take to delete NSE files.](https://customer.io/images/delete-nse-2.png)](#6a5a6ee211296a0c49beb046b941bfd8-lightbox) 3. Recreate the notification service extension, following instructions for your framework. When You create your target NSE file, make sure you select your app’s name from the *Embed in Application* dropdown. [![xcode-servicenotification3.png](https://customer.io/images/xcode-servicenotification3.png)](#97f7eea0f5f268a29a24b1bdea3c767c-lightbox) 4. Then add the required files: * [React Native](/integrations/sdk/react-native/push-notifications/push/#integrate-push-capabilities-in-your-app) * [Flutter](/integrations/sdk/flutter/push-notifications/push-setup/#swift-push) * Expo (does this automatically) * [iOS](/integrations/sdk/ios/push/#rich-push) 5. After all files are added, go to the NSE target and, under the **General** tab, check **Deployment Target** and set it to a value that is identical to your host app’s iOS version. [![troubleshoot-nse.png](https://customer.io/images/troubleshoot-nse.png)](#7e7c735e2a16c72a6db71ef6cf9fc50b-lightbox) When you create a new target, by default, XCode sets the highest version of deployment target version available. While testing if your device’s iOS version is lower than this deployment target, then the NSE won’t be connected to the main target and you won’t receive rich push notifications. Then you can build and run your app to test if you can receive a rich push notification. ### Why aren’t devices added to people in Production builds?[](#why-arent-devices-added-to-people-in-production-builds) If you see devices register successfully on your Staging builds, but not in Production or TestFlight builds, there might be an issue with your project setup. Check that the Push capability is enabled for both Release and Debug modes in your project. You might also need to enable the *Background Modes (Remote Notifications)* capability, depending on your project setup and messaging needs. ### Image display issues[](#image-display-issues) If you’re having trouble, try using our test image in a message! If it works, then there’s likely a problem with your original image. [![a test image of a bird that we know will work with all push notifications](https://customer.io/images/push-image-control.jpg)](#880a298d31bff7acc0ac56edbb6a6dc6-lightbox) Android and iOS devices support different image sizes and formats. In general, you should stick to the smallest size (under 1 MB—the limit for Android devices) and common formats (PNG, JPEG). iOS Android In-App (all platforms) **Format** JPEG, PNG, BMP, GIF JPEG, PNG, BMP JPEG, PNG, GIF **Maximum size** 10 MB\* 1 MB **Maximum resolution** 2048 x 1024 px 1038 x 1038 px \*For linked media only. If you host images in our Asset Library, you’re limited to 3MB per image. ### Why didn’t everybody in my segment get a push notification?[](#why-didnt-everybody-in-my-segment-get-a-push-notification) If your [segmentA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions.](/journeys/data-driven-segments/) doesn’t specify people who have an existing device, it’s likely that people entered your segment without using your app. If you send a push notification to such a segment, the “Sent” count will probably show fewer sends than there were people in your segment. ### Why are messages sent but not delivered or opened?[](#why-are-messages-sent-but-not-delivered-or-opened) The *sent* status means that we sent a message to your delivery provider—APNS or FCM. It’ll be marked *delivered* or *opened* when the delivery provider forwards the message to the device and the SDK reports the metric back to Customer.io. If a person turned their device off or put it in airplane mode, they won’t receive your push notification until they’re back on a network.  Make sure you’ve configured your app to track metrics If your app isn’t set up to capture push metrics, your app will *never* report `delivered` or `opened` metrics! ### Why don’t my messages play sounds?[](#why-dont-my-messages-play-sounds) When you send a push notification to iOS devices that uses our SDK, you can opt to send the *Default* system sound or no sound at all. If your audience’s phone is set to vibrate, or they’ve disabled sound permissions for your app, the *Default* setting will cause the device to vibrate rather than playing a sound. In most cases, you should use the *Default* sound setting to make sure your audience hears (or feels) your message. But, before you send sound, you should understand: 1. Your app needs permission from your users to play sounds. This is done by your app, not our SDKs. [Here’s an example from our iOS sample app](https://github.com/customerio/customerio-ios/blob/main/Apps/APN-UIKit/APN%20UIKit/Util/NotificationUtil.swift#L12-L13) showing how to request sound permissions. 2. iOS users can go into *System Settings* and disable sound permissions for your app. Enabling the *Default* setting doesn’t guarantee that your audience hears a sound when your message is delivered!  We don’t support custom sounds yet If you want to send a custom sound, you’ll need to handle it on your own, outside the SDK and use a custom payload when you set up your push notifications. ### FCM `SENDER_ID_MISMATCH` error[](#fcm-sender_id_mismatch-error) This error occurs when the FCM Sender ID in your app does not match the Sender ID in your Firebase project. To resolve this issue, you’ll need to ensure that the Sender ID in your app matches the Sender ID in your Firebase project. 1. Check that you uploaded the correct JSON certificate to Customer.io. If your JSON certificate represents the wrong Firebase project, you may see this error. 2. Verify that the Sender ID in your app matches the Sender ID in your Firebase project. 3. If you imported devices (device tokens) from a previous project, make sure that you imported tokens from the correct Firebase project. If the tokens represent a different app than the one you send push notifications to, you’ll see this error. In some cases, we may make fixes in our iOS push packages that fix downstream issues in the Flutter SDK. Before you contact support, you might want to \[update your iOS dependencies\](/Page(/integrations/sdk/flutter/push/#update-ios-dependencies) to get the latest packages and see if that fixes the issue. You can also check out our latest iOS changes to see if we’ve already fixed the issue or check out open issues to see if you’re experiencing a known issue. ### Deep links on iOS only open in a browser[](#deep-links-on-ios-only-open-in-a-browser) It sounds like you want to use [universal links](/universal-links/#deep-links-vs-universal-links)—links that go to your app if a person has your app installed and to your website if they don’t. Universal links are a bit different than your average deep link and require a little bit of additional setup. ### Notifications not coming through when app is in background[](#notifications-not-coming-through-when-app-is-in-background) If your app does not receive push notifications when it’s in the background, check the following: 1. Ensure that you have implemented the `_firebaseMessagingBackgroundHandler` as suggested by the [Firebase Messaging documentation](https://firebase.google.com/docs/cloud-messaging/flutter/receive#background_messages). This handler is responsible for processing messages received while the app is in the background or closed. 2. Verify that the handler is set correctly and receiving callbacks. Double-check the implementation to ensure it’s properly registered within your app’s code. 3. Confirm the Flutter version you are using. For Flutter version 3.3.0 or higher, you will need to add `@pragma('vm:entry-point')` to the handler function for it to work correctly. ## Swift Package Manager (SPM) issues[](#spm-issues) ### `Unable to find module dependency: 'CioMessagingPushFCM'` in NSE[](#unable-to-find-module-dependency-ciomessagingpushfcm-in-nse) The NotificationServiceExtension target is missing the SPM package link. 1. In Xcode, select the **NotificationServiceExtension** target and go to **General** > **Frameworks and Libraries** 2. Click **+** and add **FlutterGeneratedPluginSwiftPackage**. [![Add FlutterGeneratedPluginSwiftPackage to the NotificationServiceExtension target](https://customer.io/images/xcode-nse-spm-framework.png)](#63f96c00dae3d457f55911fae69d4722-lightbox) ### `redefinition of module 'Firebase'`[](#redefinition-of-module-firebase) Firebase is being loaded from both CocoaPods and SPM, causing a conflict. 1. Update your Firebase dependencies to SPM-compatible versions in your `pubspec.yaml`: ```yaml firebase_core: ^3.5.0 # we recommend at least ^4.6.0 firebase_messaging: ^15.2.0 # we recommend at least ^16.1.3 ``` 2. Remove any manual Firebase pod lines from your `ios/Podfile` and run `flutter pub upgrade firebase_core firebase_messaging`. ### `requires minimum platform version 15.0 for the iOS platform`[](#requires-minimum-platform-version-150-for-the-ios-platform) The Customer.io SDK and Firebase require iOS 15.0 or later. Set the deployment target to 15.0 or later in Xcode: 1. Select the **Runner** project and go to **Build Settings** 2. Set **iOS Deployment Target** to **15.0**. 3. Update your `ios/Podfile`: ```ruby platform :ios, '15.0' ``` ### NSE unable to find `CioMessagingPushFCM` dependency[](#nse-unable-to-find-ciomessagingpushfcm-dependency) The NotificationServiceExtension can’t resolve the Customer.io SDK dependency. This can happen in both local builds and CI environments. 1. Make sure SPM is enabled before building. You can enable it globally or per-project: * **Global**: Run `flutter config --enable-swift-package-manager` * **Per-project**: Add `enable-swift-package-manager: true` to the `flutter:` > `config:` section of your `pubspec.yaml` 2. Clean and rebuild: ```bash flutter clean flutter pub get flutter build ios ``` In your CI pipeline, make sure that you run `flutter config --enable-swift-package-manager` before running `flutter pub get` to ensure that the configuration takes effect. ### `import UserNotifications` error[](#import-usernotifications-error) SPM doesn’t transitively import system frameworks the way CocoaPods does. If your NSE fails to compile with errors about `UNNotificationServiceExtension`, `UNNotificationRequest`, or `UNNotificationContent`, you’re missing the system import. Add `import UserNotifications` at the top of your `NotificationService.swift`: ```swift import CioMessagingPushFCM import UserNotifications ``` ## In-App message issues[](#in-app-message-issues) ### My in-app messages are sent but not delivered[](#my-in-app-messages-are-sent-but-not-delivered) People won’t get your message until they open your app. If you use page rules, they won’t see your message until they visit the right screen(s), so delivery times for in-app messages can vary significantly from other types of messages. --- ## In app messages > In app **Source:** /integrations/sdk/flutter/in-app-messages/in-app # In-app messages ## How it works[](#how-it-works) An in-app message is a message that people see in your app. People won’t see your in-app messages until they open your app. If you set an *expiry* period for your message, and that time elapses before someone opens your app, they won’t see your message. You can also set *page rules* to display your in-app messages when people visit specific pages in your app. However, to take advantage of page rules, you need to use [screen tracking](/integrations/sdk/flutter/tracking/screen-events/#auto-screenview) features. Screen tracking tells us the titles of your screens and which screen a person is on, so we can display in-app messages on the correct pages/screens in your app. ## Set up in-app messaging[](#set-up-in-app-messaging) In-app messages are disabled by default. Just pass the `inAppConfig` parameter in your `CustomerIOConfig` and add your [Site IDEquivalent to the *user name* you’ll use to interface with the Journeys Track API; also used with our JavaScript snippets. You can find your Site ID under *Workspace Settings* > *API Credentials*](https://fly.customer.io/env/last/settings/api_credentials). ``` 1 2 3 4 5 6 7 8 9 10 11 ``` ```dart import 'package:customer_io/customer_io.dart'; import 'package:customer_io/customer_io_config.dart'; import 'package:customer_io/customer_io_enums.dart'; CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: 'cdpApiKey', region: Region.us, inAppConfig: InAppConfig(siteId: 'siteId') ), ); ``` ## Page rules[](#page-rules) When you send an in-app message, you can set *Page Rules* determining the page(s) where your audience can see your message. Before you can take advantage of page rules, you need to: 1. Track screens in your app. See [Screen Events](/integrations/sdk/flutter/tracking/screen-events/) for help sending `screen` events. 2. Provide screen titles to whoever sets up in-app messages in Customer.io. If we don’t recognize the page that you set for a page rule, your audience will never see your message! [![Set up page rules to limit in app messages by page](https://customer.io/images/in-app-page-rule.png)](#a55af0f9917c15a7b484c9df200f448d-lightbox) Keep in mind: page rules are case sensitive. If you’re targeting your mobile app, make sure your page rules match the casing of the `title` in your `screen` events. If you’re targeting your website, your page rules should always be lowercase. [![The first page rule is Web contains /dashboard. The second page rule is iOS contains Dashboard.](https://customer.io/images/page-rule-case-sensitive.png)](#ba51bbdc9b4c25b5402f99a8a9d30245-lightbox) --- ## In app messages > In app actions **Source:** /integrations/sdk/flutter/in-app-messages/in-app-actions # In-app event listeners ## How it works[](#how-it-works) In-app messages often have a call to action. Most basic actions are handled automatically by the SDK. For example, if you set a call-to-action button to open a web page, the SDK will open the web page when the user taps the button. But you can also set up custom actions that require your app to handle the response. If you set up custom actions, you’ll need to handle the action yourself and dismiss the resulting message when you’re done with it. ### Handle responses to messages (event listeners)[](#event-listeners) You can set up event listeners to handle your audience’s response to your messages. For example, you might run different code in your app when your audience taps a button in your message or when they dismiss the message without tapping a button. You can listen for four different events: * `messageShown`: a message is “sent” and appears to a user * `messageDismissed`: the user closes the message (by tapping an element that uses the `close` action) * `errorWithMessage`: the message itself produces an error—this probably prevents the message from appearing to the user * `messageActionTaken`: the user performs an action in the message. After you initialize the SDK, you can register an event listener to subscribe to in-app events. In the code below, `event` is an instance of `InAppMessageEvent` containing details about the in-app message, e.g. `messageId`, `deliveryId`. ```dart // subscribe to stream StreamSubscription subscription = CustomerIO.inAppMessaging.subscribeToEventsListener((InAppEvent event) { // cases for each event.eventType switch (event.eventType) { case EventType.messageShown: print("messageShown: ${event.message}"); break; case EventType.messageDismissed: print("messageDismissed: ${event.message}"); break; case EventType.errorWithMessage: print("errorWithMessage: ${event.message}"); break; case EventType.messageActionTaken: // event.actionValue => The type of action that triggered the event. // event.actionName => The name of the action specified when building the in-app message. print("messageActionTaken: ${event.message}"); break; } }); // to unsubscribe from the event listener subscription.cancel(); ``` ## Handling custom actions[](#handling-custom-actions) When you set up an in-app message, you can determine the “action” to take when someone taps a button, taps your message, etc. In most cases, you’ll want to deep link to a screen, etc. But, in some cases, you might want to execute some custom action or code—like requesting that a user opts into push notifications or enables a particular setting. In these cases, you’ll want to use the `messageActionTaken` event listener and listen for custom action names or values to execute code. While you’ll have to write custom code to handle custom actions, the SDK helps you [listen for in-app message events](#event-listeners) including your custom action, so you know when to execute your custom code. 1. When you [add an action to an in-app message](/journeys/in-app-messages/) in Customer.io, select *Custom Action* and set your Action’s *Name* and value. The *Name* corresponds to the `actionName`, and the value represents the `actionValue` in your event listener. [![Set up a custom in-app action](https://customer.io/images/in-app-custom-action.png)](#1005ee0b179f3999e81398a57e369557-lightbox) 2. [Register an event listener](#event-listener) for `MessageActionTaken`, and listen for the `actionName` or `actionValue` you set up in the previous step.  Use names and values exactly as entered We don’t modify your action’s name or value, so you’ll need to match the case of names or values exactly as entered in your *Custom Action*. 3. When someone receives a message and invokes the action (tapping a button, tapping a message, etc), your app will perform the custom action. ## Dismiss in-app message[](#dismiss-in-app-message) You can dismiss the currently display in-app message with the following method. This can be particularly useful to dismiss in-app messages when your audience clicks or taps custom actions. ```dart CustomerIO.inAppMessaging.dismissMessage(); ``` ## Deep links[](#deep-links) You can open deep links when a user clicks actions inside in-app messages. Setting up deep links for in-app messages is the same as [setting up deep links for push notifications](/integrations/sdk/flutter/push-notifications/deep-links/). --- ## In app messages > Inbox **Source:** /integrations/sdk/flutter/in-app-messages/inbox # Notification inbox Requires v3.3+This feature requires SDK version 3.3 or later.  Minimum SDK required: 3.3 Users who don’t have a version of your app with Customer.io SDK version 3.3 or later will not see this feature and related messages. If you send inbox messages to users without the minimum required version, they won’t be *delivered*. ## How it works[](#how-it-works) Unlike other messages, inbox messages don’t necessarily appear immediately to users, and they don’t disappear when the user dismisses them. Instead, you’ll display these messages through a notification inbox that your audience can access at their leisure. Customer.io delivers inbox messages as JSON payloads, not fully-rendered messages. The SDK helps you listen for these payloads, but you’ll determine how to display them in your own inbox client. You can send an inbox message as a part of a [campaign, broadcast](/journeys/send-inbox/), or [transactional message](/journeys/send-inbox-txnl/). ## Get the inbox instance[](#get-the-inbox-instance) You’ll access inbox functionality through the `inbox` property on the in-app messaging module. ```dart final inbox = CustomerIO.inAppMessaging.inbox; ``` ## Inbox methods[](#inbox-methods) The inbox instance provides several methods to manage messages. Method Description `fetchMessages({String? topic})` Fetch messages from the inbox. Optionally filter by topic. Returns a Future with the list of messages. `messages({String? topic})` Stream messages from the inbox for real-time updates. Optionally filter by topic. Returns a Stream of message lists. `markMessageOpened(message)` Mark a message as opened. `markMessageUnopened(message)` Mark a message as unopened. `markMessageDeleted(message)` Mark a message as deleted. `trackMessageClicked(message, {String? actionName})` Track a click on the message. The `actionName` parameter is optional. ## Inbox message payloads[](#inbox-message-payloads) Inbox messages are delivered as a JSON payload. The SDK helps you listen for the payload, but you’ll render the content in your own inbox client. The client payload includes the following fields, but you’re most concerned with the `properties` object, which represents your message content. By default, we’ll send a `title` and `body` field, but you can add other fields like an `image` or a `link`—whatever you set up your inbox to expect. Make sure that your team members know what payloads to send—especially if you expect different payloads for different topics or types of messages. Field Type Description `messageId` string Unique identifier for the message. `sentAt` string When the message was sent. `expiresAt` string When the message will expire. `opened` boolean Whether the message has been opened. `topics` array The topics that the message belongs to. `type` string The type of message. `properties` object The properties of the message. ```json { "messageId": "1234567890", "sentAt": "2026-02-05T12:00:00Z", "expiresAt": "2026-02-05T12:00:00Z", "opened": false, "topics": ["orders", "shipping"], "type": "order_shipped", "properties": { "title": "Hey Cool Person, your order shipped!", "body": "You can track your order #1234567890 here:", "link": "https://example.com/orders/1234567890" } } ``` ### Inbox topics and types[](#inbox-topics-and-types) When you send an inbox message, you can assign it to one or more topics. You can use these topics to filter messages when you fetch them. You can also use the topics to determine how to render the messages in your notification inbox. Messages also have a `type`. Think of this like a sub-category or topic for a message. For example, you might have `orders` and `sale` topics, where `orders` don’t have images but `sale` topics might. Or, within the `orders` topic, you might have `order_placed` and `order_shipped` types, where `order_placed` lists order details and images of purchased products and `order_shipped` provides a link to the tracking information for the order that opens in a new tab. ## Setup your notification inbox[](#setup-your-notification-inbox) Inbox messages are just JSON payloads. You’ll need to build your own inbox client to display the messages. The code below gives you a starting point, but you can build your own inbox client however you want. ### Fetch messages[](#fetch-messages) ```dart // Fetch all messages final messages = await inbox.fetchMessages(); // Fetch messages filtered by topic final promotions = await inbox.fetchMessages(topic: 'promotions'); ``` ### Stream messages for real-time updates[](#stream-messages-for-real-time-updates) ```dart // Stream all messages (real-time updates) inbox.messages().listen((messages) { // Update your UI with the messages updateInboxUI(messages); }); // Stream messages filtered by topic inbox.messages(topic: 'promotions').listen((messages) { // Update your UI with promotions updatePromotionsUI(messages); }); ``` ### Mark messages as opened or unopened[](#mark-messages-as-opened-or-unopened) ```dart // Mark a message as opened inbox.markMessageOpened(message); // Mark a message as unopened inbox.markMessageUnopened(message); ``` ### Track message clicks[](#track-message-clicks) ```dart // Track a click without an action name inbox.trackMessageClicked(message); // Track a click with an action name inbox.trackMessageClicked(message, actionName: 'view_details'); ``` ### Delete messages[](#delete-messages) ```dart // Mark a message as deleted inbox.markMessageDeleted(message); ``` ## Working with message properties[](#working-with-message-properties) You can access message properties to display custom content in your inbox: ```dart // Access message properties final title = message.properties['title'] as String?; final body = message.properties['body'] as String?; final link = message.properties['link'] as String?; final imageUrl = message.properties['image'] as String?; // Handle message action when user taps void handleMessageTap(InboxMessage message) { // Mark as opened inbox.markMessageOpened(message); // Track the click inbox.trackMessageClicked(message); // Open link if available final link = message.properties['link'] as String?; if (link != null) { launchUrl(Uri.parse(link)); } } ``` --- ## In app messages > Inline in app **Source:** /integrations/sdk/flutter/in-app-messages/inline-in-app # Inline in-app messages ## How it works[](#how-it-works) An inline message targets a specific widget in your app. You create a placeholder `InlineInAppMessageView` in your UI, and the SDK fills it with the content of your message. Inline messages let you show dynamic content without releasing a new version of your app. Unlike push notifications, banners, or modal in-app messages, an inline message looks and feels like part of your interface. ## 1\. Add View to your app UI to support inline messages[](#1-add-view-to-your-app-ui-to-support-inline-messages) Add `InlineInAppMessageView` anywhere you want to display inline messages. The widget expands or contracts automatically when a message loads or when people interact with it.  See [our sample apps](https://github.com/customerio/customerio-flutter/tree/main/apps) for real-world implementations. ```dart import 'package:customer_io/customer_io.dart'; import 'package:customer_io/customer_io_widgets.dart'; class InlineExample extends StatelessWidget { const InlineExample({super.key}); @override Widget build(BuildContext context) { return InlineInAppMessageView( elementId: 'inline', // Use this ID in Customer.io when you build your message. onActionClick: ( InAppMessage message, String actionValue, String actionName, ) { // Handle button taps or other actions. debugPrint( 'Inline message action clicked: $actionName with value: $actionValue', ); }, ); } } ``` ### View layout[](#view-layout) * Avoid hard-coding a height. The widget manages its own height as messages load and change. * You control layout—padding, margins, alignment—just like any other widget. ## 2\. Build and send your message[](#2-build-and-send-your-message) When you add an in-app message to a broadcast or campaign in Customer.io: 1. Set **Display** to **Inline**. 2. Enter the **Element ID** that matches the `elementId` you set in your widget. 3. (Optional) If you send multiple messages to the same Element ID, set a **Priority** so we know which message to show first. Then design and send your message! [![Inline display settings in the in-app message editor](https://customer.io/images/in-app-inline.png)](#74810b23329cd479a11edfdda9f818e0-lightbox) ## Handling custom actions[](#handling-custom-actions) When you configure an in-app message, you decide what happens when someone taps a button or the message itself. For deep links, the SDK opens the link automatically. For other interactions—like showing a settings page—you can listen for action events and run your own code. ### 1\. Compose a message with a custom action[](#1-compose-a-message-with-a-custom-action) In Customer.io, add an action to your in-app message, choose **Custom Action**, and set the action *Name* and *Value*. The *Name* maps to `actionName`; the *Value* maps to `actionValue` in your callback. [![Set up a custom in-app action](https://customer.io/images/in-app-custom-action.png)](#1005ee0b179f3999e81398a57e369557-lightbox) ### 2\. Listen for events[](#2-listen-for-events) You have two ways to detect clicks in inline messages. 1. **Callback on the widget** – Pass `onActionClick` (shown above) to handle actions for that specific inline view. 2. **Global listener** – Subscribe to `CustomerIO.inAppMessaging.subscribeToEventsListener` to handle inline **and** modal message events in one place. ```dart final subscription = CustomerIO.inAppMessaging.subscribeToEventsListener( (InAppEvent event) { if (event.eventType == EventType.messageActionTaken) { // Perform your logic here. debugPrint('Action taken: ${event.actionName} / ${event.actionValue}'); } }, ); // Later, when you no longer need events subscription.cancel(); ``` ## Handle responses to messages (event listeners)[](#event-listeners) Just like modal messages, inline messages emit events you can react to: * `messageShown` – The message appeared. * `errorWithMessage` – We encountered an error rendering the message. * `messageActionTaken` – Someone tapped an action. This only triggers if the inline view does **not** have an `onActionClick` callback. Inline messages have no *dismiss* concept, so there is no `messageDismissed` event. --- ## Push notifications > App groups **Source:** /integrations/sdk/flutter/push-notifications/app-groups # App Groups for push tracking You need App Groups for reliable push delivery tracking on iOS. Without this setup, delivery metrics may be lost if iOS terminates the Notification Service Extension before the tracking request completes. With App Groups configured, the SDK automatically recovers any lost metrics on the next app launch. ## Before you begin[](#before-you-begin) Before you configure App Groups, make sure you’ve completed the following: * [Set up push notifications](/integrations/sdk/flutter/push-notifications/push-setup/) in your app, including the Notification Service Extension (NSE) ## 1\. Add the App Group capability in Xcode[](#1-add-the-app-group-capability-in-xcode) You need to add the App Groups capability to both your main app target and your Notification Service Extension target in Xcode. Automatic signing #### Automatic signing[](#Automatic signing) If you use automatic signing (the most common setup), this is the only step outside of code. Xcode registers the group and updates provisioning profiles automatically. 1. In Xcode, select your **main app target** > **Signing & Capabilities** > **\+ Capability** > **App Groups**. 2. Click **+** and enter your group identifier—for example, `group.com.example.myapp.cio`. 3. Select your **Notification Service Extension target** > **Signing & Capabilities** > **\+ Capability** > **App Groups**. 4. Select the **same** App Group you created in step 2. Both targets must reference the exact same App Group string. Manual signing #### Manual signing[](#Manual signing) If you use manual signing, you need to register the group in the Apple Developer Portal and regenerate your provisioning profiles. 1. Sign in to the [Apple Developer Portal](https://developer.apple.com/) and go to **Certificates, Identifiers & Profiles**. 2. Click **Identifiers** > **+** > **App Groups**. 3. Enter your identifier. It must start with `group.`—for example, `group.com.example.myapp.cio`. 4. Under **Identifiers**, select your main app’s App ID, enable **App Groups**, click **Configure**, and select your group. 5. Repeat step 4 for your Notification Service Extension’s App ID. 6. Regenerate provisioning profiles for both your main app and Notification Service Extension. Enabling App Groups invalidates your existing provisioning profiles.  **You must regenerate your provisioning profiles** in the Apple Developer Portal after enabling App Groups. You don’t need to regenerate certificates.  Already have an App Group? You can reuse an existing App Group by passing its identifier to `.appGroupId()`. There’s no conflict in having multiple App Groups on a target. ## 2\. Pass the App Group ID in your SDK configuration[](#2-pass-the-app-group-id-in-your-sdk-configuration) After you add the App Group capability, pass the App Group ID to the SDK in both your host app and your Notification Service Extension. Both are required—App Groups work by sharing storage between the two targets, so the SDK needs the identifier in each place to read and write delivery metrics. The App Group ID must be identical in both places and must match the entitlements you set up in Xcode.  The `.appGroupId()` method is configured in native Swift code, not in Dart. The Notification Service Extension runs as a separate iOS process outside the Flutter runtime. ### Host app initialization[](#host-app-initialization) In your `AppDelegate.swift` file, add `.appGroupId()` to the `MessagingPushFCM.initialize` call: ```swift MessagingPushFCM.initialize( withConfig: MessagingPushConfigBuilder() .appGroupId("group.com.example.myapp.cio") .build() ) ``` ### Notification service extension initialization[](#notification-service-extension-initialization) In your `NotificationService.swift` file, add `.appGroupId()` to the `MessagingPushFCM.initializeForExtension` call: ```swift MessagingPushFCM.initializeForExtension( withConfig: MessagingPushConfigBuilder(cdpApiKey: "YOUR_CDP_API_KEY") .appGroupId("group.com.example.myapp.cio") .build() ) ```  App Group ID must match everywhere The `.appGroupId()` value must be identical in your host app initialization, your NSE initialization, and the App Group entitlements on both targets. A mismatch prevents the SDK from accessing shared storage. ### Fallback behavior[](#fallback-behavior) If you omit `.appGroupId(...)`, the SDK attempts to infer the identifier using `group.{bundleId}.cio`. This can work as a fallback, but we recommend explicitly passing the value to avoid configuration issues. --- ## Push notifications > Deep links **Source:** /integrations/sdk/flutter/push-notifications/deep-links # Deep links ## How it works[](#how-it-works) Deep links are the links that directs users to a specific location within a mobile app. When you set up your notification, you can set a “deep link.” When your audience taps the notification, the SDK will route users to the right place. Deep links help make your message meaningful, with a call to action that makes it easier, and more likely, for your audience to follow. For example, if you send a push notification about a sale, you can send a deep link that takes your audience directly to the sale page in your app. However, to make deep links work, you’ll have to handle them in your app. We’ve provided instructions below to handle deep links in both Android and iOS versions of your app. ## Android: Set up deep links[](#deep-links-android) Deep links provide a way to link to a screen in your app. You’ll set up deep links by adding [intent filters](https://developer.android.com/training/app-links/deep-linking) to the `AndroidManifest.xml` file. Visit Flutter’s documentation for more info on [deep linking](https://docs.flutter.dev/development/ui/navigation/deep-linking). ```xml ``` After you set up intent filters, you can test your implementation with the Rich Push editor or the payloads included for [Testing push notifications](/integrations/sdk/flutter/push-notifications/push/#rich-push-payloads). ### Push Click Behavior (Android)[](#push-click-behavior) When you initialize the SDK, you can set a `pushConfig` that controls how your app behaves when your audience taps push notifications on Android devices. The SDK automatically tracks `Opened` metrics for all options. ```dart CustomerIO.initialize( config: CustomerIOConfig( // other config options pushConfig: PushConfig( android: PushConfigAndroid( pushClickBehavior: PushClickBehaviorAndroid.activityPreventRestart, ), ), ), ); ``` The available options are: * `activityPreventRestart` **(Default)**: If your app is already in the foreground, the SDK will not re-create your app when your audience clicks a push notification. Instead, the SDK will reuse the existing activity. If your app *is not* in the foreground, we’ll launch a new instance of your deep-linked activity. We recommend that you use this setting if your app has screens that your audience shouldn’t navigate away from—like a shopping cart screen. * `activityNoFlags`: If your app is in the foreground, the SDK will re-create your app when your audience clicks a notification. The activity is added on top of the app’s existing navigation stack, so if your audience tries to go back, they will go back to where they previously were. * `resetTaskStack`: No matter what state your app is in (foreground, background, killed), the SDK will re-create your app when your audience clicks a push notification. Whether your app is in the foreground or background, the state of your app will be killed so your audience cannot go back to the previous screen if they press the back button. ## iOS: Set up deep links[](#deep-links-ios) Deep links let you open a specific page in your app instead of opening the device’s web browser. Want to open a screen in your app or perform an action when a push notification or in-app button is clicked? Deep links work great for this! Setup deep linking in your app. There are two ways to do this; you can do both if you want. * **Universal Links**: universal links let you open your mobile app instead of a web browser when someone interacts with a *URL on your website*. For example: `https://your-social-media-app.com/profile?username=dana`—notice how this URL is the same format as a webpage. * **App scheme**: app scheme deep links are quick and easy to setup. Example of an app scheme deep link: `your-social-media-app://profile?username=dana`. Notice how this URL is *not* a URL that could show a webpage if your mobile app is not installed. Universal Links provide a fallback for links if your audience doesn’t have your app installed, but they take longer to set up than *App Scheme* deep links. App Scheme links are easier to set up but won’t work if your audience doesn’t have your app installed. ### Setup App Scheme deep links[](#app-scheme-deep-links) Before you can follow this process, you need to set up your app link scheme for iOS. [Learn more about URL schemes for iOS apps](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app). 1. Open your project in Xcode and select your root project in the Project Navigator. 2. Go to the **Info** tab. 3. Scroll down to the options in the *Info* tab and expand **URL Types**. 4. Click to add a new, untitled schema. 5. Under **Identifier** and **URL Schemes**, add the name of your schema. [![set up your deep link scheme in xcode](https://customer.io/images/xcode-deep-link-schema-flutter.png)](#fd2f0018542c29dad2ce3be59ca41b65-lightbox) ### Set up Universal Links[](#universal-links-deep-links) Follow [Flutter’s documentation](https://docs.flutter.dev/development/ui/navigation/deep-linking) to implement Universal Links in your app. --- ## Push notifications > Multiple push providers **Source:** /integrations/sdk/flutter/push-notifications/multiple-push-providers # Handling multiple push providers ## How to handle multiple push providers[](#how-to-handle-multiple-push-providers) If you use another push service alongside our SDK (like `FlutterFire`), then that other service takes over push handling by default and prevents your app from receiving rich push notifications from Customer.io. There are two ways to solve this problem, but we typically recommend [the first option](#cio-process-notification-payloads), because it’s more flexible and lets you process notifications through another service. The second option causes our SDK to take over push handling entirely. ## Option 1 (Recommended): Let Customer.io process notification payloads[](#cio-process-notification-payloads) You can pass the payloads of other message services to Customer.io whenever a device receives a notification, so our SDK can process it for you. The SDK exposes the `onMessageReceived` and `onBackgroundMessageReceived` methods for this purpose. A `true` value (the default) means that the Customer.io SDK will generate the notification and track associated metrics. A `false` value means that the SDK will only process the notification to track metrics but *will not* generate a notification on the device. App in foreground #### App in foreground[](#App in foreground) ```dart CustomerIO.messagingPush().onMessageReceived(payload).then((handled) { // handled is true if notification was handled by Customer.io SDK; false otherwise return handled; }); ``` App in background #### App in background[](#App in background) ```dart CustomerIO.messagingPush().onBackgroundMessageReceived(payload).then((handled) { // handled is true if notification was handled by Customer.io SDK; false otherwise return handled; }); ``` Imagine that you use FlutterFire (Firebase for Flutter) alongside our SDK. You might use the `onMessageReceived` and `onBackgroundMessageReceived` methods to [handle notifications](https://firebase.google.com/docs/cloud-messaging/flutter/receive#message_handling) like this: FlutterFire foreground example #### FlutterFire foreground example[](#FlutterFire foreground example) ```dart FirebaseMessaging.onMessage.listen((RemoteMessage message) { CustomerIO.messagingPush().onMessageReceived(message.toMap()).then((handled) { // handled is true if notification was handled by Customer.io SDK; false otherwise return handled; }); }); ``` FlutterFire background example #### FlutterFire background example[](#FlutterFire background example) ```dart // Annotation is required only for Flutter version 3.3.0 or higher (to prevent removal during tree shaking in release mode) @pragma('vm:entry-point') Future _firebaseMessagingBackgroundHandler(RemoteMessage message) async { await Firebase.initializeApp(); CustomerIO.messagingPush().onBackgroundMessageReceived(message.toMap()).then((handled) { // handled is true if notification was handled by Customer.io SDK; false otherwise return handled; }); } void main() async { // Initialize required SDKs FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler); // Run the app } ``` ## Option 2: Register Customer.io Messaging Service[](#register-messaging-service) If you add another push service along with our SDK, like FlutterFire (Firebase for Flutter), it will take over push notification handling and prevent your app from receiving rich push notifications from Customer.io. To fix this issue, you need to add the following code under the `` tag in the `Manifest.xml` file in your app’s `Android` folder. ```xml ```  This method causes the Customer.io SDK to handle all your push notifications If you use the code above: * Your app will receive all simple and rich push notifications from Customer.io. * When your app is in the background, it can receive push notifications with a `notification` payload from other services. * Your app **cannot receive** `data`\-only push notifications from another service. --- ## Push notifications > Push metrics **Source:** /integrations/sdk/flutter/push-notifications/push-metrics # Capture push metrics If you’ve already set up rich push capabilities with the Flutter SDK, you’re ready to go. For more advanced use cases, see this document. ## Automatic push handling[](#automatic-push-handling) Customer.io supports device-side metrics that help you determine the efficacy of your push notifications: `delivered` when a push notification is received by the app and `opened` when a push notification is clicked. The SDK automatically tracks `opened` and `delivered` events for push notifications originating from Customer.io after you configure your app to receive [push notifications](/integrations/sdk/flutter/push-notifications/push/#register-push). You don’t have to add any code to track `opened` push metrics or launch deep links.  Improve delivery metric reliability Configure [App Groups](/integrations/sdk/flutter/push-notifications/app-groups/) to make sure delivery metrics aren’t lost when iOS terminates the Notification Service Extension before the tracking request completes. With App Groups, the SDK automatically recovers any undelivered metrics on the next app launch.  Do you use multiple push services in your app? The Customer.io SDK only handles push notifications that originate from Customer.io. Push notifications that were sent from other push services or displayed locally on device are not handled by the Customer.io SDK. You must add custom handling logic to your app to handle those push events. Read the sections below to see how you can add (optional) custom handling to various push events. #### Choose whether to show push while your app is in the foreground[](#show-push-app-foreground) If your app is in the foreground and the device receives a Customer.io push notification, your app gets to choose whether or not to display the push. To configure this behavior, add the following highlighted line of code in your `AppDelegate.swift` file: ```swift func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil ) -> Bool { ... MessagingPushFCM.initialize( withConfig: MessagingPushConfigBuilder() .showPushAppInForeground(true) // `true` will display the push when app in foreground .build() ) return super.application(application, didFinishLaunchingWithOptions: launchOptions) } ``` If the push did not come from Customer.io, you’ll need to [perform custom handling](#handle-push-received-foreground) to determine whether to display the push or not. #### Custom handling when users click a push[](#handle-push-click) You might need to perform custom handling when a user clicks a push notification—like when you want to process custom fields in your push notification payload. For now, the Flutter SDK does not provide callbacks when your audience clicks a push notification. But you can use one of the many popular Flutter push notification SDKs to receive a callback. For example, the code below receives callbacks when users click a push using FlutterFire. Be sure to follow the documentation for the push notification SDK you choose to use to receive callbacks with. ```dart import 'package:firebase_core/firebase_core.dart'; import 'package:firebase_messaging/firebase_messaging.dart'; FirebaseMessaging.instance.getInitialMessage().then((initialMessage) { // Handle push notification that was clicked, when app was in the killed state }); FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) { // Handle push notification that was clicked, when app was in the background state }); ```  Do you use deep links? If you’re performing custom push click handling on push notifications originating from Customer.io, we recommend that you don’t launch a deep link URL yourself. Instead, let our SDK launch deep links to avoid unexpected behaviors. #### Custom handling when getting a push while the app is foregrounded[](#handle-push-received-foreground) If your app is in the foreground and you get a push notification, your app gets to choose whether or not to display the push. For push notifications originating from Customer.io, [your SDK configuration determines if you show the notification](#show-push-app-foreground). But you can add custom logic to your app when this kind of thing happens. For now, the Flutter SDK does not provide callbacks when a push notification is received and your app is in the foreground. But you can use one of the many popular Flutter push notification SDKs to receive a callback. For example, the code below receives a callback using FlutterFire. Be sure to follow the documentation for the push notification SDK you choose to use to receive callbacks with. ```dart import 'package:firebase_core/firebase_core.dart'; import 'package:firebase_messaging/firebase_messaging.dart'; FirebaseMessaging.onMessage.listen((RemoteMessage message) { // Handle push notification received while app in foreground }); ``` ## Manually track push metrics[](#manual-push-metrics) You can manually parse a push notification payload and send `opened` or `delivered` events to the SDK: ```dart // extracted from payload received in the push notification. const deliveryID = '123'; // extracted from payload received in the push notification const deviceToken = 'abc'; // or MetricEvent.delivered const event = MetricEvent.opened; CustomerIO.instance.trackMetric( deliveryID: deliveryID, deviceToken: deviceToken, event: event); ``` --- ## Push notifications > Push notification channel **Source:** /integrations/sdk/flutter/push-notifications/push-notification-channel # Android push notification channels 🎉New in v2.4.0 Starting in Android 8.0, you can set up “notification channels,” which categorize notifications for your Android app. Every notification now belongs to a channel and the channel determines the behavior of notifications—whether they play sounds, appear as heads-up notifications, and so on. Channels also give users control over which channels they want to see notifications from. For example, if you had a news app, you might have different channels for sports, entertainment, and breaking news, giving users the ability to pick the channels they care about. Today, Customer.io supports **a single channel per app**, and it has three settings, listed in the table below. You can customize your channel when you first set up the Customer.io SDK, but you cannot change the channel ID or importance level after you’ve created a channel. You can only change the channel name. [Learn more from the official Android developer docs](https://developer.android.com/develop/ui/views/notifications/channels). Channels are created on the audience’s side when they receive their first push from Customer.io. Users can see your channel in their device settings. Channel setting Default Description Channel ID `[your package name]` The ID of the channel. Channel name `[your app name] Notifications` The name of the channel. Importance `3` The importance of the channel. Acceptable values are `0` (min), `1` (low), `2` (medium), `3` (default/high), and `4` (urgent). See [the Android developer documentation](https://developer.android.com/develop/ui/views/notifications/channels#importance) for more about the behavior of each importance level. ## Channel configuration[](#channel-configuration) When you first integrate with the Customer.io SDK, you can set up your Android channel. Remember, after you’ve released a version of your app with channel settings, you can only change the channel name. Changes to other settings have no effect. You’ll customize your channel in your app’s manifest. ```xml ``` ### What channel settings can I change?[](#what-channel-settings-can-i-change) When you first set up the Customer.io Flutter SDK, you can customize your channel. But after you release a version of your app with the Customer.io SDK, you cannot change the channel ID or importance level. After that, you can only change the channel name. (This is a limitation imposed by Android, not Customer.io.) If you released your app with a version of the Customer.io Flutter SDK prior to 2.4.0, you can delete your old channel and create a new one with completely new settings per [Android’s developer documentation](https://developer.android.com/develop/ui/views/notifications/channels#DeleteChannel). The chart below shows what channel settings you can or can’t change: ## Delete a channel[](#delete-a-channel) If you’ve released a version of your app with the Customer.io SDK earlier than v2.4.0, you can delete your old channel and create a new one with completely new settings per [Android’s developer documentation](https://developer.android.com/develop/ui/views/notifications/channels#DeleteChannel). ```kotlin val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager val id: String = context.packageName notificationManager.deleteNotificationChannel(id) ``` --- ## Push notifications > Push setup **Source:** /integrations/sdk/flutter/push-notifications/push-setup # Set up push notifications Our Flutter SDK supports push notifications over FCM—including rich push messages with links and images. This page helps you add push support to your app. ## How it works[](#how-it-works) If you’ve followed our [getting started instructions](/integrations/sdk/flutter/getting-started/#install), you’re already set up to send push notifications to your Android audience. But you’ll need to add a bit of code to support your iOS users. Remember that a device/user can’t receive a push notification until you: 1. (iOS) Register a device token for the device; code samples on this page help you do that. 2. [Identify a person](/integrations/sdk/flutter/identify/). This associates a token with the person; you can’t send push notifications to a device until you identify the recipient. 3. (Both iOS and Android) Check for notification permissions. If your app user doesn’t grant permission, notifications will not appear in the system tray. 4. (Optional) Set up your app to report push metrics back to Customer.io.  Did you already set up your push providers? To send, test, and receive push notifications, you’ll need to set up your push notification service(s) in Customer.io. If you haven’t already, set up [Firebase Cloud Messaging (FCM)](/push-getting-started/#for-android). ## Set up push for Android[](#register-push-android) If you followed our [Getting Started instructions](/integrations/sdk/flutter/getting-started/), you’re already set up to send push notifications to Android devices. You just need to [set up iOS push support](#register-push) in your app. Next, you can set up [deep links](/integrations/sdk/flutter/push-notifications/deep-links/#deep-links-android) if you want your notifications to link into your app. ### Set or change your push icon[](#set-or-change-your-push-icon) You’ll set the icon that appears on push notifications as a part of the `AndroidManifest.xml` file in your app’s `android` folder. If your icon appears in the wrong size, or if you want to change the standard icon that appears with your push notifications, you’ll need to update your app’s manifest. ```xml ``` ## Set up push for iOS[](#register-push) You’ll need to add some additional code to support push notifications for iOS. You’ll need to add push capabilities in XCode and integrate push capabilities in your app. ### Add push capabilities in Xcode[](#add-push-capabilities-in-xcode) Before you can work with push notifications, you need to add Push Notification capabilities to your project in XCode. 1. In your Flutter project, go to the `ios` subfolder and open `.xcworkspace`. 2. Select your project. Under *Targets*, select your main app. 3. Click the **Signing & Capabilities** tab and click **Capability**. 4. Add **Push Notifications** to your app. [![add push notification capabilities to your app](https://customer.io/images/react-native-xcode-push.png)](#b837646bba75943a4f08d0fee059210c-lightbox) 5. Select **File** > **New** > **Target**. [![xcode-servicenotification1.png](https://customer.io/images/xcode-servicenotification1.png)](#64d64173bde7b46bad5fc1f14cc8f36a-lightbox) 6. Select *Notification Service Extension* and click *Next*. [![xcode-servicenotification2.png](https://customer.io/images/xcode-servicenotification2.png)](#6413f7694da0358105aca5a02cf835dc-lightbox) 7. You should see a window such as this: [![xcode-servicenotification3.png](https://customer.io/images/xcode-servicenotification3.png)](#97f7eea0f5f268a29a24b1bdea3c767c-lightbox) You can leave many of the options in this window as their defaults, but you should: * Enter a product name, like *NotificationServiceExtension* (which we use in our examples on this page) * Confirm that your main app is selected in the *Embed in Application* drop-down menu When you’re done, click **Finish**. 8. When presented with the dialog below, click **Cancel**. This will help Xcode continue debugging your app and not just the extension you just added. [![xcode-servicenotification4.png](https://customer.io/images/xcode-servicenotification4.png)](#7a87192ad7f0dc9047625d6dfc407e77-lightbox) Now you have another target in your project navigator named `NotificationServiceExtension`. We’ll configure this extension when we [Integrate Push Notifications](#swift-push) in the following section. ### Integrate push capabilities in your app[](#swift-push) #### Install dependencies[](#install-dependencies) You can install iOS dependencies using CocoaPods or Swift Package Manager (SPM).  Switching to SPM? If you’re migrating from CocoaPods to SPM, see [Upgrade from 3.x to 4.0.0](/integrations/sdk/flutter/whats-new/4.0.0-upgrade/) for step-by-step instructions. CocoaPods #### CocoaPods[](#CocoaPods) If you previously enabled SPM, make sure it’s disabled by running `flutter config --no-enable-swift-package-manager`. 1. Open the file `ios/Podfile` and make the following modifications: ```ruby target 'Runner' do # Look for the main app target. # Required by FCM push notification service use_frameworks! # Make all file modifications after these lines: config = use_native_modules! # Add the following line to add the Customer.io native dependency: pod 'customer_io/fcm', :path => '.symlinks/plugins/customer_io/ios end # Next, copy and paste the code below to the bottom of your Podfile: target 'NotificationServiceExtension' do pod 'customer_io_richpush/fcm', :path => '.symlinks/plugins/customer_io/ios' end ``` 2. Run `pod install --repo-update --project-directory=ios` from the root directory of your Flutter project. When dependencies finish installing, you should see a message like this: ```fallback Pod installation complete! There are X dependencies from the Podfile and Y total pods installed. ``` Swift Package Manager (SPM) #### Swift Package Manager (SPM)[](#Swift Package Manager \(SPM\)) Before you start, make sure you meet the following requirements: * Flutter 3.24+ * Xcode 16.0+ * `firebase_core: ^3.5.0` and `firebase_messaging: ^15.2.0` or higher (older versions don’t support SPM). We recommend at least `firebase_core: ^4.6.0` and `firebase_messaging: ^16.1.3`. 1. **Enable SPM (if not already enabled).** Run `flutter config --enable-swift-package-manager`, and then run `flutter pub get`. The Customer.io SDK is automatically resolved - no manual Xcode setup needed for the main app. 2. **Update your Podfile.** Remove any `customer_io` pod lines and the `NotificationServiceExtension` target block from your `ios/Podfile`: ```ruby pod 'customer_io/fcm', :path => ... pod 'customer_io/location', :path => ... pod 'customer_io_richpush/fcm', :path => ... ``` With SPM enabled, Flutter’s pod helper automatically skips SPM-handled plugins. 3. **Set up Rich Push (NSE).** 1. Open `ios/Runner.xcworkspace` in Xcode. 2. Select the **NotificationServiceExtension** target. 3. Go to **General** > **Frameworks and Libraries** > click **+** and add **FlutterGeneratedPluginSwiftPackage** if it isn’t already added. [![Add FlutterGeneratedPluginSwiftPackage to the NotificationServiceExtension target](https://customer.io/images/xcode-nse-spm-framework.png)](#63f96c00dae3d457f55911fae69d4722-lightbox) The plugin automatically includes the following modules via SPM: Module Purpose DataPipelines Core SDK MessagingInApp In-app messaging MessagingPushFCM Push notifications and Firebase integration The Location module is not included by default. To include it, set `customerio_location_enabled=true` in your `android/gradle.properties` file. This flag controls both Android and iOS. See [Location tracking](/integrations/sdk/flutter/tracking/location/) for details. #### Configure your app[](#configure-your-app) 1. Update your `AppDelegate.swift` file to handle push notifications: ```swift import UIKit import Flutter import CioMessagingPushFCM import CioFirebaseWrapper import FirebaseMessaging import FirebaseCore @main class AppDelegateWithCioIntegration: CioAppDelegateWrapper {} class AppDelegate: FlutterAppDelegate { override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { GeneratedPluginRegistrant.register(with: self) // Depending on how you install Firebase, // you may need to add functions to this file, like: // FirebaseApp.configure() // // Read the official Firebase docs to install Firebase correctly! MessagingPushFCM.initialize( withConfig: MessagingPushConfigBuilder() // .appGroupId("group.com.example.myapp.cio") // Optional: for reliable delivery tracking .build() ) // Add line below only if you want to have custom control over notifications being presented and processed - Customer.io will handle those automatically UNUserNotificationCenter.current().delegate = self as UNUserNotificationCenterDelegate return super.application(application, didFinishLaunchingWithOptions: launchOptions) } override func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { super.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken) Messaging.messaging().apnsToken = deviceToken } } ``` 2. Open your `NotificationService.swift` file in Xcode and modify it with the highlighted changes below: ```swift import CioMessagingPushFCM import UserNotifications // Required when using SPM class NotificationService: UNNotificationServiceExtension { override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) { MessagingPushFCM.initializeForExtension( withConfig: MessagingPushConfigBuilder(cdpApiKey: "YourCdpApiKey") // Optional: set your Customer.io account region (.US or .EU). Default: US .region(.US) // .appGroupId("group.com.example.myapp.cio") // Optional: for reliable delivery tracking .build() ) MessagingPush.shared.didReceive(request, withContentHandler: contentHandler) } override func serviceExtensionTimeWillExpire() { MessagingPush.shared.serviceExtensionTimeWillExpire() } } ```  `import UserNotifications` is required when using SPM. CocoaPods transitively imports system frameworks, so the import isn’t required with CocoaPods, but it doesn’t hurt to include it. Now you can run your app on a physical device and send yourself push notifications with images and deep links to test your implementation. You’ll have to use a physical device because emulators can’t receive push notifications. ### Sound in push notifications (iOS Only)[](#sound-in-push-notifications) When you send a push notification to iOS devices that uses our SDK, you can opt to send the *Default* system sound or no sound at all. If your audience’s phone is set to vibrate, or they’ve disabled sound permissions for your app, the *Default* setting will cause the device to vibrate rather than playing a sound. In most cases, you should use the *Default* sound setting to make sure your audience hears (or feels) your message. But, before you send sound, you should understand: 1. Your app needs permission from your users to play sounds. This is done by your app, not our SDKs. [Here’s an example from our iOS sample app](https://github.com/customerio/customerio-ios/blob/main/Apps/APN-UIKit/APN%20UIKit/Util/NotificationUtil.swift#L12-L13) showing how to request sound permissions. 2. iOS users can go into *System Settings* and disable sound permissions for your app. Enabling the *Default* setting doesn’t guarantee that your audience hears a sound when your message is delivered!  We don’t support custom sounds yet If you want to send a custom sound, you’ll need to handle it on your own, outside the SDK and use a custom payload when you set up your push notifications. ## Display push notifications in the foreground (iOS)[](#ios-foreground-notifications) By default, iOS doesn’t display push notifications when your app is in the foreground. The `showPushAppInForeground` configuration flag (set to `true` by default) tells iOS to display notifications even when your app is active. ```swift MessagingPushFCM.initialize( withConfig: MessagingPushConfigBuilder() .showPushAppInForeground(true) .build() ) ```  For more information about handling push notifications in the foreground, including custom handling for non-Customer.io push notifications, see [push metrics and custom handling](/integrations/sdk/flutter/push-notifications/push-metrics/#show-push-app-foreground). ### Implement the notification center delegate for more control[](#implement-the-notification-center-delegate-for-more-control) For more granular control over foreground notification behavior, you can implement the `userNotificationCenter(_:willPresent:withCompletionHandler:)` method in your `AppDelegate.swift` file. This native implementation takes precedence over the `showPushAppInForeground` configuration flag. This method lets you inspect the notification content and decide whether to display it, and choose which presentation options to use (banner, list, badge, sound, or any combination). Add this method to the `AppDelegate` class you set up in the [integration step](#swift-push) above: ```swift override func userNotificationCenter( _ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void ) { // Show notifications in foreground with banner, list, badge, and sound completionHandler([.banner, .list, .badge, .sound]) // Or return empty array if you do NOT want notifications shown in foreground // completionHandler([]) } ``` ## Test your implementation[](#rich-push-payloads) After you set up rich push, you should test your implementation. Below, we show the payload structure we use for iOS and Android. In general, you can use our regular rich push editor; it’s set up to send messages using the JSON structure we outline below. If you want to fashion your own payload, you can use our [custom payload](/journeys/push-custom-payloads/#getting-started-with-custom-payloads). [![the rich push editor](https://customer.io/images/push-preview.png)](#4e089ac68a22d5b994db09266a531737-lightbox) iOS FCM payload #### iOS FCM payload[](#iOS FCM payload) ```json { "message": { "apns": { "payload": { "aps": { // basic iOS message and options go here "mutable-content": 1, "alert": { "title": "string", //(optional) The title of the notification. "body": "string" //(optional) The message you want to send. } }, "CIO": { "push": { "link": "string", //generally a deep link, i.e. my-app://... or https://yourwebsite.com/... "image": "string" //HTTPS URL of your image, including file extension } } }, "headers": { // (optional) headers to send to the Apple Push Notification Service. "apns-priority": 10 } } } } ``` * message object Required The base object for all FCM payloads. * apns object Required Defines a payload for iOS devices sent through Firebase Cloud Messaging (FCM). * headers object Headers defined by [Apple’s payload reference](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns) that you want to pass through FCM. * payload object Required Contains a push payload. * CIO object Contains properties interpreted by the Customer.io iOS SDK. * push object Required A push payload for the iOS SDK. * *Custom key-value pairs\** any type Additional properties that you've set up your app to interpret outside of the Customer.io SDK. Android payload #### Android payload[](#Android payload) ```json { "message": { "data": { "title": "string", //(optional) The title of the notification. "body": "string", //The message you want to send. "image": "string", //https URL to an image you want to include in the notification "link": "string" //Deep link in the format remote-habits://deep?message=hello&message2=world } } } ``` * message Required The parent object for all push payloads. * android object Contains properties that are **not** interpreted by the SDK but are defined by FCM. You need to write your own code to handle these Android push features. * data object Required Contains all properties interpreted by the SDK. * android object Contains properties that are **not** interpreted by the SDK but are defined by FCM. You need to write your own code to handle these Android push features. * data object Contains the `link` property (interpreted by the SDK) and additional properties that you want to pass to your app. * notification object Required Contains properties interpreted by the SDK except for the `link`. ## Next steps[](#next-steps) After you set up push notifications, configure [App Groups](/integrations/sdk/flutter/push-notifications/app-groups/) for reliable delivery tracking on iOS. Without App Groups, iOS can end the Notification Service Extension before delivery metrics are sent, which means some data may never reach Customer.io. App Groups provide shared storage so the SDK can recover any lost metrics on the next app launch. --- ## Tracking > Anonymous activity **Source:** /integrations/sdk/flutter/tracking/anonymous-activity # Anonymous activity Before you identify a person, calls you make to the SDK are associated with an `anonymousId`. When you identify that person, we reconcile their anonymous activity with the identified person. In Customer.io, you’ll see anonymous activity in the *Activity Log*, but we don’t surface anonymous [profilesAn instance of a person. Generally, a person is synonymous with their profile; there should be a one-to-one relationship between a real person and their profile in Customer.io. You reference a person’s profile attributes in liquid using `customer`—e.g. `{{customer.email}}`.](/merge-people) in Customer.io. You won’t be able to find an “anonymous person” in your workspace, and an anonymous person can’t trigger campaigns or get messages (including push notifications) from Customer.io. When you identify a person, and we merge anonymous activity with the identified person, the previously-anonymous activity *can* trigger campaigns and cause your audience to receive messages. For example, imagine that you have an ecommerce app, and you want to message people who view a specific product. An anonymous user looks at the product in question, goes to a different page, and then logs into your app. When they log in, we merge their anonymous activity with their identified profile, and their previously-anonymous `screen` view triggers the campaign you set up for people who visited the product page. You can return a person’s anonymous ID at ay time by calling `CustomerIO.shared.anonymousId`. --- ## Tracking > Identify **Source:** /integrations/sdk/flutter/tracking/identify # Identify people Use `CustomerIO.identify()` to identify a person. You need to identify a mobile user before you can send them messages or track events for things they do in your app. This page is part of a setup flow for the SDK. Before you continue, make sure you've implemented previous features—i.e. you can't identify people before you initialize the SDK! ## Identify a person[](#identify) Identifying a person: 1. Adds or updates the person in your workspace. This is basically the same as an [`identify` call to our server-side API](/api/#operation/identify). 2. Saves the person’s information on the device. Future calls to the SDK reference the identified person. For example, after you identify a person, any events that you track are automatically associated with that person. 3. Associates the current device token with the the person. You can only identify one customer at a time. The SDK “remembers” the most recently-identified customer. If you identify person A, and then call the identify function for person B, the SDK “forgets” person A and assumes that person B is the current app user. You can also [stop identifying a person](#clearIdentify), which you might do when someone logs off or stops using your app for a significant period of time. An identify request takes two parameters: * **userId** (Required): The unique value representing a person—an ID, email address, or the [cio\_idAn identifier for a person that is automatically generated by Customer.io and cannot be changed. This identifier provides a complete, unbroken record of a person across changes to their other identifiers (id, email, etc).](/identifying-people/#cio_id) * **traits** (Optional): An object containing [attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages.](/journeys/attributes/) that you want to add to, or update on, a person ```dart CustomerIO.instance.identify(userId: email, traits: { "name": user.displayName, "email": user.email, "age": user.age, }); ``` ### Update a person’s attributes[](#update-person) You store information about a person in Customer.io as [attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages.](/journeys/attributes/). When you call the `identify()` function, you can update a person’s attributes in Customer.io. If you’ve already identified a person, and they update their preferences, provide additional information about themselves, or perform other attribute-changing actions, you can update their attributes with `profileAttributes`. You only need to pass the attributes that you want to create or modify to `setProfileAttributes`. For example, if you identify a new person with the attribute `{"first_name": "Dana"}`, and then you call `CustomerIO.instance.setProfileAttributes(traits: {"favorite_food": "pizza"});`, the person will gain the `favorite_food` attribute but `first_name` attribute will still be `Dana`. ```dart CustomerIO.instance.setProfileAttributes(traits: { "first_name": "Cool", "last_name": "User", "is_premium": false, }); ``` ### Device attributes[](#device-attributes) By default (if you don’t set `.autoTrackDeviceAttributes(false)` in your config), the SDK automatically collects a series of [attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages.](/journeys/attributes/) for each device. You can use these attributes in [segmentsA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions.](/journeys/data-driven-segments/) and other campaign workflow conditions to target the device owner, just like you would use a person’s other attributes. You cannot, however, use device attributes to personalize messages with [liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable `{{customer.first_name}}`.](/using-liquid) yet. Along with these attributes, we automatically set a `last_used` timestamp for each device indicating when the device owner was last identified, and the `last_status` of a push notification you sent to the device. You can also set your own custom device attributes. You’ll see a person’s devices and each device’s attributes when you go to **Journeys > People > Select a person**, and click **Devices**. [![device attributes on a person's profile](https://customer.io/images/device-attributes.png)](#db82cfb11dbec1c42a9f938183dcedbd-lightbox)  Your integration shows device attributes in the `context` object When you inspect calls from the SDK (in your integration’s data inAn integration that feeds data *into* Customer.io. tab), you’ll see device information in the `context` object. We flatten the device attributes that you send into your workspace, so that they’re easier to use in [segmentsA segment is a group of people in your workspace. Use segments to trigger campaigns, track membership over time, or fine-tune your audience. There are two types of segments: data-driven and manual. Data-driven segments automatically update when people start or stop matching criteria. Manual segments are static.](/journeys/segments/). For example, `context.network.cellular` becomes `network_cellular`. * id string Required The device token. #### Set custom device attributes[](#update-device) You can also set custom device attributes with the `setDeviceAttributes` method. You might do this to save app preferences, time zone, or other custom values specific to the device. Like profile attributes, you can pass nested JSON to device attributes. However, before you set custom device attributes, consider whether the attribute is specific to the `device` or if it applies to the person more broadly. Device tokens are ephemeral—they can change based on user behavior, like when a person uninstalls and reinstalls your app. If you want an attribute to persist beyond the life of the device, you should [apply it to the person](#update-person) rather than the device. ```dart const deviceAttributes = { "type" : "primary_device", "parentObject" : { "childProperty" : "someValue", }, }; CustomerIO.instance.setDeviceAttributes(attributes: deviceAttributes); ``` #### Disable automatic device attribute collection[](#disable-attributes) By default, the SDK automatically collects the device [attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages.](/journeys/attributes/) [defined above](#device-attributes). You can disable the `autoTrackDeviceAttributes` setting to prevent the SDK from automatically collecting these attributes. ```dart CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: '', autoTrackDeviceAttributes: false, inAppConfig: InAppConfig(siteId: ''), ), ); ``` #### Manually add device to profile[](#add-device) In the standard flow, identifying a person automatically associates the token with the identified person in your workspace. If you need to manually add or update the device elsewhere in your code, call `CustomerIO.instance.registerDeviceToken(token)`. ## Stop identifying a person[](#clearIdentify) When a person logs out, or does something else to tell you that they no longer want to be tracked, you should stop identifying them. Use `clearIdentify()` to stop identifying the previously identified person (if there was one). ```dart CustomerIO.instance.clearIdentify(); ``` ### Identify a different person[](#identify-a-different-person) If you want to identify a new person—like when someone switches profiles on a streaming app, etc—you can simply call `identify()` for the new person. The new person then becomes the currently-identified person, with whom all new information—messages, events, etc—is associated. ```dart CustomerIO.instance.identify(identifier: "new.person@example.com", attributes: {"first_name": "New", "last_name": "Person"}); ``` --- ## Tracking > Lifecycle events **Source:** /integrations/sdk/flutter/tracking/lifecycle-events # Mobile Lifecycle events By default, the Customer.io SDK automatically tracks lifecycle events for your users. These are events that represent the lifecycle of your app and your users’ experiences with it. By default, we track the following lifecycle events: * **Application Installed**: A user installed your app. * **Application Updated**: A user updated your app. * **Application Opened**: A user opened your app. * **Application Foregrounded**: A user switched back to your app. * **Application Backgrounded**: A user backgrounded your app or switched to another app. You might also want to send your own lifecycle events, like `Application Crashed` or `Application Updated`. You can do this using the `track` call. You’ll find a list of properties for these events—both the ones we track automatically and other events you might send yourself—in our [Mobile App Lifecycle Event specification](/integrations/api/cdp/#section/Semantic-events-for-data-out-integrations/mobile-application-lifecycle-event-schemas). ## Lifecycle event examples[](#lifecycle-event-examples) A lifecycle event is basically a `track` call that the SDK makes automatically for you. When you look at your data in Customer.io, you’ll see lifecycle events as `track` calls, where the event `properties` are specific to the name of the event. For example, the `Application Installed` event includes the app `version` and `build` properties. ```json { "userId": "app.installer@example.com", "type": "track", "event": "Application Installed", "properties": { "version": "3.2.1", "build": "247" } } ``` ## Sending custom lifecycle events[](#sending-custom-lifecycle-events) You can send your own lifecycle events using the `track` call. However, whenever you send lifecycle events, you should use the *Application EventName* convention that we use for our default lifecycle events. These [semantic event](/integrations/data-in/semantic-events/) names and properties represent [a standard](/integrations/data-in/semantic-events/mobile-app/) that we use across Customer.io and our downstream destinations. Adhering to this standard ensures that your events automatically map to the correct event types in Customer.io and any other services you send your data to. If you opt [out of automatic lifecycle events](#disable-lifecycle-events), you can send your own `track` calls for these events. Or, for events we can’t track automatically, you might be able to use a webhook or a callback to collect crash events. For example, you might want to send a `track` call for `Application Crashed` if your app crashes or `Application Updated` when people update your app. ```dart CustomerIO.instance.track( name: "Application Crashed", properties: [ "url": "urls://page/in/app" ] ) ``` ## Disable lifecycle events[](#disable-lifecycle-events) We track lifecycle events by default. You can disable this behavior by passing the `trackApplicationLifecycleEvents` option in your configuration. ```dart CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: '', region: Region.us, trackApplicationLifecycleEvents: false, inAppConfig: InAppConfig(siteId: ''), ), ); ``` --- ## Tracking > Location **Source:** /integrations/sdk/flutter/tracking/location # Location tracking ## How it works[](#how-it-works) The Location module captures location (with user consent) from your app and attaches it to a person’s profile in Customer.io. You can use this data for geo-aware messaging and audience segmentation with more accuracy than [IP-based geolocation](/journeys/geolocation/). When you identify a person, the SDK includes the latest location in the identify call. The SDK also sends a `Location Update` event to the person’s activity timeline, which you can use in journeys and segments. To balance location updates with battery and data usage, the SDK limits location updates once a day (at most)—and only sends that update when the person has moved a meaningful distance since the last update. The SDK does not request location permission on its own—your app must handle the permission flow. ## Install the location module[](#install) The Location module requires native dependencies on both iOS and Android. Follow the platform-specific steps below. 1. Add the following property to your project’s `android/gradle.properties` file: ```properties customerio_location_enabled=true ``` CocoaPods #### CocoaPods[](#CocoaPods) 2. Add the `location` subspec to your Podfile. Open `ios/Podfile` in your Flutter project and add the following line alongside your existing `customer_io` pod: ```ruby pod 'customer_io/location', :path => '.symlinks/plugins/customer_io/ios' ``` SPM #### SPM[](#SPM) No additional iOS setup is needed. The `customerio_location_enabled` flag you set in `gradle.properties` also controls whether the Location module is included via SPM on iOS. If the flag isn’t detected (e.g. in Flutter add-to-app modules or some CI environments), you can set the `CIO_LOCATION` environment variable instead: ```bash CIO_LOCATION=true flutter build ios ``` You can also set this in Android Studio under **Run** > **Edit Configurations** > **Environment variables**. ## Initialize the SDK with the location module[](#initialize-the-sdk-with-the-location-module) Add a `locationConfig` to your `CustomerIOConfig` to enable the module. The `trackingMode` property controls how and when the SDK captures location. Option Type Default Description `trackingMode` `LocationTrackingMode` `manual` Controls how and when the SDK captures location. See [tracking modes](#tracking-modes) below. ### Tracking modes[](#tracking-modes) Mode Description `LocationTrackingMode.manual` Your app controls when it captures location. Call `setLastKnownLocation()` or `requestLocationUpdate()` to provide location. Use this when your app already has a location-tracking mechanism or you want full control over when you capture location data. `LocationTrackingMode.onAppStart` The SDK automatically captures a one-shot location once per app launch when your app enters the foreground. You can still call `setLastKnownLocation()` or `requestLocationUpdate()` alongside automatic capture. Use this for hands-off location tracking with minimal battery impact. `LocationTrackingMode.off` Disables location tracking entirely. All location calls become silent and location is not included in identify calls. Use this if you want to register the module but disable it at runtime. ```dart CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: 'YOUR_CDP_API_KEY', // ...other config options locationConfig: LocationConfig( trackingMode: LocationTrackingMode.manual, ), ), ); ``` ## Location APIs[](#location-apis) The module provides two methods to capture location. You can call either method as often as you like; the SDK always caches the latest coordinates for profile enrichment, but sends a `Location Update` event no more than once a day—and only if the person has moved a meaningful distance since the last update. No matter how frequently you call these methods, the SDK throttles the updates for you so as not to overwhelm your workspace with profile updates. ### `setLastKnownLocation`[](#setlastknownlocation) Pass coordinates directly from your app’s own location system. This doesn’t require any location permissions from the SDK. Your app manages location access independently of Customer.io. Parameter Type Description `latitude` `double` Latitude in degrees. Must be between -90 and 90. `longitude` `double` Longitude in degrees. Must be between -180 and 180. ```dart // Pass coordinates from your app's location provider CustomerIO.location.setLastKnownLocation( latitude: 37.7749, longitude: -122.4194, ); ``` ### `requestLocationUpdate`[](#requestlocationupdate) Request a one-shot location from the native platform’s location services. Use this if your app doesn’t have its own location system. Your app must request location permission before calling this method—the SDK won’t prompt the user. If a user doesn’t grant permission or location services are disabled, the request is ignored—no crash or exception. If a request is already in progress, additional calls are ignored until the current request completes. 1. Add the required key to your `Info.plist`: ```xml NSLocationWhenInUseUsageDescription We use your location to personalize your experience. ``` 2. **(Optional)** If you want more precise location, add `ACCESS_FINE_LOCATION` to your `AndroidManifest.xml`. The SDK already includes `ACCESS_COARSE_LOCATION` when the location module is enabled. ```xml ``` 3. After your app requests and receives permission at runtime, call the SDK: ```dart // After location permission is granted CustomerIO.location.requestLocationUpdate(); ```  We recommend using a package like [geolocator](https://pub.dev/packages/geolocator) or [location](https://pub.dev/packages/location) to handle location permission requests in your Flutter app. ## Profile switch behavior[](#profile-switch-behavior) When you call `CustomerIO.instance.clearIdentify()`, the SDK clears cached location data so that one person’s location doesn’t carry over to another person’s profile. The next person you identify starts with a clean slate. Location persists across app restarts. When your app relaunches, the SDK restores the cached location so that the next `identify()` call includes it automatically. --- ## Tracking > Screen events **Source:** /integrations/sdk/flutter/tracking/screen-events # Screen tracking Screen views are events that record the pages that your audience visits in your app. They have a `type` property set to `screen`, and a `title` representing the title of the screen or page that a person visited in your app. Screen view events let you trigger [campaignsCampaigns are automated workflows you set up to send people messages and perform other actions when they meet your criteria.](/journeys/campaigns-in-customerio/) or add people to [segmentsA group of people who match a series of conditions. People enter and exit the segment automatically when they match or stop matching conditions.](/journeys/data-driven-segments/) based on the parts of your app your they use. Screen events also update your audience’s “Last Visited” attribute, which can help you track how recently people used your app. ## Enable automatic screen tracking[](#auto-screenview) We’ve provided some example code below using [Route observer](https://api.flutter.dev/flutter/widgets/RouteObserver-class.html) for automatic screen tracking. If you want to send more data with screen events, or you don’t want to send events for every individual screen that people view in your app, you [send screen events manually](#manual-screenview). ```dart class MyRouteObserver extends RouteObserver> { void _sendScreenView(PageRoute route) { var screenName = route.settings.name; // track screen manually CustomerIO.screen(name: screenName ?? "N/A"); } @override void didPush(Route route, Route? previousRoute) { super.didPush(route, previousRoute); if (route is PageRoute) { _sendScreenView(route); } } @override void didReplace({Route? newRoute, Route? oldRoute}) { super.didReplace(newRoute: newRoute, oldRoute: oldRoute); if (newRoute is PageRoute) { _sendScreenView(newRoute); } } @override void didPop(Route route, Route? previousRoute) { super.didPop(route, previousRoute); if (previousRoute is PageRoute && route is PageRoute) { _sendScreenView(previousRoute); } } } // Usage class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( theme: ThemeData(), navigatorObservers: [MyRouteObserver()], home: Screen1(), routes: { 'screen2': (context) => Screen2(), 'screen3': (context) => Screen3(), }, ); } } ``` ### Screenview settings for in-app messages[](#screenview-settings-for-in-app-messages) Customer.io uses `screen` events to determine where users are in your app so you can target them with in-app messages on specific screens. By default, the SDK sends `screen` events to Customer.io’s backend servers. But, if you don’t use `screen` events to track user activity, segment your audience, or to trigger campaigns, these events might constitute unnecessary traffic and event history. If you don’t use `screen` events for anything other than in-app notifications, you can set the `ScreenViewUse` parameter to `ScreenView.inApp`. This setting stops the SDK from sending `screen` events back to Customer.io but still allows the SDK to use `screen` events for in-app messages, so you can target in-app messages to the right screen(s) without sending event traffic into Customer.io! ```dart CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: "YOUR_CDP_API_KEY", // Required screenViewUse: ScreenView.inApp, ), ); ``` ## Send your own screen events[](#manual-screenview) Screen events use the `.screen` method. Like other event types, you can add a `properties` object containing additional information about the screen or the user. ```dart CustomerIO.instance.screen(title: "screen-name", properties: {"property": "value"}); ``` --- ## Tracking > Track events **Source:** /integrations/sdk/flutter/tracking/track-events # Track events Events are things people do in your app. They help you track your audience’s behaviors, activity, and metrics. You can use them to segment your audience, trigger messaging campaigns, and see how people use your app. ## Track an event[](#track-an-event) The `track` method helps you send events representing your audience’s activities to Customer.io. When you send events, you can include event `properties`—information about the person or the event that they performed. In Customer.io, you can use events to trigger campaigns and broadcasts. Those campaigns might send someone a push notification or manipulate information associated with the person in your workspace. Events include the following: * `name` (Required): The name of the event. Most event-based searches in Customer.io hinge on the name, so make sure that you provide an event name that will make sense to other members of your team. * `properties` (Optional): Additional information that you want to reference in messages or use to segment your audience, etc. You can reference event properties in messages and other campaign actionsA block in a campaign workflow—like a message, delay, or attribute change. using [liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable `{{customer.first_name}}`.](/using-liquid) in the format `{{event.}}`. ```dart CustomerIO.instance.track(name: "add-to-cart", properties: {"product": "shoes", "price": "29.99"}); ``` ### Anonymous activity[](#anonymous-activity) If you send a `track` call before you `identify` a person, we’ll attribute the event to an `anonymousId`. When you identify the person, we’ll reconcile their anonymous activity with the identified person. When we apply anonymous events to an identified person, the previously anonymous activity becomes eligible to trigger campaigns in Customer.io. ## Semantic Events[](#semantic-events) Some actions don’t map cleanly to our simple `identify`, `track`, and other calls. For these, we use “semantic events,” events that have a special meaning in Customer.io and your destinations. These are especially important in Customer.io for destructive operations like deleting a person. When you send an event with a semantic `event` name, we’ll perform the appropriate action. For example, if a person decides to leave your service, you might delete them from your workspace. In Customer.io, you’ll do that with a `Delete Person` event. ```dart CustomerIO.instance.track(name: "User Deleted) ``` --- ## Whats new > 2.2 upgrade **Source:** /integrations/sdk/flutter/whats-new/2.2-upgrade # 2.x -> 2.2 Version 2.2 of the Customer.io Flutter SDK introduces a new `CioAppDelegateWrapper` pattern for iOS that simplifies push notification setup and eliminates the need for method swizzling. ## Key Changes[](#key-changes) The primary change in version 2.2 is the introduction of the wrapper pattern for handling push notifications on iOS. This change: * **Eliminates method swizzling**: No more automatic method replacement * **Simplifies setup**: Less boilerplate code required * **Improves reliability**: More predictable behavior See the instructions below to update your Flutter app’s iOS configuration. ## Upgrading to SDK 2.2[](#upgrading-to-sdk-22) Update your dependencies: 1. Update your `pubspec.yaml` file: ```yaml dependencies: customer_io: ^2.2.0 ``` 2. Run dependency update: ```bash flutter pub get && cd ios && pod install --repo-update && cd .. ``` ## Update with FCM (Firebase Cloud Messaging)[](#update-appdelegate-fcm) Update your `AppDelegate.swift` file to use the new `CioAppDelegateWrapper` pattern. See the *Before* sample to see what needs to change and the *After* sample to see the new pattern. Before (2.x) #### Before (2.x)[](#Before \(2.x\)) ```swift import UIKit import Flutter import CioMessagingPushFCM import FirebaseMessaging import FirebaseCore @main @objc class AppDelegate: FlutterAppDelegate { override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { GeneratedPluginRegistrant.register(with: self) Messaging.messaging().delegate = self MessagingPushFCM.initialize( withConfig: MessagingPushConfigBuilder() .build() ) UNUserNotificationCenter.current().delegate = self as UNUserNotificationCenterDelegate return super.application(application, didFinishLaunchingWithOptions: launchOptions) } func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { Messaging.messaging().setAPNSToken(deviceToken, type: .unknown); } override func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) { MessagingPush.shared.application(application, didFailToRegisterForRemoteNotificationsWithError: error) } } extension AppDelegate: MessagingDelegate { func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) { MessagingPush.shared.messaging(messaging, didReceiveRegistrationToken: fcmToken) } } ``` After (2.2) #### After (2.2)[](#After \(2.2\)) ```swift import UIKit import Flutter import CioMessagingPushFCM import FirebaseMessaging import FirebaseCore @main class AppDelegateWithCioIntegration: CioAppDelegateWrapper {} class AppDelegate: FlutterAppDelegate { override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { GeneratedPluginRegistrant.register(with: self) // Initialize push with wrapper - handles all push methods automatically MessagingPushFCM.initialize( withConfig: MessagingPushConfigBuilder() .build() ) // Optional: Add only if you want custom control over notifications UNUserNotificationCenter.current().delegate = self as UNUserNotificationCenterDelegate return super.application(application, didFinishLaunchingWithOptions: launchOptions) } override func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { super.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken) Messaging.messaging().apnsToken = deviceToken } // No manual push methods needed - CioAppDelegateWrapper handles everything } ``` ## Configuration Options[](#configuration-options) You can customize the push behavior when you initialize your push package: ```swift MessagingPushFCM.initialize( withConfig: MessagingPushConfigBuilder() .showPushAppInForeground(true) // Show push when app is in foreground .autoTrackPushEvents(true) // Automatically track push metrics .build() ) ``` ## Important Notes[](#important-notes) 1. **Manual push handling methods are not required**: the `CioAppDelegateWrapper` automatically records information from following methods. But you can still use these methods if you want to add custom push handling: * `didRegisterForRemoteNotificationsWithDeviceToken` * `didFailToRegisterForRemoteNotificationsWithError` * All other push-related delegate methods 2. **The `@main` attribute** - Must be on the wrapper class, not your AppDelegate. 3. **Flutter-specific**: Your Flutter app’s main.dart file doesn’t need any changes. 4. **NotificationService.swift remains unchanged** - Your notification service extension configuration works the same with both approaches. ## Troubleshooting[](#troubleshooting) If push notifications stop working after you update your implementation: 1. Make sure that you’ve added the `@main` attribute to the wrapper class 2. Verify that you’ve removed `@main` from your original AppDelegate 3. Check that you’re calling `MessagingPushFCM.initialize()` 4. Run `flutter clean` followed by `pod install --repo-update --project-directory=ios` 5. Test on a physical device (push notifications don’t work on simulators) --- ## Whats new > 2.x upgrade **Source:** /integrations/sdk/flutter/whats-new/2.x-upgrade # Upgrade to Flutter 2.x This page provides steps to help you upgrade from our Flutter 1.x SDK so you understand the development effort required to update your app and take advantage of the latest features. ## What changed?[](#what-changed) This update provides native support for our new integrations framework. While this represents a significant change “under the hood,” we’ve tried to make it as seamless as possible for you; much of your implementation remains the same. This move also adds two additional features: * **You’ll use SDK methods from an `instance`**: * **Support for anonymous tracking**: you can send events and other activity for anonymous users, and we’ll reconcile that activity with a person when you identify them. * **Built-in lifecycle events**: the SDK now automatically captures events like “Application Installed” and “Application Updated” for you. * **New device-level data**: the SDK captures the device `name` and other device-level context for you. ## Upgrade process[](#upgrade-process) You’ll update initialization calls for the SDK itself and the push and/or in-app messaging modules. **As a part of this process, your credentials change**. You’ll need to set up a new data inAn integration that feeds data *into* Customer.io. integration in Customer.io and get a new *CDP API Key*. But you’ll *also* need to keep your previous `siteId` as a `migrationSiteId` when you initialize the SDK. The `migrationSiteId` is a key helps the SDK send remaining traffic when people update your app. When you’re done, you’ll also need to change a few base properties to fit the new APIs. In general, `identifier` becomes `userId`, `body` becomes `traits`, and `data` becomes `properties`. ### 1\. Get your new *CDP API Key*[](#1-get-your-new-cdp-api-key) The new version of the SDK requires you to set up a new data inAn integration that feeds data *into* Customer.io. integration in Customer.io. As a part of this process, you’ll get your *CDP API Key*. 1. Go to [*Data & Integrations* > *Integrations*](https://fly.customer.io/workspaces/last/journeys/integrations/all/overview) and click **Add Integration**. 2. Select **Flutter**. [![set up your Flutter integration](https://customer.io/images/cdp-flutter-source.png)](#b313d06604f0b0ea2cab391b1806b3cd-lightbox) 3. Enter a *Name* for your integration, like “My Flutter App”. 4. We’ll present you with a code sample containing a `cdpApiKey` that you’ll use to initialize the SDK. Copy this key and keep it handy. 5. Test your connection and click **Complete Setup**. Or, if you don’t want to test your implementation yet, **Save & Complete Later** and then click **Install Source** to finish the setup process. In this case, *Complete Later* simply means that we haven’t seen any data from your Flutter app yet. [![Set your name, get your CDP API Key, and click Complete Setup](https://customer.io/images/cdp-flutter-source-setup.png)](#1d7ba11eb6f6a64e4b1e289803050598-lightbox) Remember, you can also [connect your Flutter app to services outside of Customer.io](/integrations/data-out/add-destination/)—like your analytics provider, data warehouse, or CRM. ### 2\. Update the SDK initialization[](#2-update-the-sdk-initialization) You’ll need to update the way you initialize the SDK—with a new key and configuration options for in-app and push. We show an example configuration below. You’ll find a complete list of configuration options on the [*Packages and Configuration Options* page](/integrations/sdk/flutter/getting-started/packages-options/), but you’ll want to pay close attention to the following changes: * You’ll initialize the SDK with a `cdpApiKey`. This is the key you’ll get when you create your Flutter integration in Customer.io. * `siteId` becomes `migrationSiteId`. * Your `inAppConfig` changes and requires your `siteId`. * The optional `pushConfig` is now a part of your initialization call. You won’t set push settings as a part of a separate configuration like you did with the 1.x SDK. ```dart CustomerIO.initialize( config: CustomerIOConfig( cdpApiKey: 'cdpApiKey', migrationSiteId: 'migrationSiteId', region: Region.us, autoTrackDeviceAttributes: true, inAppConfig: InAppConfig(siteId: 'siteId'), // pushConfig is optional if you use default settings pushConfig: PushConfig( android: PushConfigAndroid( pushClickBehaviorAndroid: PushClickBehaviorAndroid.activityPreventRestart, ), ), ), ); ``` ### 3\. Update your podfile (iOS)[](#3-update-your-podfile-ios) For iOS, you’ll need to update your podfile with the correct iOS dependencies. Update your `Runner` and `NotificationServiceExtension` targets with the code below. ```ruby target 'Runner' do pod 'customer_io/fcm', :path => '.symlinks/plugins/customer_io/ios' end target 'NotificationServiceExtension' do pod 'customer_io_richpush/fcm', :path => '.symlinks/plugins/customer_io/ios' end ``` ### 4\. Update your push notification handler[](#4-update-your-push-notification-handler) In the previous version of the SDK, you had to initialize the SDK itself *and* the `MessagingPushFCM` package. You no longer need to initialize the SDK in your notification handler. You’ll also notice that all the configuration settings for push are a part of the SDK initialization itself. You won’t set push settings in your notification handler anymore. ```swift import UIKit import Flutter import CioMessagingPushFCM import FirebaseMessaging import FirebaseCore @main @objc class AppDelegate: FlutterAppDelegate { override func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { GeneratedPluginRegistrant.register(with: self) // Depending on how you install Firebase, // you may need to add functions to this file, like: // FirebaseApp.configure() // // Read the official Firebase docs to install Firebase correctly! Messaging.messaging().delegate = self MessagingPushFCM.initialize( withConfig: MessagingPushConfigBuilder() .build() ) // This Sets a 3rd party push event handler for the app—rather than the Customer.io SDK and FlutterFire. // Setting the AppDelegate as the handler will internally use `flutter_local_notifications` to handle push events. UNUserNotificationCenter.current().delegate = self as UNUserNotificationCenterDelegate return super.application(application, didFinishLaunchingWithOptions: launchOptions) } func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { Messaging.messaging().setAPNSToken(deviceToken, type: .unknown); } override func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) { MessagingPush.shared.application(application, didFailToRegisterForRemoteNotificationsWithError: error) } } extension AppDelegate: MessagingDelegate { func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) { MessagingPush.shared.messaging(messaging, didReceiveRegistrationToken: fcmToken) } } ``` ### 5\. Update your API calls[](#5-update-your-api-calls) You’ll now make your calls from `.instance` methods. There are also a few crucial differences between the 1.x API and the 2.x API: 1. `userId` replaces `identifier` in your `identify` call. 2. `attributes` has changed to `traits` in `identify`, `setProfileAttributes`, and `setDeviceAttributes` methods. 3. `properties` replaces `attributes` in `track`, `screen`, and any other [eventSomething that a person in your workspace did. Events can trigger campaigns, add people to segments, etc, and you can use properties from events to personalize messages.](/events/) calls. Identify #### Identify[](#Identify) ```dart //new call CustomerIO.instance.identify(userId: email, traits: { "name": user.displayName, "email": user.email, "age": user.age, }); //old call CustomerIO.identify(identifier: email, attributes: { "name": user.displayName, "email": user.email, "age": user.age, }); ``` Track #### Track[](#Track) ```dart //new call CustomerIO.instance.track(name: "Movie Watched", properties: { "movie_name": "The Incredibles", "watch_time_in_minutes": 102, }); //old call CustomerIO.track(name: "Movie Watched", attributes: { "movie_name": "The Incredibles", "watch_time_in_minutes": 102, }); ``` Screen #### Screen[](#Screen) ```dart //new call CustomerIO.instance.screen(title: "Settings", properties: { "source": "Dashboard", "is_logged_in": true, }); //old call CustomerIO.screen(name: "Settings", attributes: { "source": "Dashboard", "is_logged_in": true, }); ``` ## Configuration Changes[](#configuration-changes) As a part of this release, we’ve changed a few `CustomerIOConfig` configuration options when you initialize the SDK. The following table shows the changes to the configuration options. Field Type Default Description `cdpApiKey` string Replaces `apiKey`; required to initialize the SDK and send data to Customer.io. `migrationSiteId` string Replaces `siteId`; required if you’re updating from 2.x. This is the key representing your previous version of the SDK. `trackApplicationLifeCycleEvents` boolean `true` When true, the SDK automatically tracks application lifecycle events (like *Application Installed*). `inAppConfig` object Replaces the former `enableInApp` option, providing a place to set in-app configuration options. For now, it takes a single property called `siteId`. `pushConfig` object Optional push configuration settings directly in the `CustomerIOConfig`. For now, it only takes the `android.PushClickBehavior` setting. If you don’t set a `pushConfig`, we’ll use default push settings. --- ## Whats new > 3.5.0 upgrade **Source:** /integrations/sdk/flutter/whats-new/3.5.0-upgrade # Upgrade from 3.x to 3.5.0 Version 3.5.0 of the Customer.io Flutter SDK adds App Groups support for more reliable push delivery metric tracking on iOS. This update is additive—existing integrations work without modification. ## What changed?[](#what-changed) Version 3.5.0 adds support for [App Groups](/integrations/sdk/flutter/push-notifications/app-groups/), which improves the reliability of push delivery metric tracking on iOS. This update is additive—your existing integration continues to work without changes. However, to take advantage of App Groups, you’ll need to update your Xcode project configuration and regenerate provisioning profiles if you use manual signing. ### Why app groups?[](#why-app-groups) When you send a push notification, the SDK tracks delivery metrics in your Notification Service Extension (NSE). However, iOS can end the NSE before the tracking request completes, which means some delivery data may never reach Customer.io. App Groups provide shared storage between your main app and the NSE, so the SDK can save metrics and recover them on the next app launch. ## Upgrade process[](#upgrade-process) 1. Update to version 3.5.0 or later of the Customer.io Flutter SDK. 2. Follow the [App Groups setup instructions](/integrations/sdk/flutter/push-notifications/app-groups/) to configure your Xcode project and pass `.appGroupId()` to the SDK in your native Swift code. No other code changes are needed. --- ## Whats new > 3.x upgrade **Source:** /integrations/sdk/flutter/whats-new/3.x-upgrade # 2.x -> 3.0.0 Version 3.x of the Customer.io Flutter SDK introduces Firebase wrapper support for FCM users that improves Firebase compatibility and simplifies push notification setup. ## What changed?[](#what-changed) Version 3.x introduces a Firebase wrapper that improves compatibility with Firebase Cloud Messaging (FCM). ## What needs to change?[](#what-needs-to-change) You need to add the `CioFirebaseWrapper` import to your Swift files that use `CioMessagingPushFCM`. Add the Firebase wrapper import to your `AppDelegate.swift` file: ```swift import UIKit import Flutter import CioMessagingPushFCM import CioFirebaseWrapper // Add this import for FCM users import FirebaseMessaging import FirebaseCore @main class AppDelegateWithCioIntegration: CioAppDelegateWrapper {} ``` ## Troubleshooting[](#troubleshooting) If you see build errors related to Firebase after upgrading: 1. **Clean your build**: Run `cd ios && pod install && cd ..` then rebuild 2. **Check imports**: Ensure you’ve added `import CioFirebaseWrapper` to all files that import `CioMessagingPushFCM` --- ## Whats new > 4.0.0 upgrade **Source:** /integrations/sdk/flutter/whats-new/4.0.0-upgrade # Upgrade from 3.x to 4.0.0 Version 4.0.0 of the Customer.io Flutter SDK adds Swift Package Manager (SPM) support for iOS. ## What changed?[](#what-changed) Version 4.0.0 of the Flutter SDK adds Swift Package Manager (SPM) support as an alternative iOS dependency manager. SPM is Apple’s built-in package manager with native Xcode integration, so you don’t need to manage a separate Podfile for Customer.io dependencies. When SPM is enabled, the SDK is automatically resolved - no manual Xcode package setup needed for the main app. CocoaPods continues to work. If you want to stay on CocoaPods, you don’t need to change anything. ## Upgrade process[](#upgrade-process) Update to version 4.0.0 or later of the Customer.io Flutter SDK in your `pubspec.yaml`: ```yaml dependencies: customer_io: ^4.0.0 ``` ### If you use CocoaPods (no changes needed)[](#if-you-use-cocoapods-no-changes-needed) If you want to continue using CocoaPods, you don’t need to change anything. Your existing Podfile will continue to work. Just update the SDK version above and run `pod install --repo-update --project-directory=ios`. ### If you want to switch to SPM[](#if-you-want-to-switch-to-spm) #### Requirements[](#requirements) * Flutter 3.24+ * Xcode 16.0+ * `firebase_core: ^3.5.0` or higher (we recommend at least `^4.6.0`) * `firebase_messaging: ^15.2.0` or higher (we recommend at least `^16.1.3`) Older versions of `firebase_core` and `firebase_messaging` don’t support SPM and cause module conflicts. #### Steps[](#steps) 1. **Update Firebase dependencies** in your `pubspec.yaml` to SPM-compatible versions: ```yaml dependencies: firebase_core: ^3.5.0 # we recommend at least ^4.6.0 firebase_messaging: ^15.2.0 # we recommend at least ^16.1.3 ``` 2. **Enable SPM (if not already enabled).** If you haven’t enabled Swift Package Manager in your Flutter project, you can do so globally or per-project: * **Global**: Run `flutter config --enable-swift-package-manager` * **Per-project**: Add the following to your `pubspec.yaml`: ```yaml flutter: config: enable-swift-package-manager: true ``` 3. **Remove CIO pod lines and the NSE target from your Podfile.** Remove any `customer_io` pod lines and the `NotificationServiceExtension` target block: ```ruby pod 'customer_io/fcm', :path => ... pod 'customer_io/location', :path => ... pod 'customer_io_richpush/fcm', :path => ... ``` With SPM enabled, Flutter’s pod helper automatically skips SPM-handled plugins. The core SDK, in-app messaging, and push notifications modules (`DataPipelines`, `MessagingInApp`, `MessagingPushFCM`) are automatically included via SPM - no additional setup needed.  Using the Location module? If you use the Location module, make sure `customerio_location_enabled=true` is set in your `android/gradle.properties`. This flag controls Location inclusion on both Android and iOS when using SPM. If the flag can’t be read (e.g. in add-to-app modules or some CI setups), you can use the `CIO_LOCATION` environment variable as a fallback: `CIO_LOCATION=true flutter build ios`. See [Location tracking](/integrations/sdk/flutter/tracking/location/) for details. 4. **Remove the old CocoaPods framework from the NSE target** in Xcode. Go to your **NotificationServiceExtension** target > **General** > **Frameworks, Libraries, and Embedded Content** and remove `Pods_NotificationServiceExtension.framework`. 5. **Add the SPM framework to the NSE target.** In the same **Frameworks and Libraries** section, click **+** and add **FlutterGeneratedPluginSwiftPackage**. [![Add FlutterGeneratedPluginSwiftPackage to the NotificationServiceExtension target](https://customer.io/images/xcode-nse-spm-framework.png)](#63f96c00dae3d457f55911fae69d4722-lightbox) 6. **Add `import UserNotifications`** to the top of your `NotificationService.swift`: ```swift import CioMessagingPushFCM import UserNotifications ``` SPM doesn’t transitively import system frameworks like CocoaPods does, so you must add the import. 7. **Clean and rebuild:** ```bash cd ios && rm -rf Pods Podfile.lock cd .. && flutter clean && flutter pub get flutter build ios ``` ## Troubleshooting[](#troubleshooting) If you run into issues during migration, see [SPM troubleshooting](/integrations/sdk/flutter/getting-started/troubleshooting/#spm-issues) for solutions to common problems like module conflicts, deployment target errors, and CI build failures. --- ## Whats new > Changelog **Source:** /integrations/sdk/flutter/whats-new/changelog # Changelog Check out the release history for the Flutter SDK. Stable releases have been tested thoroughly and are ready for use in your production apps. #### Need to upgrade? Select your current version to see all the features and fixes from your version to the latest release. 4.0.03.5.03.4.03.3.03.2.23.2.13.2.03.1.13.1.03.0.13.0.02.9.02.8.02.7.02.6.12.6.02.5.02.4.32.4.22.4.12.4.02.3.12.3.02.2.02.1.82.1.72.1.62.1.52.1.42.1.32.1.22.1.12.1.02.0.01.5.21.5.11.5.01.4.01.3.21.3.11.3.01.2.71.2.61.2.51.2.41.2.31.2.21.2.11.2.01.1.21.1.11.1.01.0.0 ### Breaking Changes ### Features ### Bug Fixes # 4.x Releases[](#4x-releases) * * * * ### 4.0.0[](#400) April 10, 2026[code changes](https://github.com/customerio/customerio-flutter/compare/3.5.0...4.0.0) ### ⚠ BREAKING CHANGES * Added support for Swift Package Manager (SPM) in Flutter SDK. No changes for apps using CocoaPods, apps using SPM should refer to the updated documentation for setup instructions. (#330) ### Features * Added support for Swift Package Manager (SPM) ([#330](https://github.com/customerio/customerio-flutter/issues/330)) ([8abff81](https://github.com/customerio/customerio-flutter/commit/8abff815225379dab5e350cbb5b6d33af213512b)) # 3.x Releases[](#3x-releases) * * * * ### 3.5.0[](#350) April 2, 2026[code changes](https://github.com/customerio/customerio-flutter/compare/3.4.0...3.5.0) ### Features * Push delivery reslience improvement ([#321](https://github.com/customerio/customerio-flutter/issues/321)) ([7c23a0a](https://github.com/customerio/customerio-flutter/commit/7c23a0aaa9b647cf06db2e592bd8debc73edeb96)) * ### 3.4.0[](#340) March 11, 2026[code changes](https://github.com/customerio/customerio-flutter/compare/3.3.0...3.4.0) ### Features * Location enrichment ([#316](https://github.com/customerio/customerio-flutter/issues/316)) ([1b36d69](https://github.com/customerio/customerio-flutter/commit/1b36d6906599a15f87448859e943e8df049687e4)) * ### 3.3.0[](#330) February 21, 2026[code changes](https://github.com/customerio/customerio-flutter/compare/3.2.2...3.3.0) ### Features * Added support for Notification Inbox ([#313](https://github.com/customerio/customerio-flutter/issues/313)) ([b1e732b](https://github.com/customerio/customerio-flutter/commit/b1e732b7606e2f95e54d9a50f00cbbeb72b119ea)) * ### 3.2.2[](#322) February 16, 2026[code changes](https://github.com/customerio/customerio-flutter/compare/3.2.1...3.2.2) ### Bug Fixes * Downgrade okhttp version to 4.x ([#307](https://github.com/customerio/customerio-flutter/issues/307)) ([b0dff34](https://github.com/customerio/customerio-flutter/commit/b0dff34c2e5acd29f7b373820d667bafc8c63fb3)) * ### 3.2.1[](#321) February 5, 2026[code changes](https://github.com/customerio/customerio-flutter/compare/3.2.0...3.2.1) ### Bug Fixes * Remove outdated sonatype snapshot dependency ([#303](https://github.com/customerio/customerio-flutter/issues/303)) ([02309bf](https://github.com/customerio/customerio-flutter/commit/02309bf36a334663a9c99d86f1f4a3f1bcaa9ca9)) * ### 3.2.0[](#320) January 14, 2026[code changes](https://github.com/customerio/customerio-flutter/compare/3.1.1...3.2.0) ### Features * In-app messages now support SSE (Server-Sent Events) as an alternative to polling, reducing latency and improving message delivery efficiency ([#298](https://github.com/customerio/customerio-flutter/issues/298)) ([59ab310](https://github.com/customerio/customerio-flutter/commit/59ab3102e6b78f404e59bc937fa0fa783705d1bf)) * ### 3.1.1[](#311) December 16, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/3.1.0...3.1.1) ### Bug Fixes * Bump Android compileSdk to 36 for AndroidX compatibility ([#297](https://github.com/customerio/customerio-flutter/issues/297)) ([5b8f972](https://github.com/customerio/customerio-flutter/commit/5b8f9725b0a8df3d99e4b53833a0d1c2f1d4b6fb)) * ### 3.1.0[](#310) October 30, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/3.0.1...3.1.0) ### Features * Updated the SDK and dependencies for Android 16 compatibility, including minor updates to better support newer OS restrictions and behavior changes. ([#293](https://github.com/customerio/customerio-flutter/issues/293)) ([2b235de](https://github.com/customerio/customerio-flutter/commit/2b235de04cea8b51682e2acb8021c0830686aa8f)) ### ⚠️ Notes * Apps now may need to update their `compileSdk` version to `36` and Gradle version to at least `8.9.3` to ensure compatibility with updated dependencies and to successfully build against Android 16. * ### 3.0.1[](#301) October 24, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/3.0.0...3.0.1) ### Bug Fixes * prevent message type crash in release builds ([#291](https://github.com/customerio/customerio-flutter/issues/291)) ([44ff921](https://github.com/customerio/customerio-flutter/commit/44ff92167b4c26b42e018b1288f58e1631e6a1ce)) * ### 3.0.0[](#300) October 17, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.9.0...3.0.0) ### ⚠ BREAKING CHANGES * Add CioFirebaseWrapper to pull in Firebase specific services (#290) ### Features * Add CioFirebaseWrapper to pull in Firebase specific services ([#290](https://github.com/customerio/customerio-flutter/issues/290)) ([444becb](https://github.com/customerio/customerio-flutter/commit/444becbb27ac9e49bb2f4d81dd0f75a3d50b7ad1)) # 2.x Releases[](#2x-releases) * * * * ### 2.9.0[](#290) October 8, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.8.0...2.9.0) ### Features * You can now send banners, modals, pop-ups, and surveys to anonymous visitors —no ID or email required. ([#289](https://github.com/customerio/customerio-flutter/issues/289)) ([47f1918](https://github.com/customerio/customerio-flutter/commit/47f1918562a498117952bd77163398f9ec529133)) * ### 2.8.0[](#280) October 7, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.7.0...2.8.0) ### Features * Improve push notificaiton delivery receipts delay ([#287](https://github.com/customerio/customerio-flutter/issues/287)) ([4503048](https://github.com/customerio/customerio-flutter/commit/4503048d98613664888b9f60e1a4ca75690d9270)) * ### 2.7.0[](#270) October 3, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.6.1...2.7.0) ### Breaking Features * Support for Kotlin 2+ is added (#591) (b5f94ff) but this also means apps needs to have the following minimum requirement * Gradle: 8.0 or later * Android Gradle Plugin (AGP): 8.0 or later (8.2+ recommended) * Kotlin: 1.9.20 or later (2.0+ required if using Kotlin Multiplatform or K2-specific features) ### Features * Upgrade Kotlin and AGP versions ([#284](https://github.com/customerio/customerio-flutter/issues/284)) ([ed9da81](https://github.com/customerio/customerio-flutter/commit/ed9da81ad05500e07224391e696f725cc75d4b76)) * Added support for queue sticky sessions from latest Android native SDK (customerio/customerio-android#598) * Align public API with other CIO SDK platforms from latest Android native SDK (customerio/customerio-android#600) ### Bug Fixes * Resolved a crash when dismissing in app messages using back press during initial loading phase. Users can now safely navigate away from messages without encountering unexpected app crashes. from latest Android native SDK (customerio/customerio-android#608) * ### 2.6.1[](#261) September 29, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.6.0...2.6.1) ### Bug Fixes * Upgrade Android compileSdk to 34 ([#282](https://github.com/customerio/customerio-flutter/issues/282)) ([9a29530](https://github.com/customerio/customerio-flutter/commit/9a29530c9fb0646926429205fa7b875bc3701cdc)) * ### 2.6.0[](#260) September 16, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.5.0...2.6.0) ### Improvements * Updated Native iOS SDK from `3.11.0` to `3.13.1` which includes following updates: ([#280](https://github.com/customerio/customerio-flutter/issues/280)) ([70c78cc](https://github.com/customerio/customerio-flutter/commit/70c78cc7c93751f5404d580d1a466416f4466dc4)) * Added support for queue sticky sessions * Align public API with other CIO SDK platforms * Fixed build issues on Xcode 26 beta that only affected apps using CocoaPods * Fixed an issue where custom scheme URLs were not opening when using FCM with `CioAppDelegateWrapper` * ### 2.5.0[](#250) August 27, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.4.3...2.5.0) ### Features * Align public API with other CIO SDK platforms ([#271](https://github.com/customerio/customerio-flutter/issues/271)) ([b559742](https://github.com/customerio/customerio-flutter/commit/b559742375205a082fca820d3aa1923ef94b1741)) * ### 2.4.3[](#243) August 11, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.4.2...2.4.3) ### Bug Fixes * Fixed an issue where inline message view occupied `1dp` of space even when no content was available. With this fix, the view no longer takes up any visual space when content is unavailable and only becomes visible when there is content to display. ([#259](https://github.com/customerio/customerio-flutter/issues/259)) ([b78cffd](https://github.com/customerio/customerio-flutter/commit/b78cffda57f2940b321a7c0e2afab9627a78ffae)) * ### 2.4.2[](#242) July 24, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.4.1...2.4.2) ### Fixes and Tooling update * Support for FCM 12.x is added which requires a minimum iOS deployment target of 15. If you’re using FCM module, ensure your deployment target and tooling are up to date. Or lock Firebase to 11.x to avoid compatibility issues * Fixes a crash when build attributes from device are nullable (iOS 3.11.0, Android 4.7.1) ([#253](https://github.com/customerio/customerio-flutter/issues/253)) ([9e66b4b](https://github.com/customerio/customerio-flutter/commit/9e66b4beee2ebbbe3bbf7e79e83011255fd91349)) * ### 2.4.1[](#241) July 21, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.4.0...2.4.1) ### Bug Fixes * Fixed build issue on iOS by adding a default implementation for an internal SPI method in `DeepLinkUtil`, preventing conformance errors with `BUILD_LIBRARY_FOR_DISTRIBUTION = YES` ([#249](https://github.com/customerio/customerio-flutter/issues/249)) ([7313421](https://github.com/customerio/customerio-flutter/commit/731342157082e76ae846c1964ad008f53e3c1834)) * ### 2.4.0[](#240) July 17, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.3.1...2.4.0) ### Features * Add ability to configure messaging channels for local notifications ([#247](https://github.com/customerio/customerio-flutter/issues/247)) ([0541919](https://github.com/customerio/customerio-flutter/commit/05419193144bd3cebcdbd732fb14091ead6fa86a)) * ### 2.3.1[](#231) July 9, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.3.0...2.3.1) ### Bug Fixes * Preserve numeric types when doing sanitization for JSON ([#246](https://github.com/customerio/customerio-flutter/issues/246)) ([ea94c07](https://github.com/customerio/customerio-flutter/commit/ea94c078a5003f0cca1b794be04d783291f2b06e)) * ### 2.3.0[](#230) June 26, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.2.0...2.3.0) ### Features * Added support for inline in-app messages. Inline in-app messages act like a part of the content on your page. They let you dynamically populate parts of your app and talk to your customers without interrupting their experience. ([39e7b87](https://github.com/customerio/customerio-flutter/commit/39e7b8751210056646f976aebea2c377c59156de)) * ### 2.2.0[](#220) June 2, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.1.8...2.2.0) ### Features * Add support for iOS no-swizzling approach and improve example app setup * Fixed an issue where the SDK enforced a strict version of firebase messaging, preventing integration with newer versions. * Fixes the bug where multi screen in-app messages might dismiss earlier than intended * ([#226](https://github.com/customerio/customerio-flutter/issues/226)) ([2f4c0a2](https://github.com/customerio/customerio-flutter/commit/2f4c0a2064a6006829df5b0ee68627f501c62822)) * ### 2.1.8[](#218) May 30, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.1.7...2.1.8) ### Bug Fixes * Fixed a crash that occurred only when the app was restored by Android OS from background after being removed from memory with a modal in-app message active. ([#225](https://github.com/customerio/customerio-flutter/issues/225)) ([b521461](https://github.com/customerio/customerio-flutter/commit/b521461a823e42d4ff040b83e7c37d957c83b839)) * ### 2.1.7[](#217) May 22, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.1.6...2.1.7) ### Bug Fixes * Fixed an issue where SDK calls returning no result (i.e. `void`) were incorrectly logged as errors for unsupported values. The fix removes unnecessary error log without affecting any functionality or behavior. ([#224](https://github.com/customerio/customerio-flutter/issues/224)) ([2022c27](https://github.com/customerio/customerio-flutter/commit/2022c27609462461596ddc50076a134f38f514fb)) * ### 2.1.6[](#216) April 28, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.1.5...2.1.6) Updates the iOS native dependency from `3.8.1` to `3.8.2` and Android native dependency from `4.5.6` to `4.5.8` which includes the following improvements.([#221](https://github.com/customerio/customerio-flutter/issues/221)) ([56418f2](https://github.com/customerio/customerio-flutter/commit/56418f292b377fbf5f05f14143be1740e7bce31e)) ### Bug Fixes * \[iOS\] Region codes are now handled more flexibly—if we can’t recognize one, we use a default instead of blocking SDK startup. ([https://github.com/customerio/customerio-ios/pull/879](https://github.com/customerio/customerio-ios/pull/879)) * \[iOS\] Set a safe upper limit for the Firebase (FCM) version in CocoaPods to avoid build issues with newer versions.([https://github.com/customerio/customerio-ios/pull/880](https://github.com/customerio/customerio-ios/pull/880)) * \[Android\]Fixed an issue where a freshly generated Firebase token was being deleted by mistake. Now, only outdated tokens are removed. ([https://github.com/customerio/customerio-android/issues/517](https://github.com/customerio/customerio-android/issues/517)) ([ccb9de2](https://github.com/customerio/customerio-android/commit/ccb9de27e7ad38e2569a5a9d91d9fec2cd5293ce)) * \[Android\] Custom events triggered via the plugin now follow the same timing and lifecycle as other SDK events. ([https://github.com/customerio/customerio-android/issues/521](https://github.com/customerio/customerio-android/issues/521)) ([1c0b7a6](https://github.com/customerio/customerio-android/commit/1c0b7a6c7bc3b14820b9c6bab3168025206cbfbd)) * ### 2.1.5[](#215) April 14, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.1.4...2.1.5) ### Bug Fixes * Better support for user data with missing fields—SDK now handles null values in nested attributes or traits gracefully. ([#217](https://github.com/customerio/customerio-flutter/issues/217)) ([0d5928b](https://github.com/customerio/customerio-flutter/commit/0d5928b27292def1e427becb165d64880bb46883)) * ### 2.1.4[](#214) April 3, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.1.3...2.1.4) Updates the iOS native dependency from `3.8.0` to `3.8.1` and Android native dependency from `4.5.3` to `4.5.5` which includes the following improvements. ### Bug Fixes * \[iOS\] Fixed an issue where the “Application Installed” event was incorrectly triggered on every app launch instead of only after the initial installation. * \[Android\] Resolved syncing issues for events stored while in battery saver (offline) mode ([https://github.com/customerio/customerio-android/issues/498](https://github.com/customerio/customerio-android/issues/498)) ([6f3d16f](https://github.com/customerio/customerio-android/commit/6f3d16fe01a675cfa522099230baf03650cf9c42)) * \[Android\] Fixed the sequencing of screen tracking events for in-app messaging current screen state ([https://github.com/customerio/customerio-android/issues/500](https://github.com/customerio/customerio-android/issues/500)) ([6877daf](https://github.com/customerio/customerio-android/commit/6877daf98235ce9c96a2ce4932f188efb2c33a71)) * ### 2.1.3[](#213) February 27, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.1.2...2.1.3) ### Bug Fixes * Incorrectly scrolling content for in-app modal messages positioned top/bottom ([#208](https://github.com/customerio/customerio-flutter/issues/208)) ([5bdf0eb](https://github.com/customerio/customerio-flutter/commit/5bdf0ebae6a5c2f0f34589d80c77212557dfd033)) * ### 2.1.2[](#212) February 21, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.1.1...2.1.2) ### Bug Fixes * Android 14 introduced strict rules for when apps are in the killed state, impacting push delivery tracking. This release fixes that.([#204](https://github.com/customerio/customerio-flutter/issues/204)) ([8b60a4e](https://github.com/customerio/customerio-flutter/commit/8b60a4ee1d5357ee871fcf03684b307a117350fa)) * ### 2.1.1[](#211) January 9, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.1.0...2.1.1) Updates the iOS native dependency from `3.7.1` to `3.7.2` and Android native dependency from `4.5.0` to `4.5.2` which includes the following improvements. ### Bug Fixes * \[Android\] Fixes the bug where device update/delete events would not migrate automatically when migrating from v3 to v4 ([https://github.com/customerio/customerio-android/issues/481](https://github.com/customerio/customerio-android/issues/481)) * \[Android & iOS\] Fixes in-app messages overlay background color being ignored from in-app message payload ([https://github.com/customerio/customerio-android/issues/485](https://github.com/customerio/customerio-android/issues/485)) ([https://github.com/customerio/customerio-ios/issues/843](https://github.com/customerio/customerio-ios/issues/843)) * ### 2.1.0[](#210) January 6, 2025[code changes](https://github.com/customerio/customerio-flutter/compare/2.0.0...2.1.0) ### Features * Added ability to disable forwarding screen events to destinations/servers. Apps can still send screen events for local processing and use them for page rules in in-app messages by updating SDK configuration during initialization. ([#190](https://github.com/customerio/customerio-flutter/issues/190)) ([b4a4fed](https://github.com/customerio/customerio-flutter/commit/b4a4feddb943972f635826d55d31a4cb14904210)) * ### 2.0.0[](#200) December 10, 2024[code changes](https://github.com/customerio/customerio-flutter/compare/1.5.2...2.0.0) ### ⚠ BREAKING CHANGES * Data Pipelines Support: Sending your mobile data into our customer data platform (CDP) helps you support Journeys and the rest of your martech stack—analytics, data warehouses, CRMs, and more. (#187) > ***NOTE:*** Please follow the [migration guide](https://docs.customer.io/sdk/flutter/whats-new/2.x-upgrade/) for a seamless upgrade to this version. ### Features * Anonymous tracking: You can send anonymous events, and we’ll reconcile anonymous activity with your users when you identify them. * Built-in lifecycle events: the SDK now automatically captures events like “Application Installed” and “Application Updated” for you, so you better understand your users’ behaviors in your app. * New device data: The SDK captures complete device-level context, such as your audience’s screen dimensions, device names, and more. ### Improvements * Resolves an issue where the user agent for events was labeled as coming from the iOS SDK instead of the Flutter SDK. # 1.x Releases[](#1x-releases) * * * * ### 1.5.2[](#152) September 6, 2024[code changes](https://github.com/customerio/customerio-flutter/compare/1.5.1...1.5.2) Updates Android Native dependency from **3.11.0** to **3.11.2** which includes following improvements. ### Features * Messages created in the [new drag and drop in-app editor](https://customer.io/docs/release-notes/2024-07-15-in-app-visual-editor/) will load much faster and don’t require pre-fetching assets. If you are using the older in-app editor, the initial in-app message may experience a delay. We highly recommend upgrading to the new in-app editor to avoid this issue and ensure optimal performance. \[[#139](https://github.com/customerio/customerio-flutter/issues/139)\] ([b10cc75](https://github.com/customerio/customerio-flutter/commit/b10cc751d6f220e7c7ade1c189bba28ee16b68ff)) ### Bug Fixes * Fixed crash that could occur on some Android devices during asset pre-fetching step in certain situations. \[[#139](https://github.com/customerio/customerio-flutter/issues/139)\] ([b10cc75](https://github.com/customerio/customerio-flutter/commit/b10cc751d6f220e7c7ade1c189bba28ee16b68ff)) * Resolved an issue where calling `CustomerIO.MessagingInApp().dismissMessage()` explicitly would print crash logs on Android. The method can now be called safely without unnecessary logs. \[[#142](https://github.com/customerio/customerio-flutter/pull/142)\] ([1635acf](https://github.com/customerio/customerio-flutter/commit/1635acfba88fcf74462072294a4d3e70f069e119)) * ### 1.5.1[](#151) August 1, 2024[code changes](https://github.com/customerio/customerio-flutter/compare/1.5.0...1.5.1) ### Bug Fixes * Resolved an issue where the native iOS code communicated to the Flutter code on a non-platform thread. This change ensures that platform channel messages are sent on the correct platform thread, preventing potential data loss or crashes. ([#134](https://github.com/customerio/customerio-flutter/issues/134)) ([bc8704b](https://github.com/customerio/customerio-flutter/commit/bc8704b03891372566f3450ed02a082ecb0ae4a9)) * ### 1.5.0[](#150) July 2, 2024[code changes](https://github.com/customerio/customerio-flutter/compare/1.4.0...1.5.0) ### Features * When using page rules and when an in-app messages need a second to load, the in-app message might appear after a user navigates to another page. We made changes to ensure the page-rules are checked after the message is loaded and immediately before it’s displayed in order to resolve this issue.([#131](https://github.com/customerio/customerio-flutter/issues/131)) ([a563055](https://github.com/customerio/customerio-flutter/commit/a5630555e34668a10c299a1b22f59afcc46217e9)) * ### 1.4.0[](#140) April 18, 2024[code changes](https://github.com/customerio/customerio-flutter/compare/1.3.2...1.4.0) ### Features * support for android gradle plugin 8 ([#117](https://github.com/customerio/customerio-flutter/issues/117)) ([48b4e06](https://github.com/customerio/customerio-flutter/commit/48b4e06ae85ef7bd58e963e89d67d23d7191d5aa)) * ### 1.3.2[](#132) April 8, 2024[code changes](https://github.com/customerio/customerio-flutter/compare/1.3.1...1.3.2) ### Bug Fixes * added proguard rules for R8 strict mode ([#116](https://github.com/customerio/customerio-flutter/issues/116)) ([9946fe7](https://github.com/customerio/customerio-flutter/commit/9946fe73938ae25caf4beac710855feeaa2e4dba)) * ### 1.3.1[](#131) November 14, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.3.0...1.3.1) ### Bug Fixes * improve android push click behavior ([#89](https://github.com/customerio/customerio-flutter/issues/89)) ([62b9e61](https://github.com/customerio/customerio-flutter/commit/62b9e615cbe0c145319d4a5ceb8ab44823b6adb6)) * ### 1.3.0[](#130) October 25, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.2.7...1.3.0) ### Features * in-app message persistence ([#97](https://github.com/customerio/customerio-flutter/issues/97)) ([71d85cc](https://github.com/customerio/customerio-flutter/commit/71d85cc4ce25a37399a68afda975abea19bfccc1)) * ### 1.2.7[](#127) October 18, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.2.6...1.2.7) ### Bug Fixes * in-app crash for no browser ([#94](https://github.com/customerio/customerio-flutter/issues/94)) ([8b859ed](https://github.com/customerio/customerio-flutter/commit/8b859eddf383c1a195767eb87cf6513bb81ac44c)) * ### 1.2.6[](#126) September 28, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.2.5...1.2.6) ### Bug Fixes * stack-overflow caused by BQ recursion ([#90](https://github.com/customerio/customerio-flutter/issues/90)) ([ebc7511](https://github.com/customerio/customerio-flutter/commit/ebc7511d19409d7524f5aa8dd5446d85dc14ecfb)) * ### 1.2.5[](#125) September 7, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.2.4...1.2.5) ### Bug Fixes * in-app concurrency issue android ([#73](https://github.com/customerio/customerio-flutter/issues/73)) ([93332a4](https://github.com/customerio/customerio-flutter/commit/93332a44f0865534b414626a9f177efbb979f311)) * ### 1.2.4[](#124) July 25, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.2.3...1.2.4) ### Bug Fixes * in-app messages not displaying for release builds on Android ([#65](https://github.com/customerio/customerio-flutter/issues/65)) ([1d742c2](https://github.com/customerio/customerio-flutter/commit/1d742c2975fd200df45a7e6c81c54eead0302a9c)) * ### 1.2.3[](#123) July 14, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.2.2...1.2.3) ### Bug Fixes * hardcode android native SDK version ([#61](https://github.com/customerio/customerio-flutter/issues/61)) ([587f559](https://github.com/customerio/customerio-flutter/commit/587f559fbba4864d17f0506875474ff705866189)) * ### 1.2.2[](#122) June 27, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.2.1...1.2.2) ### Bug Fixes * iOS crash on forced unwrapping ([#59](https://github.com/customerio/customerio-flutter/issues/59)) ([f514174](https://github.com/customerio/customerio-flutter/commit/f5141742c49e876f40034d366c7122d519ee897e)) * ### 1.2.1[](#121) June 6, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.2.0...1.2.1) ### Bug Fixes * updated module name from common to CioInternalCommon ([#55](https://github.com/customerio/customerio-flutter/issues/55)) ([d81f8df](https://github.com/customerio/customerio-flutter/commit/d81f8df2f3c686f197625c77900af0862211b8e1)) * ### 1.2.0[](#120) June 1, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.1.2...1.2.0) ### Features * in-app dismiss support ([#51](https://github.com/customerio/customerio-flutter/issues/51)) ([c4d21f2](https://github.com/customerio/customerio-flutter/commit/c4d21f2c294ee37ebfc8f644bc6580cd44556544)) * ### 1.1.2[](#112) May 3, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.1.1...1.1.2) ### Bug Fixes * autoupdate to latest major version of iOS SDK ([#40](https://github.com/customerio/customerio-flutter/issues/40)) ([974a342](https://github.com/customerio/customerio-flutter/commit/974a3422544e712ae52fc7ca1a8318601d0859c2)) * ### 1.1.1[](#111) April 26, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.1.0...1.1.1) ### Bug Fixes * missing opened metric on android 12 and above ([#43](https://github.com/customerio/customerio-flutter/issues/43)) ([1a61e0e](https://github.com/customerio/customerio-flutter/commit/1a61e0e587bd0315122db2783b76930fa372c589)) * ### 1.1.0[](#110) April 26, 2023[code changes](https://github.com/customerio/customerio-flutter/compare/1.0.0...1.1.0) ### Features * process push notifications received outside CIO SDK ([#38](https://github.com/customerio/customerio-flutter/issues/38)) ([7b5cb7e](https://github.com/customerio/customerio-flutter/commit/7b5cb7e2aab1f7d3d9a521d5a58b9d0f3eab5177)) * ### 1.0.0[](#100) April 3, 2023[code changes](https://github.com/customerio/customerio-flutter/issues/17) ### Features * added missing methods ([#17](https://github.com/customerio/customerio-flutter/issues/17)) ([73f29e6](https://github.com/customerio/customerio-flutter/commit/73f29e64cb58c24f97f3654c5519e22e5255c507)) * added SDK config ([#1](https://github.com/customerio/customerio-flutter/issues/1)) ([e8ed7dd](https://github.com/customerio/customerio-flutter/commit/e8ed7ddef985895840a4e406c1a5bb35250c7096)) * tracking and in-app added ([#2](https://github.com/customerio/customerio-flutter/issues/2)) ([c23f2d9](https://github.com/customerio/customerio-flutter/commit/c23f2d936b801692618c5938ab3d32183345fbbe)) ### Bug Fixes * add test coverage and refactored scripts ([#34](https://github.com/customerio/customerio-flutter/issues/34)) ([f7f2387](https://github.com/customerio/customerio-flutter/commit/f7f2387941a6416411b26061420ccfb98ed0db72)) * formatting issues ([d67fa7e](https://github.com/customerio/customerio-flutter/commit/d67fa7eea264d20e1b6314277bef926150625f4e)) * in-app remove gist org id ([#19](https://github.com/customerio/customerio-flutter/issues/19)) ([ce4cc9e](https://github.com/customerio/customerio-flutter/commit/ce4cc9e4dd596ba2ff47e02199096154eac8ec06)) * missing methods and extra dependency ([2c5deca](https://github.com/customerio/customerio-flutter/commit/2c5decac44288e6fba439c1a5669032a0282c69c)) * obj-c bindings issue ([0dbe4ef](https://github.com/customerio/customerio-flutter/commit/0dbe4ef4a893df10d5bf060b6635240699357fa1)) * plugin version in user-agent ([a10e482](https://github.com/customerio/customerio-flutter/commit/a10e482de83bb4f648408f99a2bed1cade6561c7)) * release script typo ([2a8b7ae](https://github.com/customerio/customerio-flutter/commit/2a8b7aea96d74cd095c122cede2f7c7ff3dfbd89)) * typo fixed ([#9](https://github.com/customerio/customerio-flutter/issues/9)) ([a5107df](https://github.com/customerio/customerio-flutter/commit/a5107dfb566561d9b8d3155f0a8a87096de78ee2)), closes [#7](https://github.com/customerio/customerio-flutter/issues/7) [#8](https://github.com/customerio/customerio-flutter/issues/8) * updated android dependency to auto update ([#24](https://github.com/customerio/customerio-flutter/issues/24)) ([040cef2](https://github.com/customerio/customerio-flutter/commit/040cef205821c9bb1913a378dfffa356a3b25650)) * updated icon and typo ([57c6eef](https://github.com/customerio/customerio-flutter/commit/57c6eefb7d77bc88972450d75e74f1982abb8b16)) * [4.x Releases](#4x-releases) * [4.0](#40x-releases) * [4.0.0](#400) * [3.x Releases](#3x-releases) * [3.5](#35x-releases) * [3.5.0](#350) * [3.4](#34x-releases) * [3.4.0](#340) * [3.3](#33x-releases) * [3.3.0](#330) * [3.2](#32x-releases) * [3.2.2](#322) * [3.2.1](#321) * [3.2.0](#320) * [3.1](#31x-releases) * [3.1.1](#311) * [3.1.0](#310) * [3.0](#30x-releases) * [3.0.1](#301) * [3.0.0](#300) * [2.x Releases](#2x-releases) * [2.9](#29x-releases) * [2.9.0](#290) * [2.8](#28x-releases) * [2.8.0](#280) * [2.7](#27x-releases) * [2.7.0](#270) * [2.6](#26x-releases) * [2.6.1](#261) * [2.6.0](#260) * [2.5](#25x-releases) * [2.5.0](#250) * [2.4](#24x-releases) * [2.4.3](#243) * [2.4.2](#242) * [2.4.1](#241) * [2.4.0](#240) * [2.3](#23x-releases) * [2.3.1](#231) * [2.3.0](#230) * [2.2](#22x-releases) * [2.2.0](#220) * [2.1](#21x-releases) * [2.1.8](#218) * [2.1.7](#217) * [2.1.6](#216) * [2.1.5](#215) * [2.1.4](#214) * [2.1.3](#213) * [2.1.2](#212) * [2.1.1](#211) * [2.1.0](#210) * [2.0](#20x-releases) * [2.0.0](#200) * [1.x Releases](#1x-releases) * [1.5](#15x-releases) * [1.5.2](#152) * [1.5.1](#151) * [1.5.0](#150) * [1.4](#14x-releases) * [1.4.0](#140) * [1.3](#13x-releases) * [1.3.2](#132) * [1.3.1](#131) * [1.3.0](#130) * [1.2](#12x-releases) * [1.2.7](#127) * [1.2.6](#126) * [1.2.5](#125) * [1.2.4](#124) * [1.2.3](#123) * [1.2.2](#122) * [1.2.1](#121) * [1.2.0](#120) * [1.1](#11x-releases) * [1.1.2](#112) * [1.1.1](#111) * [1.1.0](#110) * [1.0](#10x-releases) * [1.0.0](#100) ---