Introducing the official Percept Flutter SDK

Getting Started

1. Install

  1. Add the following lines to your package's pubspec.yaml file to include the dependency:
      percept_flutter: ^1.2.2
  1. To install the package, use the following command in your command line interface:
$ flutter pub get
  1. Import the package in your Dart code to make it available for use:
import 'package:percept_flutter/percept_flutter.dart'

2. Initialize Percept SDK

import 'package:percept_flutter/percept_flutter.dart'

class YourClassState extends State<YourClass> {
  Percept percept;

  void initState() {

Percept constructor takes some optional parameters which are as follows:

Parameter Name Description Default Value
autoCaptureAppLifecycleEvents Auto track app life cycle events or not true
autoCaptureUnhandledErrors Auto track unhandled errors true
maxBatchSize Default batch size of event requests 100
maxDelayMins Maximum interval between retry requests in case of failure 30 min
maxCacheSizeMb Maximum cache size used to store failed requests 10 mb
clearAfterDays Days after which stored failed requests are deleted in case of retry failure 7 days

int maxBatchSize = 100, int maxDelayMins = 30, int maxCacheSizeMb = 10, int clearAfterDays = 7

NOTE: Token is the percept workspace token associated with your app.

3. Set user

After successfully initializing the SDK, On login set current User using the following function.

percept.setUser(userId: "userId",userProperties: {"TestUser"}, additionalProperties: {"isVerifiedAccount": true})

4. Set currrent user properties

use setCurrentUserProperties method to set properties on the user profile created by setUser

// first call this method
await percept.setUser(userId: 'U1');

// sets user `deviceToken` and `isPaidUser` property to true
percept.setCurrentUserProperties(userProperties: {UserProperty.deviceToken:"token"}, additionalProperties: {"isPaidUser": true})

UserProperties can only have keys present in the UserProperty enum which are as follows.

User Property Name Description
userId UserId associated with the user
name name of the user
phone Phone number associated with the user
email Email ID associated with the user
deviceToken FCM token for the device

To get your firebase token you can use:



FirebaseMessaging.instance.onTokenRefresh.listen((token) => { });

5. Engage

Integration with Firebase Messaging: To streamline push notification functionality and accurately monitor their impact on attribution.

  1. Capture when app session is initiated from terminated state by interacting with push notification.
// Get any messages which caused the application to open from a terminated state.
RemoteMessage? initialMessage = await FirebaseMessaging.instance.getInitialMessage();
   if (initialMessage != null) {
  1. Capture when app session is resumed from background state by interacting with push notification.
// Get any messages which caused the application to open from a terminated state.
   (message) => _percept.trackPNBackground(message.toMap()),
  1. Capture when the app was in foreground and the push notification was received.
// Get any messages which were received when the app was in foreground.
   (message) => _percept.trackPNForeground(message.toMap()),
  1. Notifying SDK when notification received in terminated state for better attribution

Register the handler before calling runApp. Details for background fcm message handling->

import 'package:percept_flutter/constants.dart';
import 'package:percept_flutter/utils/comm_helpers.dart';

Future<void> bgMessageHandler(RemoteMessage message) async {
      PerceptCommunicationState.received, message.toMap(), PERCEPT_TEST_KEY);

void main() async {
  await Firebase.initializeApp(options: DefaultOptions.currentPlatform);

This property will be tracked by pi_pn_attribution property in every subsequently tracked event.

pi_pn_attribution Description
terminated Interaction with pn initiated current app session from terminated state
background Interaction with pn resumed current app session from background state
foreground Notification was received when the app was in foreground state
none Current session is not attributed to any pn

Along with pi_pn_attribution property following properties are tracked:

Property_name Description
pi_pn_targetUrl TargetUrl in the notification payload
pi_pn_campaignId CampaignId associated with the notificaiton
pi_pn_campaignName CampaignName associated with the notificaiton
pi_pn_campaignSource CampaignSource associated with the notificaiton

Note: It is essential to have Firebase Messaging implemented to enable support for these properties.

6. Send Event

You can capture event using the following function. Percept automatically generates a unique ID and stores it in local storage or a cookie.

// Track only event-name
percept.capture('Referral Banner Click');

// Track event-name with property
percept.capture('Screen View', {'screenName': 'Homepage'});

// Track handled errors
percept.captureError(error, stackTrace);

After initializing the library, Percept will automatically track some properties by default

7. Set Global Properties

Set global properties which will be passed with all subsequent events

percept.setGlobalProperties({'global-property-key', 'value'});

8. Get all global properties

Get all global properties


9. Clear

Call clear function on logout to delete all user related information


Events auto tracked by sdk

event name parameter key to control description
App Opened autoCaptureAppLifecycleEvents Triggered when percept sdk is initialized
App Active autoCaptureAppLifecycleEvents Triggered when app comes to foreground
App Backgrounded autoCaptureAppLifecycleEvents Triggered when app goes to background
Application Installed autoCaptureAppLifecycleEvents Triggered when app is installed for the first time
Application Updated autoCaptureAppLifecycleEvents Triggered when app is updated

Properties tracked by sdk

Property name Description
pi_app_name Application name
pi_app_version Human friendly app version like "2.3.7"
pi_app_build Build number like "2.3.7" or "237"
pi_os_name Operating system name like iOS or Android
pi_os_version Operating system version "7.1.3"
pi_sdk_type PI sdk type such as Flutter or Native
pi_sdk_version PI sdk version
pi_pn_attribution Tracks if current session is attributed to PN Interaction

Along with other platform specific device info as follows:


Property name Description
pi_systemName The name of the current operating system
pi_systemVersion The current operating system version
pi_model Device model
pi_isPhysicalDevice false if the application is running in a simulator, true otherwise


Property name Description
pi_brand The consumer-visible brand with which the product/hardware will be associated
pi_device The name of the industrial design
pi_hardware The name of the hardware (from the kernel command line or /proc)
pi_manufacturer The manufacturer of the product/hardware
pi_model The end-user-visible name for the end product
pi_product The name of the overall product
pi_isPhysicalDevice false if the application is running in an emulator, true otherwise
pi_systemFeatures Describes what features are available on the current device


If you have any questions, issues, or need assistance with Percept, here are the available support channels:

Please feel free to reach out to us with any concerns or inquiries. We'll do our best to assist you and provide timely support.