Docs

Using Piwik PRO SDK for Flutter

Data anonymization

Anonymization is a feature that allows tracking a user's activity for aggregated data analysis even if the user doesn't consent to track the data. If a user does not agree to being tracked, he will not be identified as the same person across multiple sessions.

Personal data will not be tracked during the session (i.e. user ID). If the anonymization is enabled, a new visitor ID will be created each time the application starts.

Anonymization is enabled by default.

You can turn the anonymization on and off by calling setAnonymizationState:

await FlutterPiwikPro.sharedInstance.setAnonymizationState(true);
  • bool shouldAnonymize - pass true to enable anonymization, or false to disable it.

Tracking screen views

The basic functionality of the SDK is tracking screen views which represent the content the user is viewing in the application. To track a screen you only need to provide the name of the screen. This name is internally translated by the SDK to an HTTP URL as the Piwik PRO server uses URLs for tracking views. Additionally, Piwik PRO SDK uses prefixes which are inserted in generated URLs for various types of action(s).

To track screen views you can use the trackScreen method:

await FlutterPiwikPro.sharedInstance.trackScreen(screenName: "menuScreen");
  • String screenName – title of the action being tracked. The appropriate screen path will be generated for this action.

Tracking custom events

Custom events can be used to track the user's interaction with various custom components and features of your application, such as playing a song or a video. You can read more about events in the Piwik PRO documentation and ultimate guide to event tracking.

To track custom events you can use the trackCustomEvent method:

await FlutterPiwikPro.sharedInstance.trackCustomEvent(
    action: 'test action',
    category: 'test category',
    name: 'test name',
    value: 120);
  • String category – this String defines the event category. You may define event categories based on the class of user actions (e.g. taps, gestures, voice commands), or you may define them based upon the features available in your application (e.g. play, pause, fast forward, etc.).
  • String action – this String defines the specific event action within the category specified. In the example, we are essentially saying that the category of the event is user clicks, and the action is a button click.
  • String? name (optional) – this String defines a label associated with the event. For example, if you have multiple button controls on a screen, you might use the label to specify the specific identifier of a button that was clicked.
  • double? value (optional) – this Float defines a numerical value associated with the event. For example, if you were tracking "Buy" button clicks, you might log the number of items being purchased, or their total cost.
  • String? path (optional, Android only) – the path under which this event occurred.

Tracking exceptions

Tracking exceptions allow the measurement of exceptions and errors in your app. Exceptions are tracked on the server in a similar way as screen views, however, URLs internally generated for exceptions always use the fatal or caught prefix.

To track exceptions you can use the trackException method:

await FlutterPiwikPro.sharedInstance.trackException(description: "description of an exception");
  • String description – provides the exception message.

Tracking social interactions

Social interactions such as likes, shares and comments in various social networks can be tracked as below. This is tracked in a similar way as screen views.

To track social interactions you can use the trackSocialInteraction method:

await FlutterPiwikPro.sharedInstance.trackSocialInteraction(
    interaction: 'like',
    network: 'Facebook');
  • String interaction – defines the social interaction, e.g. "Like".
  • String network – defines the social network associated with interaction, e.g. "Facebook".

Tracking downloads

You can track downloads initiated by your application by using the trackDownload method:

await FlutterPiwikPro.sharedInstance.trackDownload('http://your.server.com/bonusmap2.zip');
  • String url – URL of the downloaded content.

Tracking application installs

