percept_flutter

Description:

percept flutter

Percept-flutter #
Introducing the official Percept Flutter SDK
Getting Started #
1. Install #

Add the following lines to your package's pubspec.yaml file to include the dependency:

dependencies:
percept_flutter: ^2.0.1
copied to clipboard

To install the package, use the following command in your command line interface:

$ flutter pub get
copied to clipboard

Import the package in your Dart code to make it available for use:

import 'package:percept_flutter/percept_flutter.dart'
copied to clipboard
2. Initialize Percept SDK #
import 'package:percept_flutter/percept_flutter.dart'

class YourClassState extends State<YourClass> {
Percept percept;

@override
void initState() {
super.initState();
percept=Percept(token)
}
}
copied to clipboard
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


enableExperiment
Enables or disables the experiment feature within the service
false


experimentFetchedCb
A callback function that is triggered when experiment data is fetched
undefined


experimentRefetchIntervalMin
The interval, in minutes, at which the experiment data is refetched
undefined



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: {UserProperty.name:"TestUser"}, additionalProperties: {"isVerifiedAccount": true})
copied to clipboard
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})
copied to clipboard
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.getToken()
copied to clipboard
or
FirebaseMessaging.instance.onTokenRefresh.listen((token) => { });
copied to clipboard

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

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) {
_percept.trackPNTerminated(initialMessage.toMap());
}
copied to clipboard

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.
FirebaseMessaging.onMessageOpenedApp.listen(
(message) => _percept.trackPNBackground(message.toMap()),
);
copied to clipboard

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.
FirebaseMessaging.onMessage.listen(
(message) => _percept.trackPNForeground(message.toMap()),
);
copied to clipboard

Notifying SDK when notification received in terminated state for better attribution

Register the handler before calling runApp. Details for background fcm message handling-> https://firebase.google.com/docs/cloud-messaging/flutter/receive#background_messages
import 'package:percept_flutter/constants.dart';
import 'package:percept_flutter/utils/comm_helpers.dart';

@pragma('vm:entry-point')
Future<void> bgMessageHandler(RemoteMessage message) async {
CapturePerceptCommRequest(
PerceptCommunicationState.received, message.toMap(), PERCEPT_TEST_KEY);
}

void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp(options: DefaultOptions.currentPlatform);
FirebaseMessaging.onBackgroundMessage(bgMessageHandler);
runApp(MyApp());
}
copied to clipboard
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);
copied to clipboard
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'});
copied to clipboard
8. Get all global properties #
Get all global properties
percept.getGlobalProperties();
copied to clipboard
9. Clear #
Call clear function on logout to delete all user related information
percept.clear()
copied to clipboard
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:
IOS:



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



Android:



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



Handling Experiments #
1. Enabling Experiments #
To enable experiment tracking, set the enableExperiment option to true in the initOptions. You can also specify a callback function to handle the experiment data when it is fetched.
final initOptions = InitOptions(
enableExperiment: true,
experimentFetchedCb: (data) {
final experimentData = data['experimentData'];
final experimentUserType = data['experimentUserType'];
final isExperimentDataResolved = data['isExperimentDataResolved'];

if (isExperimentDataResolved) {
print('Experiment data fetched: $experimentData');
} else {
print('Experiment data could not be resolved.');
}
},
experimentRefetchIntervalMin: 10, // Refetch experiment data every 10 minutes
);

Percept('Your Project Token', initOptions);
copied to clipboard
Note: The experimentRefetchIntervalMin option sets the interval in minutes for automatically refetching experiment data. The interval must be at least 5 minutes. If a value less than 5 is provided, it will be automatically set to 5 minutes and a warning will be logged.
2. Fetching Experiment Data #
You can fetch experiment data at any time using the getExperiment method. This method returns a Future that resolves to the variant data for the specified experiment.
final experimentName = 'example-experiment';
final variant = await percept.getExperiment(experimentName);

if (variant) {
print('User is in variant: $variant');
} else {
print('No variant data available');
}
copied to clipboard
3. Refetching Experiment Data #
If you have set the experimentRefetchIntervalMs option, the SDK will automatically refetch the experiment data at the specified interval. You can also manually refetch the experiment data using the refetchExperiment method.
await percept.refetchExperiment();
copied to clipboard
4. Getting All Active Experiments #
You can get all active experiments and their variants using the getAllActiveExperiments method.
final activeExperiments = await percept.getAllActiveExperiments();
print('Active experiments:', activeExperiments);
copied to clipboard
5. Getting Experiment User Type #
You can get the user type for experiments using the getExperimentUserType method.
final userType = await percept.getExperimentUserType();
print('Experiment user type:', userType);
copied to clipboard
Support #
If you have any questions, issues, or need assistance with Percept, here are the available support channels:

GitHub Issues: Project Issues

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.