Skip to content

Client ​

The client sends events from the browser, Node.js and edge functions. Install it from npm, or use the script tag. Refer to Script tag.

sh
npm install @quickpipeaiab/lead-scoring

createClient ​

ts
function createClient<Events = Record<string, object>>(options: ClientOptions): Client<Events>

createClient returns a client. The options are the options of the configuration, plus beforeSend.

OptionTypeDescription
keystringRequired. A publishable key lg-pub-live-… in the browser, or a secret key lg-sec-live-… on a server. The key gives the source of each event.
beforeSend(event) => event | nullOptional. Changes an event before the SDK sends it. Return null to drop the event. Only the npm client has this option.
ts
import { createClient } from '@quickpipeaiab/lead-scoring';

const lg = createClient({
  key: 'lg-pub-live-…',
  beforeSend: (event) => (event.event === 'debug.ping' ? null : event),
});

The SDK applies the consent rules again after beforeSend. It removes a click ID, a subject or a UTM value that the consent of the visitor does not allow. It drops an event with a name that the SDK cannot send, for example identify. It keeps the eventId of the event.

Methods ​

MethodReturnsDescription
track(name: string, properties?: object)voidSends an event.
identify(identifiers: PersonIdentifiers)voidAdds identifiers of a person to the current visitor. The match mode of each identifier decides the result.
account(identifiers: AccountIdentifiers, attributes?: object)voidLinks the current person to a company and sets attributes of the company, for example name and country.
set(attributes: object)voidSets attributes of the current person, for example a job title.
consent(state: 'granted' | 'denied')voidGives or removes the consent of the visitor for analytics only
consent(states: Partial<Record<Purpose, ConsentState>>)voidSets the consent state of each purpose that the object gives. Refer to Set consent.
reset()voidDeletes the visitor ID and starts a new anonymous visitor. Call it when a user signs out.
use(adapter: Adapter)voidAdds a custom adapter. Refer to Adapters.
debug(on: boolean)voidWrites each event, its checks and the response in the console.
flush()Promise<void>Sends all events in the queue now.
as(subject, options?: { ip?: string })SubjectServer only. Returns an object with track, identify, account and set for one explicit person.

The methods that return void never throw an error. When an event is not correct, the SDK drops it. In debug mode, it writes the reason in the console.

The client also has Symbol.asyncDispose. Thus await using sends the queue at the end of the scope:

ts
await using lg = createClient({ key: 'lg-sec-live-…' });
lg.as({ email: '[email protected]' }).track('invoice.paid', { amount: 1200 });

track ​

ts
lg.track('pricing.viewed', { plan: 'pro' });

Rules for the event name:

  • The SDK removes the spaces at the start and at the end, and changes the name to lowercase.
  • The name can contain a to z, 0 to 9 and the characters _ . : -. The first character must be a letter or a digit.
  • The maximum length is 100 characters.
  • Use the form namespace.action, for example email.clicked or trial.started.
  • Do not use the names identify, link and profile. The SDK sends these names itself.
  • Do not use a name that starts with system.. QuickPipe rejects all these names.

Rules for the properties:

  • The SDK keeps each property key as you send it. It does not change the case of keys.
  • The maximum size is 32 KB, with a maximum depth of 5 and a maximum of 200 keys.

identify ​

ts
lg.identify({ email: '[email protected]', userId: 'u_812' });
IdentifierExample
email[email protected]
phone+46701234567
linkedinProfilehttps://www.linkedin.com/in/ana-berg
xProfilehttps://x.com/anaberg or @anaberg
instagramProfilehttps://www.instagram.com/anaberg
githubProfilehttps://github.com/anaberg
tiktokProfile@anaberg
youtubeChannelhttps://www.youtube.com/@anaberg
leadId0190d4c6-7b1e-7c3a-9f2e-5a1d2b3c4d5e, the lead ID in QuickPipe, a UUIDv7
userIdThe user ID in your product
anonymousIdThe visitor ID from the cookie lg_aid

account ​

ts
lg.account({ domain: 'acme.se', seOrgnr: '556000-0001' }, { name: 'Acme AB', country: 'SE' });
IdentifierExample
domainacme.se
seOrgnr, noOrgnr, dkCvr, fiYtunnus, isKennitalaThe Nordic company number, for example 556000-0001 for seOrgnr
euVatSE556000000101
lei, duns, ukCrn, nlKvk, frSiren, frSiret, deRegisterThe company number of that register
linkedinCompanyhttps://www.linkedin.com/company/acme
companyIdThe company ID in QuickPipe

The company name and the country are attributes of the account, not identifiers. Send them in the second argument of account. QuickPipe makes name_country from them. A server producer can also send a profile event with subjectKind: "account".

The identifier names are the camelCase form of the names in the registry of your workspace, for example seOrgnr for se_orgnr. A name starts with a lowercase letter and contains only letters and digits.

set ​

ts
lg.set({ title: 'VP Sales', plan: 'pro' });

The script stub ​

The script tag version has the same methods. Call them through the global function lg. The stub keeps the calls until the script loads:

html
<script>window.lg=window.lg||function(){(lg.q=lg.q||[]).push(arguments)}</script>
<script>
  lg('track', 'pricing.viewed', { plan: 'pro' });
  lg('identify', { email: '[email protected]' });
  lg('account', { domain: 'acme.se' });
  lg('set', { title: 'VP Sales' });
  lg('consent', 'granted');
  lg('reset');
  lg('debug', true);
</script>

Server ​

On a server, use a secret key. The subject of each call is explicit:

ts
import { createClient } from '@quickpipeaiab/lead-scoring';

const lg = createClient({ key: 'lg-sec-live-…' });

lg.as({ email: '[email protected]' }, { ip: request.ip }).track('invoice.paid', { amount: 1200 });
lg.as({ leadId: '0190d4c6-7b1e-7c3a-9f2e-5a1d2b3c4d5e' }).set({ plan: 'pro' });

await lg.flush();

Keep a secret key on the server. The SDK refuses a secret key in a browser.

Join server events to the browser visitor ​

A server can read the cookie lg_aid. Then the server events and the browser events have the same visitor. This example uses Next.js:

ts
import { cookies } from 'next/headers';

const anonymousId = (await cookies()).get('lg_aid')?.value;
if (anonymousId) lg.as({ anonymousId }).track('checkout.completed', { amount: 1200 });

React ​

tsx
import { Provider, useClient } from '@quickpipeaiab/lead-scoring/react';

export function App({ children }) {
  return <Provider client={lg}>{children}</Provider>;
}

function PricingButton() {
  const { track } = useClient();
  return <button onClick={() => track('pricing.cta_clicked')}>See pricing</button>;
}

Provider gives the client to the components. The client sends page.viewed on each route change. In the Next.js App Router, each file that calls useClient needs 'use client' at the top.

Types ​

This command writes the event names and the property shapes that QuickPipe already received from your sources:

sh
npx lead-scoring types --key lg-sec-live-… --out lead-scoring.d.ts

Give the type to createClient<Events>(). Then your editor completes the event names and checks the properties. An event name that is not in the file also compiles.