You can also track installations of your application. This event is sent to the server only once per application version (additional events won't be sent).

You can track app installs using the trackApplicationInstall method:

await FlutterPiwikPro.sharedInstance.trackApplicationInstall();

Tracking application updates

You can track updates of your application. This event is sent the first time a new version of the app is launched, once per update.

You can track app updates using the trackApplicationUpdate method:

await FlutterPiwikPro.sharedInstance.trackApplicationUpdate();

Tracking outlinks

For tracking outlinks to external websites or other apps opened from your application you can use the trackOutlink method:

await FlutterPiwikPro.sharedInstance.trackOutlink('http://great.website.com');
  • String url – defines the outlink target. HTTPS, HTTP and FTP are valid.

Tracking search operations

Tracking search operations allow the measurement of popular keywords used for various search operations performed inside your application. To track them you can use the trackSearch method:

await FlutterPiwikPro.sharedInstance.trackSearch(keyword: 'Space', category: "Movies", numberOfHits: 100);
  • String keyword – the searched query that was used in the app.
  • String? category (optional) – specify a search category.
  • int? numberOfHits (optional) – we recommend setting the search count to the number of search results displayed on the results page. When keywords are tracked with a count of 0, they will appear in the "No Result Search Keyword" report.

Tracking content impressions

You can track the impression of an ad using the trackContentImpression method:

await FlutterPiwikPro.sharedInstance.trackContentImpression(
    contentName: "name",
    piece: 'contentPiece',
    target: 'contentTarget');
  • String contentName – the name of the content, e.g. "Ad Foo Bar".
  • String? piece (optional) – the actual content. For instance the path to an image, video, audio, any text.
  • String? target (optional) – the target of the content e.g. the URL of a landing page.

Tracking content interactions

When a user interacts with an ad by tapping on it, you can track it using the trackContentInteraction method:

await FlutterPiwikPro.sharedInstance.trackContentInteraction(
    contentName: "name",
    contentInteraction: 'Clicked really hard',
    piece: 'contentPiece',
    target: 'contentTarget');
  • String contentName – the name of the content, e.g. "Ad Foo Bar".
  • String contentInteraction (required) – a type of interaction that occurred, e.g. "tap".
  • String? piece (optional) – the actual content. For instance the path to an image, video, audio, any text.
  • String? target (optional) – the target of the content e.g. the URL of a landing page.

Tracking goals

Goal tracking is used to measure and improve your business objectives. To track goals, you first need to configure them on the server in your web panel. Goals such as, for example, subscribing to a newsletter can be tracked as below with the goal ID that you will see on the server after configuring the goal and optional revenue. The currency for the revenue can be set in the Piwik PRO Analytics settings. You can read more about goals here.

To track goals you can use the trackGoal method:

await FlutterPiwikPro.sharedInstance.trackGoal(goal: "27ecc5e3-8ae0-40c3-964b-5bd8ee3da059", revenue: 102.2);
  • String goal – a tracking request will trigger a conversion for the goal of the website being tracked with this ID.
  • double? revenue (optional) – a monetary value that has been generated as revenue by goal conversion.

Tracking ecommerce product detail view

You can track when a user views a product page using the trackEcommerceProductDetailView method:

final ecommerceProducts = [
    EcommerceProduct(sku: 'craft-311',
        name: 'Unicorn Iron on Patch',
        category: ['Crafts & Sewing', 'Toys'],
        price: '49.90',
        quantity: 3,
        brand: 'DMZ',
        variant: 'blue',
        customDimensions: {1: 'coupon-2020', 2: '20%'}),
    EcommerceProduct(sku: 'dert-456')
];
await FlutterPiwikPro.sharedInstance.trackEcommerceProductDetailView(
    products: ecommerceProducts,
);
  • List<EcommerceProduct> products – the products list.

Each EcommerceProduct has the following attributes:

  • String sku – stock-keeping unit.
  • String? name (optional, default: "") – product name.
  • List<String>? category (optional, default: "") – up to 5 categories.
  • String? price (optional, default: 0) – product price.
  • int? quantity (optional, default: 1) – quantity.
  • String? brand (optional, default: "") – brand name.
  • String? variant (optional, default: "") – variant.
  • Map<int, String>? customDimensions (optional, default: ) – max 20 custom product dimensions.

Tracking ecommerce add to cart

You can track when a user adds a product to the cart using the trackEcommerceAddToCart method:

await FlutterPiwikPro.sharedInstance.trackEcommerceAddToCart(
    products: ecommerceProducts,
);
  • List<EcommerceProduct> products – the products list.

Tracking ecommerce remove from cart

You can track when a user removes a product from the cart using the trackEcommerceRemoveFromCart method:

await FlutterPiwikPro.sharedInstance.trackEcommerceRemoveFromCart(
    products: ecommerceProducts,
);
  • List<EcommerceProduct> products – the products list.

Tracking ecommerce cart update

You can track the current state of the cart using the trackEcommerceCartUpdate method:

await FlutterPiwikPro.sharedInstance.trackEcommerceCartUpdate(
    grandTotal: '6000.43',
    products: ecommerceProducts,
);
  • String grandTotal – the total value of items in the cart.
  • List<EcommerceProduct> products – the products list.

Tracking ecommerce order

You can track a completed order using the trackEcommerceOrder method:

await FlutterPiwikPro.sharedInstance.trackEcommerceOrder(
    identifier: 'order-3415',
    grandTotal: '10000',
    subTotal: '120.00',
    tax: '39.60',
    shippingCost: '60.00',
    discount: '18.00',
    products: ecommerceProducts,
);
  • String identifier – a unique string identifying the order.
  • String grandTotal – the total amount of the order.
  • String? subTotal (optional) – the subtotal (net price) for the order.
  • String? tax (optional) – the tax for the order.
  • String? shippingCost (optional) – the shipping for the order.
  • String? discount (optional) – the discount for the order.
  • List<EcommerceProduct>? products (optional) – the items included in the order.

Tracking ecommerce transactions

❗️

Deprecated

Tracking ecommerce transactions is deprecated and will be replaced by ecommerce order.

Ecommerce transactions (in-app purchases) can be tracked to help you improve your business strategy. To track a transaction you must provide two required values - the transaction identifier and grandTotal. Optionally, you can also provide values for subTotal, tax, shippingCost, discount and list of purchased items.

To track an ecommerce transaction you can use the trackEcommerceTransaction method:

final ecommerceTransactionItems = [
    EcommerceTransactionItem(category: 'cat1', sku: 'sku1', name: 'name1', price: 20, quantity: 1),
    EcommerceTransactionItem(category: 'cat2', sku: 'sku2', name: 'name2', price: 10, quantity: 1),
    EcommerceTransactionItem(category: 'cat3', sku: 'sku3', name: 'name3', price: 30, quantity: 2),
];
await FlutterPiwikPro.sharedInstance.trackEcommerceTransaction(
    identifier: "transactionID",
    grandTotal: 100,
    subTotal: 10,
    tax: 5,
    shippingCost: 100,
    discount: 6,
    transactionItems: ecommerceTransactionItems,
);
  • String identifier – a unique string identifying the order.
  • int grandTotal – the total amount of the order, in cents.
  • int? subTotal (optional) – the subtotal (net price) for the order, in cents.
  • int? tax (optional) – the tax for the order, in cents.
  • int? shippingCost (optional) – the shipping for the order, in cents.
  • int? discount (optional) – the discount for the order, in cents.
  • List<EcommerceTransactionItem>? transactionItems (optional) – the items included in the order.

Tracking campaigns

Tracking campaign URLs created with the online Campaign URL Builder tool allow you to measure how different campaigns (for example with Facebook ads or direct emails) bring traffic to your application. You can register a custom URL schema in your project settings to launch your application when users tap on the campaign link. You can track these URLs from the application delegate as below. The campaign information will be sent to the server together with the next analytics event. More details about campaigns can be found in the documentation.

To track a campaign you can use the trackCampaign method:

await FlutterPiwikPro.sharedInstance.trackCampaign("http://example.org/offer.html?pk_campaign=Email-SummerDeals&pk_keyword=LearnMore");
  • String url – the campaign URL. HTTPS, HTTP and FTP are valid - the URL must contain a campaign name and keyword parameters.

Tracking custom variables

❗️

Deprecated

The custom variables feature will soon be disabled. We recommend using custom dimensions instead.

To track custom name-value pairs assigned to your users or screen views, you can use custom variables. A custom variable can have a visit scope, which means that they are assigned to the whole visit of the user or action scope meaning that they are assigned only to the next tracked action such as screen view. It is required for names and values to be encoded in UTF-8.

You can add a custom variable using the trackCustomVariable method:

await FlutterPiwikPro.sharedInstance.trackCustomVariable(
    index: 1,
    name: 'filter',
    value: 'lcd',
    scope: CustomVariableScope.visit);
  • int index – a given custom variable name must always be stored in the same "index" per session. For example, if you choose to store the variable name = "Gender" in index = 1 and you record another custom variable in index = 1, then the "Gender" variable will be deleted and replaced with new custom variable stored in index 1. Please note that some of the indexes are already reserved. See Default custom variables section for details.
  • String name – this String defines the name of a specific Custom Variable such as "User type". Limited to 200 characters.
  • String value – this String defines the value of a specific Custom Variable such as "Customer". Limited to 200 characters.
  • CustomVariableScope scope – this String allows the specification of the tracking event type - "visit", "action", etc. The scope is the value from the enum CustomVariableScope and can be visit or action.

Tracking custom dimensions

You can also use custom dimensions to track custom values. Custom dimensions first have to be defined on the server in your web panel. More details about custom dimensions can be found in the documentation.

You can add a custom dimension using the trackCustomDimension method:

await FlutterPiwikPro.sharedInstance.trackCustomDimension(index: 1, value: 'english');
  • int index – a given custom dimension must always be stored in the same "index" per session, similar to custom variables. In example 1 is our dimension slot.
  • String value – this String defines the value of a specific custom dimension such as "English". Limited to 200 characters.

Tracking profile attributes

Requires Audience Manager

⚠️

Audience Manager is deprecated and will be replaced by Customer Data Platform module.

The Audience Manager stores visitors' profiles, which have data from a variety of sources. One of them can be a mobile application. It is possible to enrich the profiles with more attributes by passing any key-value pair like gender: male, favourite food: Italian, etc. It is recommended to set additional user identifiers such as email or User ID. This will allow the enrichment of existing profiles or merging profiles rather than creating a new profile. For example, if the user visited the website, browsed or filled in a form with his/her email (his data was tracked and profile created in Audience Manager) and, afterwards started using a mobile application, the existing profile will be enriched only if the email was set. Otherwise, a new profile will be created.

To set profile attributes you can use the trackProfileAttribute method:

await FlutterPiwikPro.sharedInstance.trackProfileAttribute(name: 'food', value: 'chips');
  • String name – defines profile attribute name (non-null string).
  • String value – defines profile attribute value (non-null string).

Aside from attributes, each event also sends parameters which are retrieved from the tracker instance:

  • WEBSITE_ID – always sent.
  • USER_ID – if set.
  • EMAIL – if set.
  • VISITOR_ID – always sent, ID of the mobile application user, generated by the SDK.
  • DEVICE_ID – Advertising ID that, by default, is fetched automatically when the tracker instance is created (only on Android).

Reading user profile attributes

Requires Audience Manager

⚠️

Audience Manager is deprecated and will be replaced by Customer Data Platform module.

It is possible to read the attributes of a given profile, however, with some limitations. Due to security reasons to avoid personal data leakage, it is possible to read only attributes that were enabled for API access (whitelisted) in the Attributes section of Audience Manager.

To get user profile attributes you can use the readUserProfileAttributes method:

await FlutterPiwikPro.sharedInstance.readUserProfileAttributes();

Returns Future<Map<String, String>> – a map of key-value pairs, where each pair represents attribute name (key) and value.

Checking audience membership

Requires Audience Manager

⚠️

Audience Manager is deprecated and will be replaced by Customer Data Platform module.

Checking audience membership allows one to check if the user belongs to a specific group of users defined in the Audience Manager panel based on analytics data and audience manager profile attributes. You can check if a user belongs to a given audience, for example, to display him/her some type of special offer.

You can check audience membership using the checkAudienceMembership method:

await FlutterPiwikPro.sharedInstance.checkAudienceMembership('audienceId');
  • String audienceId – ID of the audience (Audience Manager -> Audiences tab).

Returns Future<bool> – true if a user is a member of an audience, false otherwise.

Updated 4 days ago