Using Piwik PRO SDK for React Native

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 PiwikProSdk.setAnonymizationState(true);

shouldAnonymize: boolean – 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 path of the screen. This path 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 PiwikProSdk.trackScreen('your_screen_path');

path: string – the screen path. The appropriate URL 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 PiwikProSdk.trackCustomEvent('category', 'action', {
  name: 'name',
  value: 1.5,
});

category: string – 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.).
action: string – this string defines the specific event action within the category specified.
options.name: string (optional) – 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.
options.value: number (optional) – 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.
options.path: string (optional) – the path under which this event occurred.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

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.

To track exceptions you can use the trackException method:

await PiwikProSdk.trackException('description of an exception');

description: string – 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 PiwikProSdk.trackSocialInteraction('like', 'Facebook');

interaction: string – defines the social interaction, e.g. "Like".
network: string – 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 PiwikProSdk.trackDownload('http://your.server.com/bonusmap.zip');

url: string – 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 PiwikProSdk.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 PiwikProSdk.trackApplicationUpdate();

Tracking outlinks

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

await PiwikProSdk.trackOutlink('http://great.website.com');

url: string – 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 PiwikProSdk.trackSearch('Space', { category: 'Movies', count: 100 });

keyword: string – the searched query that was used in the app.
options.category: string (optional) – specify a search category.
options.count: number (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.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

Tracking content impressions

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

await PiwikProSdk.trackImpression('Ad Foo Bar', {
  piece: 'banner',
  target: 'https://example.com/landing',
});

contentName: string – the name of the content, e.g. "Ad Foo Bar".
options.piece: string (optional) – the actual content. For instance the path to an image, video, audio, any text.
options.target: string (optional) – the target of the content e.g. the URL of a landing page.
options.url: string (optional) – the URL associated with the tracked content block.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

Tracking content interactions

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

await PiwikProSdk.trackInteraction('Ad Foo Bar', 'click', {
  piece: 'banner',
  target: 'https://example.com/landing',
});

contentName: string – the name of the content, e.g. "Ad Foo Bar".
interaction: string – a type of interaction that occurred, e.g. "click".
options.piece: string (optional) – the actual content. For instance the path to an image, video, audio, any text.
options.target: string (optional) – the target of the content e.g. the URL of a landing page.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

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 PiwikProSdk.trackGoal('27ecc5e3-8ae0-40c3-964b-5bd8ee3da059', { revenue: 102.2 });

goal: string – a tracking request will trigger a conversion for the goal of the website being tracked with this ID.
options.revenue: number (optional) – a monetary value that has been generated as revenue by goal conversion.
options.currencyCode: string (optional) – the ISO 4217 currency code for the revenue. Example: USD, EUR, PLN.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

Tracking ecommerce product detail view

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

const ecommerceProducts = [
  {
    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%' },
  },
  { sku: 'dert-456' },
];
const options: EcommerceOptions = {
  visitCustomVariables: { 1: { name: 'name', value: 'value' } },
  customDimensions: { 1: 'value', 2: 'value' },
  currencyCode: 'EUR',
};
await PiwikProSdk.trackEcommerceProductDetailView(ecommerceProducts, options);

products: EcommerceProduct[] – the products list.
options.currencyCode: string (optional) – the ISO 4217 currency code for the product prices. Example: USD, EUR, PLN.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

Each EcommerceProduct has the following attributes:

sku: string – stock-keeping unit.
name: string (optional, default: "") – product name.
category: string[] (optional, default: "") – up to 5 categories.
price: string (optional, default: 0) – product price.
quantity: number (optional, default: 1) – quantity.
brand: string (optional, default: "") – brand name.
variant: string (optional, default: "") – variant.
customDimensions: object (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:

const options: EcommerceOptions = {
  visitCustomVariables: { 1: { name: 'name', value: 'value' } },
  customDimensions: { 1: 'value', 2: 'value' },
  currencyCode: 'EUR',
};
await PiwikProSdk.trackEcommerceAddToCart(ecommerceProducts, options);

products: EcommerceProduct[] – the products list.
options.currencyCode: string (optional) – the ISO 4217 currency code for the product prices. Example: USD, EUR, PLN.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

Tracking ecommerce remove from cart

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

const options: EcommerceOptions = {
  visitCustomVariables: { 1: { name: 'name', value: 'value' } },
  customDimensions: { 1: 'value', 2: 'value' },
  currencyCode: 'EUR',
};
await PiwikProSdk.trackEcommerceRemoveFromCart(ecommerceProducts, options);

products: EcommerceProduct[] – the products list.
options.currencyCode: string (optional) – the ISO 4217 currency code for the product prices. Example: USD, EUR, PLN.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

Tracking ecommerce cart update

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

const options: EcommerceOptions = {
  visitCustomVariables: { 1: { name: 'name', value: 'value' } },
  customDimensions: { 1: 'value', 2: 'value' },
  currencyCode: 'EUR',
};
await PiwikProSdk.trackEcommerceCartUpdate(ecommerceProducts, '6000.43', options);

products: EcommerceProduct[] – the products list.
grandTotal: string – the total value of items in the cart.
options.currencyCode: string (optional) – the ISO 4217 currency code for the product prices. Example: USD, EUR, PLN.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

Tracking ecommerce order

You can track a completed order using the trackEcommerceOrder method:

await PiwikProSdk.trackEcommerceOrder('order-3415', '10000', ecommerceProducts, {
  subTotal: '120.00',
  tax: '39.60',
  shipping: '60.00',
  discount: '18.00',
});

orderId: string – a unique string identifying the order.
grandTotal: string – the total amount of the order.
products: EcommerceProduct[] – the items included in the order.
options.subTotal: string (optional) – the subtotal (net price) for the order.
options.tax: string (optional) – the tax for the order.
options.shipping: string (optional) – the shipping for the order.
options.discount: string (optional) – the discount for the order.
options.currencyCode: string (optional) – the ISO 4217 currency code for the order. Example: USD, EUR, PLN.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

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, shipping, discount and a list of purchased items.

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

const items = [
  { sku: '0123456789012', category: "Men's T-shirts", name: 'Polo T-shirt', price: 3000, quantity: 2 },
];
await PiwikProSdk.trackEcommerce('order_1', 124144, {
  subTotal: 33110,
  tax: 9890,
  shipping: 1000,
  discount: 0,
  items,
});

orderId: string – a unique string identifying the order.
grandTotal: number – the total amount of the order, in cents.
options.subTotal: number (optional) – the subtotal (net price) for the order, in cents.
options.tax: number (optional) – the tax for the order, in cents.
options.shipping: number (optional) – the shipping for the order, in cents.
options.discount: number (optional) – the discount for the order, in cents.
options.items (optional) – the items included in the order.
options.customDimensions (optional) – an object specifying custom dimensions.
options.visitCustomVariables (optional) – an object specifying visit custom variables.

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. 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 PiwikProSdk.trackCampaign('http://example.org/offer.html?pk_campaign=Email-SummerDeals&pk_keyword=LearnMore');

url: string – 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.

A custom variable is a custom name-value pair that you can assign to your users or screen views. A custom variable can have a visit scope (assigned to the whole visit) or a screen scope (assigned only to a tracked screen view). It is required for names and values to be encoded in UTF-8.

In React Native SDK, custom variables are passed as the visitCustomVariables or screenCustomVariables option object to tracking methods:

await PiwikProSdk.trackScreen('your_screen_path', {
  screenCustomVariables: { 4: { name: 'food', value: 'pizza' } },
  visitCustomVariables: { 5: { name: 'drink', value: 'water' } },
});

index: number – 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 a new custom variable stored in index 1. Some indexes (1-3) are reserved by default — see Default custom variables.
name: string – the name of a specific custom variable such as User type. Limited to 200 characters.
value: string – the value of a specific custom variable such as Customer. Limited to 200 characters.

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.

In React Native SDK, custom dimensions are passed as the customDimensions option object to tracking methods:

await PiwikProSdk.trackScreen('your_screen_path', {
  customDimensions: { 1: 'english', 2: 'premium' },
});

index: number – the dimension slot ID configured in the Piwik PRO panel.
value: string – the value of a specific custom dimension. Limited to 1024 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 trackProfileAttributes method:

await PiwikProSdk.trackProfileAttributes([
  { name: 'food', value: 'pizza' },
  { name: 'drink', value: 'water' },
]);

profileAttributes – an object or array of objects with two required properties:
- name: string – profile attribute name.
- value: string – the profile attribute value.

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 getProfileAttributes method:

const attributes = await PiwikProSdk.getProfileAttributes();

Returns an object – 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:

const isMember = await PiwikProSdk.checkAudienceMembership('audienceId');

audienceId: string – ID of the audience (Audience Manager -> Audiences tab).

Returns a boolean – true if a user is a member of an audience, false otherwise.