Isomorphic JS/TS tracking agent for Bucket.co
The library can be included directly as an external script or you can import it.
A. Script tag (client-side directly in html)
<script src="https://cdn.jsdelivr.net/npm/@bucketco/tracking-sdk@1"></script>B. Import module (in either node or browser bundling)
import bucket from "@bucketco/tracking-sdk";
// or
var bucket = require("@bucketco/tracking-sdk");Other languages than Javascript/Typescript are currently not supported by an SDK. You can use the HTTP API directly
// init the script with your Tracking Key
bucket.init("tk123", {});
// set current user
bucket.user("john_doe", { name: "John Doe" });
// set current company
bucket.company("acme_inc", { name: "Acme Inc", plan: "pro" }, "john_doe");
// track events
bucket.track("sent_message", { foo: "bar" }, "john_doe", "company_id");
// collect qualitative feedback
bucket.feedback({
featureId: "my_feature_id",
userId: "john_doe",
companyId: "acme_inc", // String (optional)
score: 5, // Number: 1-5 (optional)
comment: "Absolutely stellar work!" // String (optional)
})NOTE: When used in the browser, you can omit the 3rd argument (userId) to the company and track methods. See persisting users for more details.
Supply these to the init call (2nd argument)
{
debug?: false, // enable debug mode to log all info and errors
persistUser?: true | false // default value depends on environment, see below under "persisting users"
host?: "https://tracking.bucket.co", // don't change this
}Bucket can collect qualitative feedback from your users in the form of a Customer Satisfaction Score and a comment.
Feedback can be submitted to Bucket using the SDK:
bucket.feedback({
featureId: "my_feature_id", // String (required), copy from Feature feedback tab
userId: "john_doe", // String, optional if using user persistence
companyId: "acme_inc", // String (optional)
score: 5, // Number: 1-5 (optional)
comment: "Absolutely stellar work!" // String (optional)
})If you are not using the Bucket SDK, you can still submit feedback using the HTTP API.
See details in Feedback HTTP API
In order to collect feedback from a customer, you might want to build your own UI that matches your own style guide.
We have built a few scaffolds you can get started with easily:
The Bucket SDK doesn't collect any metadata and HTTP IP addresses are not being stored.
For tracking individual users, we recommend using something like database ID as userId, as it's unique and doesn't include any PII (personal identifiable information). If, however, you're using e.g. email address as userId, but prefer not to send any PII to Bucket, you can hash the sensitive data before sending it to Bucket:
import bucket from "@bucketco/tracking-sdk";
import { sha256 } from 'crypto-hash';
bucket.user(await sha256("john_doe"));
You can pass attributes as a object literal to the user, company and track methods (2nd argument).
Attributes cannot be nested (multiple levels) and must be either strings, integers or booleans.
Built-in attributes:
name(display name for user/company)
Usage in the browser (imported or script tag):
Once you call user, the userId will be persisted so you don't have to supply userId to each subsequent company and track calls.
This is practical for client-side usage where a session always is a single user.
Usage in node.js
User persistence is disabled by default when imported in node.js to avoid that companies or events are tied to the wrong user by mistake. This is because your server is (usually) not in a single user context.
Instead, you should provide the userId to each call, as the 3rd argument to company and track.
Types are bundled together with the library and exposed automatically when importing through a package manager.
MIT License
Copyright (c) 2023 Bucket ApS