Skip to main content

Flutter

Percept Flutter SDK

Getting Started​

1. Install​

  1. Add the following lines to your package's pubspec.yaml file to include the dependency:
dependencies:
percept_flutter: ^1.2.0
  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;

@override
void initState() {
super.initState();
percept=Percept(token)
}
}

Percept constructor takes some optional parameters which are as follows:

Parameter NameDescriptionDefault Value
autoCaptureAppLifecycleEventsAuto track app life cycle events or nottrue
autoCaptureUnhandledErrorsAuto track unhandled errorstrue
maxBatchSizeDefault batch size of event requests100
maxDelayMinsMaximum interval between retry requests in case of failure30 min
maxCacheSizeMbMaximum cache size used to store failed requests10 mb
clearAfterDaysDays after which stored failed requests are deleted in case of retry failure7 days
enableExperimentEnables or disables the experiment feature within the servicefalse
experimentFetchedCbA callback function that is triggered when experiment data is fetchedundefined
experimentRefetchIntervalMinThe interval, in minutes, at which the experiment data is refetchedundefined

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})

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 NameDescription
userIdUserId associated with the user
namename of the user
phonePhone number associated with the user
emailEmail ID associated with the user
deviceTokenFCM token for the device

To get your firebase token you can use:

FirebaseMessaging.instance.getToken()

or

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) {
_percept.trackPNTerminated(initialMessage.toMap());
}
  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.
FirebaseMessaging.onMessageOpenedApp.listen(
(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.
FirebaseMessaging.onMessage.listen(
(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-> 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());
}

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

pi_pn_attributionDescription
terminatedInteraction with pn initiated current app session from terminated state
backgroundInteraction with pn resumed current app session from background state
foregroundNotification was received when the app was in foreground state
noneCurrent session is not attributed to any pn

Along with pi_pn_attribution property following properties are tracked:

Property_nameDescription
pi_pn_targetUrlTargetUrl in the notification payload
pi_pn_campaignIdCampaignId associated with the notificaiton
pi_pn_campaignNameCampaignName associated with the notificaiton
pi_pn_campaignSourceCampaignSource 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

percept.getGlobalProperties();

9. Clear​

Call clear function on logout to delete all user related information

percept.clear()

Events auto tracked by sdk​

event nameparameter key to controldescription
App OpenedautoCaptureAppLifecycleEventsTriggered when percept sdk is initialized
App ActiveautoCaptureAppLifecycleEventsTriggered when app comes to foreground
App BackgroundedautoCaptureAppLifecycleEventsTriggered when app goes to background
Application InstalledautoCaptureAppLifecycleEventsTriggered when app is installed for the first time
Application UpdatedautoCaptureAppLifecycleEventsTriggered when app is updated

Properties tracked by sdk​

Property nameDescription
pi_app_nameApplication name
pi_app_versionHuman friendly app version like "2.3.7"
pi_app_buildBuild number like "2.3.7" or "237"
pi_os_nameOperating system name like iOS or Android
pi_os_versionOperating system version "7.1.3"
pi_sdk_typePI sdk type such as Flutter or Native
pi_sdk_versionPI sdk version
pi_pn_attributionTracks if current session is attributed to PN Interaction

Along with other platform specific device info as follows:

IOS:

Property nameDescription
pi_systemNameThe name of the current operating system
pi_systemVersionThe current operating system version
pi_modelDevice model
pi_isPhysicalDevicefalse if the application is running in a simulator, true otherwise

Android:

Property nameDescription
pi_brandThe consumer-visible brand with which the product/hardware will be associated
pi_deviceThe name of the industrial design
pi_hardwareThe name of the hardware (from the kernel command line or /proc)
pi_manufacturerThe manufacturer of the product/hardware
pi_modelThe end-user-visible name for the end product
pi_productThe name of the overall product
pi_isPhysicalDevicefalse if the application is running in an emulator, true otherwise
pi_systemFeaturesDescribes 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);

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');
}

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();

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);

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);

Support​

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.