@sap_oss/automated-usage-tracking-tool

Automated Usage Tracking Tool

About this project

The Automated Usage Tracking Tool is designed to help developers track user interactions within their JavaScript and TypeScript applications using SAP Customer Data Cloud.

By integrating this tool, you can gather insights into how users interact with various features of your application, which can be invaluable for improving user experience and making data-driven decisions.

Key features

• Consent Management: The tool provides built-in methods to request user consent for tracking, ensuring compliance with privacy regulations.
• Feature Usage Tracking: Easily track how often specific features of your application are used.
• Customizable Storage: Optionally specify a custom storage name for tracking data.
• Web and CLI Support: The tool supports both web and command-line interface (CLI) applications.
• Theme Support: For web applications, you can apply the sap_horizon theme to the consent dialog for a consistent look and feel.

Requirements and Setup

• Node.js: Ensure you are using Node.js version 19 or higher.

This tool is ready to use by JavaScript/Typescript client applications after importing and installing it from NPM.

Create a new project

npm init

Install package

Install @sap_oss/automated-usage-tracking-tool as a dependency of the new project

npm install @sap_oss/automated-usage-tracking-tool

Import the package

Import the default artifact

import TrackingTool from '@sap_oss/automated-usage-tracking-tool'

Initialize the tracker

const trackingTool = new TrackingTool({
  apiKey: [apiKey],
  dataCenter: [dataCenter],
  storageName: [storageName], // Optional
})

Request Consent

Ask for consent confirmation or ask the consent question to the user.

Note: If the consent was already granted, the consent dialog will not be shown (no extra validations needed).

await trackingTool.requestConsentConfirmation() // Possible Answer: Yes (or exit app)
// OR
await trackingTool.requestConsentQuestion() // Possible Answers: Yes or No

Track Usages

Track usages of your application features.

Note: If the consent was not granted, the usage will not be tracked (no extra validations needed).

trackingTool.trackUsage({
  toolName: [toolName],
  featureName: [featureName],
})

Themes

For the web version, there is the option to import the sap_horizon theme to be applied to the consent dialog

import '@sap_oss/automated-usage-tracking-tool/theme/sap_horizon.css'

Types

Types are available for Typescript client applications.

import { TrackerArguments, TrackUsageArguments, ConsentArguments } from '@sap_oss/automated-usage-tracking-tool'

Extra: Check If The Consent Was Already Granted

This method is not necessary for the implementation (as this is performed behind the scenes), but it can be used to check if the consent was already granted if you want to use that information in your application.

trackingTool.isConsentGranted()

Usage Examples

In the /examples folder there are available examples of Javascript and Typescript Web and CLI client apps using the tool.

JavaScript CLI Client

This example demonstrates the integration with a JavaScript CLI client application. See examples/javascript-cli-client/README.md for more details.

JavaScript Web Client

This example demonstrates the integration with a JavaScript web client application. See examples/javascript-web-client/README.md for more details.

TypeScript CLI Client

This example demonstrates the integration with a TypeScript CLI client application. See examples/typescript-cli-client/README.md for more details.

TypeScript Web Client (Angular)

This example demonstrates the integration with a TypeScript web client application. See examples/typescript-web-client/README.md for more details.

Support, Feedback, Contributing

This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.

Security / Disclosure

If you find any bug that may be a security problem, please follow our instructions at in our security policy on how to report it. Please do not create GitHub issues for security-related doubts or problems.

Code of Conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright 2024 SAP SE or an SAP affiliate company and automated-usage-tracking-tool contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.