JS SDK

Use the Logspot JS SDK in web applications built with React, Next.js, Angular, etc.

Logspot SDK for browser applications built with React, Next.js, Angular, etc.

Installation

npm install @logspot/web

yarn add @logspot/web

Init

import Logspot from '@logspot/web';

Logspot.init({ publicKey: 'YOUR_PUBLIC_KEY' });

publicKey - project public key
cookiesDisabled - use this property to disable anonymous user tracking
cookieDomain - use this property to set root domain (cross-domain tracking)
cookieExpirationInSeconds - how long the anonymous id persists. Default ~12 months, chosen to respect most privacy laws and regulations. Shorten it if you operate in regions that restrict the consent window further (some require as little as 6 months).
enableAutoPageviews - enable auto tracking of pageviews (default: true)
enableAutoClicks - enable auto capture of user clicks (default: false)
stickyCampaigns - remember first-visit campaign parameters for later events (default: false). See Campaign Tracking
consentBehavior - default consent state: notRequired (default), implied, or express. See Consent Management
consentSources - read consent from a connected CMP, e.g. ['onetrust']. See Consent Management
externalApiUrl - API proxy url. Per-endpoint overrides are also available: identifyApiUrl, consentApiUrl, and groupApiUrl.
onLoad - callback function to perform actions when Logspot is loaded. E.g. register super properties before initial pageview
eventMapper - callback function which maps tracking payload to a new payload. With it, you can adjust Logspot's events to your needs.

Track

Logspot.track({
  event: 'UserSubscribed',
  userId: 'john@doe.com',
  metadata: { additionalData: '123' },
});

Parameters:

event - event name e.g. GroupCreated
userId (optional) - unique user id which will link the event to a specific user. It can be integer, UUID or even an email.
groupId (optional) - associate the event (and user) with an account, e.g. a company domain.
groupType (optional) - group type for groupId; defaults to company.
metadata (optional) - you can attach a JSON object to your event.
notify (optional) - deprecated and being sunset. Accepted for backwards compatibility, but nothing reads it. To send a notification when an event arrives, create a Send Notification action.
message (optional | max 350 chars) - a short string shown alongside the event.

Maximum size of the payload is 3kB.

Track Using CSS Classes

You can also track clicks on your website by using lgspt- classname. All clicks will be automatically tracked. The event name will be fetched from the classname.

<button class="my-class other-class lgspt-sign-up">Sign up</button>

Above click will result in the Sign Up event.

Identify

Link an anonymous visitor to a known user once they sign up or log in. See Identifying Users.

Logspot.identify('user_123', { email: 'jane@acme.com', name: 'Jane Doe' });

userId - your stable user id.
traits (optional) - properties stored on the identity.
options (optional) - pass { identityVerification: { token } } when Secure Mode is enabled.

Call Logspot.reset() on logout to clear the identified user and start a fresh anonymous id.

Group

Associate the current visitor with an account (a company, workspace, or any group type) without sending an event. See Groups & Companies.

Logspot.group('acme.com', { name: 'Acme, Inc.', plan: 'enterprise' });

groupId - a stable key for the account (a domain like acme.com is common).
traits (optional) - properties stored on the account.
options (optional) - pass { type: 'workspace' } for a group type other than the default company.

It binds to the identified user when known, otherwise to the current anonymous id (promoted to the person on the next identify).

Pageview

Pageviews are sent automatically when enableAutoPageviews is on. To send one manually:

Logspot.pageview();

Revenue

Record a payment so revenue is tied to the user, account, and marketing source. See Revenue Tracking & Attribution.

Logspot.revenue(49.99, { currency: 'USD', plan: 'pro' });

amount - amount in major units (dollars, not cents).
options (optional) - currency (ISO-4217) plus any properties to store on the event (plan, product, …).

If you use Stripe, connect it instead and let Logspot ingest payments automatically — see the revenue guide.

Tell Logspot what each event is allowed to be used for. See Consent Management.

Logspot.setConsent({ analytics: true, functional: true, marketing: false });

const consent = Logspot.getConsent();

All fields are optional — send only the categories you've decided. If you use a CMP, set consentSources at init instead of calling setConsent yourself.

Get Anonymous ID

Read the current visitor's anonymous id — useful for passing into Stripe Checkout metadata for revenue attribution.

const anonymousId = Logspot.getAnonymousId();

You can define super properties which will be assigned to every event and pageview by calling register method. Previous properties will be merged with new properites (the new props will overwrite the prev props).

?> Super properties will be stored in cookies for 30 days (if cookies are enabled)

Register Super Properties

Logspot.register({
  email: 'john@doe.com',
  name: 'John',
});

Get Super Properties

const props = Logspot.getProperties();
// {
//   email: "john@doe.com",
//   name: "John",
// }

Unregister Super Properties

You can unregister super property when it's not needed anymore.

Logspot.unregister('email');

Reset Super Properties & User ID

When you want to clean up super properties and user id, use reset method.

Logspot.reset();

How to Configure Super Properties for All Events Including the First Pageview?

!> The first pageview is sent when the script is loaded. If we call register after init, the first pageview won't have super properties.

We need to use onLoad parameter in the sdk config. In the onLoad, you can call register method to register super properties for all events or any other method.

import Logspot from "@logspot/web";

Logspot.init({ ..., onLoad: () => {
    Logspot.register({ siteName: "Google" })
}});

or register dynamic properties with e.g. API call:

import Logspot from "@logspot/web";

Logspot.init({ ..., onLoad: async () => {
    const user = await fetchSomeUserData(userId);
    Logspot.register({ someUserProperty: user.property })
}});