matomo-react-native
Version:
Enhanced Matomo tracking library for React Native and Expo projects with TypeScript support and automatic platform detection.
278 lines (277 loc) • 13.1 kB
TypeScript
import { MatomoInitOptions, MatomoUserInfo, MatomoTrackAppStartOptions, MatomoTrackPageViewOptions, MatomoTrackScreenViewOptions, MatomoTrackActionOptions, MatomoTrackEventOptions, MatomoTrackContentOptions, MatomoTrackSiteSearchOptions, MatomoTrackLinkOptions, MatomoTrackDownloadOptions, MatomoTrackReferralUrlOptions, MatomoTrackAdClickOptions, MatomoTrackAdImpressionOptions } from './types';
/**
* Represents a Matomo Tracker for tracking user interactions.
*
* @class
* @param {MatomoInitOptions} userOptions - User configuration options for Matomo tracking.
*/
declare class MatomoTracker {
private disabled;
private log;
private trackerUrl;
private siteId;
private userId?;
private userInfo;
constructor(userOptions: MatomoInitOptions);
/**
* Initializes the MatomoTracker with user options.
*
* @param {MatomoInitOptions} options - Initialization options.
*/
initialize({ urlBase, trackerUrl, siteId, userId, disabled, log }: MatomoInitOptions): void;
/**
* Tracks app start as an action with a prefixed 'App' category.
* Automatically detects platform using React Native Platform.OS when available.
*
* @param {MatomoTrackAppStartOptions} options - Tracking options.
* @returns {Promise<void>} A Promise that resolves when the tracking is complete.
*
* @example
* // Basic app start tracking with automatic platform detection
* trackAppStart();
*
* @example
* // App start with custom referrer and URL
* trackAppStart({
* url: '/app-start',
* referrer: 'https://mywebsite.com',
* platform: 'ios'
* });
*
* @see https://developer.matomo.org/api-reference/tracking-api#optional-user-info for optional data used for tracking different user info
*/
trackAppStart({ url, referrer, platform, userAgent, userInfo }?: MatomoTrackAppStartOptions): Promise<void>;
/**
* Tracks a page view.
*
* This method is used to record page views in your application, providing insights into user navigation.
*
* @param {MatomoTrackPageViewOptions} options - Options for tracking the page view.
* @returns {Promise<void>} A Promise that resolves when the page view tracking is complete.
*
* @example
* // Tracking a page view
* trackPageView({ name: 'Home Page', url: '/home' });
*
* @example
* // Tracking a page view with user information
* trackPageView({ name: 'Product Details', url: '/product/123', userInfo: { uid: '123456' } });
*/
trackPageView({ name, url, userInfo }: MatomoTrackPageViewOptions): Promise<void>;
/**
* Tracks a screen view as an action with the prefixed 'Screen' category.
*
* This method is used to record user interactions with screens or pages in your application.
*
* @param {MatomoTrackScreenViewOptions} options - Options for tracking the screen view.
* @throws {Error} Throws an error if the 'name' parameter is not provided.
* @returns {Promise<void>} A Promise that resolves when the screen view tracking is complete.
*
* @example
* // Tracking a screen view without user information
* trackScreenView({ name: 'Home' });
*
* @example
* // Tracking a screen view with additional user information
* trackScreenView({ name: 'Product Details', userInfo: { uid: '123456' } });
*/
trackScreenView({ name, url, userInfo }: MatomoTrackScreenViewOptions): Promise<void>;
/**
* Tracks a custom action.
*
* This method is used to record user interactions with specific actions in your application.
*
* @param {MatomoTrackActionOptions} options - Options for tracking the action.
* @throws {Error} Throws an error if the 'name' parameter is not provided.
* @returns {Promise<void>} A Promise that resolves when the action tracking is complete.
*
* @example
* // Tracking a custom action without user information
* trackAction({ name: 'ButtonClick' });
*
* @example
* // Tracking a custom action with additional user information
* trackAction({ name: 'AddToCart', userInfo: { uid: '123456'} });
*
* @see {@link https://developer.matomo.org/api-reference/tracking-api#recommended-parameters|Matomo Tracking API - Recommended Parameters}
*/
trackAction({ name, url, userInfo }: MatomoTrackActionOptions): Promise<void>;
/**
* Tracks a custom event.
*
* This method is used to record specific events in your application, providing insights into user interactions.
*
* @param {MatomoTrackEventOptions} options - Options for tracking the event.
* @throws {Error} Throws an error if the 'category' or 'action' parameters are not provided.
* @returns {Promise<void>} A Promise that resolves when the event tracking is complete.
*
* @example
* // Tracking a basic event without additional information
* trackEvent({ category: 'Videos', action: 'Play' });
*
* @example
* // Tracking an event with a name and user information
* trackEvent({ category: 'Music', action: 'Pause', name: 'FavoriteSong', userInfo: { uid: '123456'} });
*
* @see {@link https://developer.matomo.org/api-reference/tracking-api#optional-event-trackinghttpsmatomoorgdocsevent-tracking-info|Matomo Tracking API - Event Tracking}
*/
trackEvent({ category, action, name, value, campaign, url, userInfo }: MatomoTrackEventOptions): Promise<void>;
/**
* Tracks a custom content.
*
* This method is used to record specific content impressions or interactions in your application, providing insights into user interactions.
*
* @param {MatomoTrackContentOptions} options - Options for tracking the content.
* @throws {Error} Throws an error if the 'name' is not provided.
* @returns {Promise<void>} A Promise that resolves when the content tracking is complete.
*
* @example
* // Tracking a basic content impression
* trackContent({ name: "preview-liveboard", piece: "Malaysia", target: "https://dummy.matomo.org/liveboard/malaysia") });
*
* @example
* // Tracking a content interaction with user information
* trackContent({ name: "preview-liveboard", interaction: "tap", piece: "Malaysia", target: "https://dummy.matomo.org/liveboard/malaysia", userInfo: { uid: '123456'} });
*
* @see {@link https://developer.matomo.org/api-reference/tracking-api#optional-content-trackinghttpsmatomoorgdocscontent-tracking-info|Matomo Tracking API - Content Tracking}
*/
trackContent({ contentName, contentPiece, contentTarget, contentInteraction, url, userInfo }: MatomoTrackContentOptions): Promise<void>;
/**
* Tracks a site search.
*
* This method is used to record user searches on your site, providing valuable insights into user behavior.
*
* @param {MatomoTrackSiteSearchOptions} options - Options for tracking the site search.
* @throws {Error} Throws an error if the 'keyword' parameter is not provided.
* @returns {Promise<void>} A Promise that resolves when the site search tracking is complete.
*
* @example
* // Tracking a site search without additional information
* trackSiteSearch({ keyword: 'product' });
*
* @example
* // Tracking a site search with a category, result count, and user information
* trackSiteSearch({ keyword: 'tutorial', category: 'Learning', count: 5, userInfo: { uid: '123456' } });
*
* @see {@link https://developer.matomo.org/api-reference/tracking-api#optional-action-info-measure-page-view-outlink-download-site-search|Matomo Tracking API - Site Search Tracking}
*/
trackSiteSearch({ keyword, category, count, url, userInfo }: MatomoTrackSiteSearchOptions): Promise<void>;
/**
* Tracks clicks on outgoing links.
*
* This method is used to record user interactions when clicking on external links, providing insights into user navigation patterns.
*
* @param {MatomoTrackLinkOptions} options - Options for tracking the link click.
* @throws {Error} Throws an error if the 'link' parameter is not provided.
* @returns {Promise<void>} A Promise that resolves when the link click tracking is complete.
*
* @example
* // Tracking a link click without additional information
* trackLink({ link: 'https://external-site.com' });
*
* @example
* // Tracking a link click with user information
* trackLink({ link: 'https://external-site.com', userInfo: { userId: '123456', userRole: 'visitor' } });
*
* @see {@link https://developer.matomo.org/api-reference/tracking-api#optional-action-info-measure-page-view-outlink-download-site-search|Matomo Tracking API - Outlink Tracking}
*/
trackLink({ link, url, userInfo }: MatomoTrackLinkOptions): Promise<void>;
/**
* Tracks file downloads.
*
* This method is used to record user interactions when downloading files, providing insights into user engagement with downloadable content.
*
* @param {MatomoTrackDownloadOptions} options - Options for tracking the file download.
* @throws {Error} Throws an error if the 'download' parameter is not provided.
* @returns {Promise<void>} A Promise that resolves when the download tracking is complete.
*
* @example
* // Tracking a file download without additional information
* trackDownload({ download: 'https://example.com/files/document.pdf' });
*
* @example
* // Tracking a file download with user information
* trackDownload({ download: 'https://example.com/files/image.png', userInfo: { uid: '123456' } });
*
* @see {@link https://developer.matomo.org/api-reference/tracking-api#optional-action-info-measure-page-view-outlink-download-site-search|Matomo Tracking API - Download Tracking}
*/
trackDownload({ download, url, userInfo }: MatomoTrackDownloadOptions): Promise<void>;
/**
* This method is used to update the user information for tracking for entire instance.
*/
updateUserInfo(newUserInfo: MatomoUserInfo): void;
/**
* This method is used to remove the user information for tracking for entire instance.
*/
removeUserInfo(): void;
/**
* Tracks a referral URL for attribution tracking.
*
* This convenience method tracks where users came from by recording referral information
* as an event with proper campaign attribution.
*
* @param {MatomoTrackReferralUrlOptions} options - Options for tracking the referral.
* @returns {Promise<void>} A Promise that resolves when the referral tracking is complete.
*
* @example
* // Track a referral from social media
* trackReferralUrl({
* referralUrl: 'https://facebook.com/post/123',
* source: 'facebook',
* medium: 'social',
* campaign: 'summer-2024'
* });
*/
trackReferralUrl({ referralUrl, campaign, source, medium, url, userInfo }: MatomoTrackReferralUrlOptions): Promise<void>;
/**
* Tracks an advertisement click.
*
* Uses Matomo's content tracking to record when users click on advertisements,
* providing insights into ad performance and user engagement.
*
* @param {MatomoTrackAdClickOptions} options - Options for tracking the ad click.
* @returns {Promise<void>} A Promise that resolves when the ad click tracking is complete.
*
* @example
* // Track a banner ad click
* trackAdClick({
* adId: 'banner-001',
* adName: 'Summer Sale Banner',
* adSource: 'homepage',
* adCampaign: 'summer-2024',
* targetUrl: 'https://example.com/sale'
* });
*/
trackAdClick({ adId, adName, adSource, adCampaign, targetUrl, url, userInfo }: MatomoTrackAdClickOptions): Promise<void>;
/**
* Tracks an advertisement impression (view).
*
* Records when an advertisement is displayed to users, helping measure
* ad visibility and reach.
*
* @param {MatomoTrackAdImpressionOptions} options - Options for tracking the ad impression.
* @returns {Promise<void>} A Promise that resolves when the ad impression tracking is complete.
*
* @example
* // Track a banner ad impression
* trackAdImpression({
* adId: 'banner-001',
* adName: 'Summer Sale Banner',
* adSource: 'homepage',
* adCampaign: 'summer-2024'
* });
*/
trackAdImpression({ adId, adName, adSource, adCampaign, url, userInfo }: MatomoTrackAdImpressionOptions): Promise<void>;
/**
* Adds common Matomo tracking parameters to improve tracking accuracy
*/
private addCommonParameters;
/**
* Sends the tracking data to Matomo.
*
* @param {Record<string, any>} data - The tracking data.
* @returns {Promise<void>} A Promise that resolves when the tracking data is sent.
*/
private track;
}
export default MatomoTracker;