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.
npm install @quickpipeaiab/lead-scoringcreateClient
function createClient<Events = Record<string, object>>(options: ClientOptions): Client<Events>createClient returns a client. The options are the options of the configuration, plus beforeSend.
| Option | Type | Description |
|---|---|---|
key | string | Required. 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 | null | Optional. Changes an event before the SDK sends it. Return null to drop the event. Only the npm client has this option. |
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
| Method | Returns | Description |
|---|---|---|
track(name: string, properties?: object) | void | Sends an event. |
identify(identifiers: PersonIdentifiers) | void | Adds identifiers of a person to the current visitor. The match mode of each identifier decides the result. |
account(identifiers: AccountIdentifiers, attributes?: object) | void | Links the current person to a company and sets attributes of the company, for example name and country. |
set(attributes: object) | void | Sets attributes of the current person, for example a job title. |
consent(state: 'granted' | 'denied') | void | Gives or removes the consent of the visitor for analytics only |
consent(states: Partial<Record<Purpose, ConsentState>>) | void | Sets the consent state of each purpose that the object gives. Refer to Set consent. |
reset() | void | Deletes the visitor ID and starts a new anonymous visitor. Call it when a user signs out. |
use(adapter: Adapter) | void | Adds a custom adapter. Refer to Adapters. |
debug(on: boolean) | void | Writes 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 }) | Subject | Server 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:
await using lg = createClient({ key: 'lg-sec-live-…' });
lg.as({ email: '[email protected]' }).track('invoice.paid', { amount: 1200 });track
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
atoz,0to9and the characters_ . : -. The first character must be a letter or a digit. - The maximum length is 100 characters.
- Use the form
namespace.action, for exampleemail.clickedortrial.started. - Do not use the names
identify,linkandprofile. 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
lg.identify({ email: '[email protected]', userId: 'u_812' });| Identifier | Example |
|---|---|
email | [email protected] |
phone | +46701234567 |
linkedinProfile | https://www.linkedin.com/in/ana-berg |
xProfile | https://x.com/anaberg or @anaberg |
instagramProfile | https://www.instagram.com/anaberg |
githubProfile | https://github.com/anaberg |
tiktokProfile | @anaberg |
youtubeChannel | https://www.youtube.com/@anaberg |
leadId | 0190d4c6-7b1e-7c3a-9f2e-5a1d2b3c4d5e, the lead ID in QuickPipe, a UUIDv7 |
userId | The user ID in your product |
anonymousId | The visitor ID from the cookie lg_aid |
account
lg.account({ domain: 'acme.se', seOrgnr: '556000-0001' }, { name: 'Acme AB', country: 'SE' });| Identifier | Example |
|---|---|
domain | acme.se |
seOrgnr, noOrgnr, dkCvr, fiYtunnus, isKennitala | The Nordic company number, for example 556000-0001 for seOrgnr |
euVat | SE556000000101 |
lei, duns, ukCrn, nlKvk, frSiren, frSiret, deRegister | The company number of that register |
linkedinCompany | https://www.linkedin.com/company/acme |
companyId | The 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
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:
<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:
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:
import { cookies } from 'next/headers';
const anonymousId = (await cookies()).get('lg_aid')?.value;
if (anonymousId) lg.as({ anonymousId }).track('checkout.completed', { amount: 1200 });React
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:
npx lead-scoring types --key lg-sec-live-… --out lead-scoring.d.tsGive 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.