JavaScript SDK methods

The JavaScript SDK is equipped to handle all essential event calls, including page, screen, track, identify, and group. Furthermore, it offers functionalities to efficiently manage sessions and user/group information.

With these capabilities, you can seamlessly track and analyze user interactions across different platforms, facilitating a comprehensive understanding of user behavior and engagement.

Below the JavaScript SDK methods:

page
screen
track
identify
group
user
setAnonymousId
getSessionId
startSession
endSession
ready
reset
debug
close

The JavaScript SDK also supports the getAnonymousId method of the RudderStack SDK that can be used as an alternative to the user().anonymousId.

page

The page method implements the page call.

The page call allows you to capture when a user views a page on your website, including any extra details about that specific page.

Syntax

page(category, name, properties, options, callback)

page(
    name: string,
    properties?: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

page(
    category: string,
    name: string,
    properties?: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

page(
    properties?: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

Parameters

All parameters are optional. A single String parameter indicates name, while a single Object parameter signifies properties.

Name	Type	Description
`category`	`String`	Category of the page. Can be useful to group pages.
`name`	`String`	Name of the page.
`properties`	`Object`	Properties of the page.
`options`	`Object`	Options of the page.
`callback`	`Function`	A function called when the event has been queued.

It returns a Promise that resolve when the event has queued. If the browser does not support promises and a polyfill has not been installed, it returns undefined.

Example

krenalis.page('Shirt', {
    productId: 308263,
}).then(() => console.log('event queued'));

screen

The screen method implements the screen call.

The screen call enables you to capture instances when a user views a screen and record associated properties or details about that particular screen.

Syntax

screen(category, name, properties, options, callback)

screen(
    name: string,
    properties?: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

screen(
    category: string,
    name: string,
    properties?: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

screen(
    properties?: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

Parameters

All parameters are optional. A single String parameter indicates name, while a single Object parameter signifies properties.

Name	Type	Description
`category`	`String`	Category of the screen. Can be useful to group screens.
`name`	`String`	Name of the screen.
`properties`	`Object`	Properties of the screen.
`options`	`Object`	Options of the screen.
`callback`	`Function`	A function called when the event has been queued.

It returns a Promise that resolve when the event has queued. If the browser does not support promises and a polyfill has not been installed, it returns undefined.

Example

krenalis.screen('Order Completed', {
    items: 3,
    total: 274.99,
}).then(() => console.log('event queued'));

track

The track method implements the track call.

The track call is used to send specific events or actions, and associated properties, that occur when users interact with your application or website.

Syntax

track(name, properties, options, callback)

track(
    name: string,
    properties?: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

Parameters

Only name is required, the other parameters are optional. A single Object parameter signifies properties.

Name	Type	Required	Description
`name`	`String`	✓	Name of the event.
`properties`	`Object`		Properties of the event.
`options`	`Object`		Options of the event.
`callback`	`Function`		A function called when the event has been queued.

It returns a Promise that resolve when the event has queued. If the browser does not support promises and a polyfill has not been installed, it returns undefined.

Example

krenalis.screen('Order Completed', {
    items: 3,
    total: 274.99,
});

identify

The identify method implements the identify call.

Through an identify call, you can connect previous and upcoming events to a recognized user and save details about them along with their events, such as name and email. The user information can also be utilized to update and enhance unified data from other sources.

Syntax

identify(userId, traits, options, callback)

identify(
    userId: string,
    traits?: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

identify(
    traits?: string,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

Parameters

All parameters are optional. A single Object parameter signifies traits.

Name	Type	Description
`userId`	`String`	Identifier of the user.
`traits`	`Object`	Traits to add to the user's traits. Pass the `undefined` value for a trait to remove it.
`options`	`Object`	Options of the event.
`callback`	`Function`	A function called when the event has been queued.

It returns a Promise that resolve when the event has queued. If the browser does not support promises and a polyfill has not been installed, it returns undefined.

Example

krenalis.identify('59a20n37ec82', {
    firstName: 'Emily',
    lastName: 'Johnson',
    email: 'emma.johnson@example.com',
    address: {
        street: "123 Main Street",
        city: "San Francisco",
        state: "CA",
        postalCode: "94104",
        country: "USA"
    }
});

For the previous example, we can have three scenarios:

If the user is currently anonymous, they become known with the given User ID and traits.
If the user is currently non-anonymous but has a different User ID, their User ID is changed, and all traits are replaced with the provided ones.
If the user is currently non-anonymous and has the same User ID as the provided one, the provided traits are added to the current traits. If a provided trait has the value undefined, the corresponding trait is removed.

To completely replace the current user's traits, regardless of whether the user is anonymous or non-anonymous, and without making an identify call, use the user().traits method.

group

The group method, when called without arguments, returns an instance of the Group class representing the group.

When called with arguments, implements the group call. The group call provides a way to associate individual users with groups, such as a company, organization, team, association, or initiative. A user who has been identified can be associated with several groups.

Syntax

// returns a Group instance
group()

// implements the group call
group(groupId, traits, options, callback)

// returns a Group instance
group(): Group

// implements the group call
group(
    groupId: string,
    traits?: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

// implements the group call
group(
    traits: Record<string, unknown>,
    options?: Record<string, unknown>,
    callback?: () => void
): Promise<SentEvent>

Parameters

All parameters are optional. A single Object parameter signifies traits.

Name	Type	Description
`groupId`	`String`	Identifier of the group.
`traits`	`Object`	Traits of the group.
`options`	`Object`	Options of the event.
`callback`	`Function`	A function called when the event has been queued.

If no arguments are provided, it returns an instance of the Group class. Otherwise, it returns a Promise that resolve when the event has queued. If the browser does not support promises and a polyfill has not been installed, it returns undefined.

Example

const groupId = krenalis.group().id();

krenalis.group('84s76y49tb28v1jxq', {
    name: "AcmeTech",
    industry: "Technology",
    employeeCount: 100
});

user

The user method returns an instance of the User class to read and set the identifier, Anonymous ID, and traits of the user.

Syntax

user()

user(): User

Parameters

There are no parameters.

Returns an instance of the User class representing the user.

Example

const traits = krenalis.user().traits();

setAnonymousId

The setAnonymousId method is used to set the Anonymous ID. It's necessary because you can't call the user().anonymousId method before Krenalis is ready. If you need to set the Anonymous ID before Krenalis is ready, using the setAnonymousId method is your only option.

Call the setAnonymousId method with an argument:

to reset the Anonymous ID with a newly generated value, pass null.
to set the Anonymous ID with a specified value, pass a non-empty String or a Number (the number will be converted to a String).

If it is called after Krenalis is ready, it also returns the Anonymous ID.

Syntax

setAnonymousId(id)

setAnonymousId(id?: string): string | undefined

Parameters

Name	Type	Required	Description
`id`	`String`		Anonymous ID to set. If it is missing it does nothing.

It returns the Anonymous ID, if called after Krenalis is ready.

Example

krenalis.setAnonymousId('cd320a46-0642-468c-9f03-c8647faa8ac4');

getSessionId

The getSessionId method returns the current session identifier.

Syntax

getSessionId()

getSessionId(): number

Parameters

There are no parameters. Returns a Number representing the current session identifier, or null if there is no session.

Example

const sessionId = krenalis.getSessionId();

startSession

The startSession method starts a new session using the provided identifier. If no identifier is provided, it generates one automatically.

Syntax

startSession(id)

startSession(id?: number): void

Parameters

Name	Type	Required	Description
`id`	`Number`		Session identifier.

Example

krenalis.startSession();

endSession

The endSession method ends the session.

Syntax

endSession()

endSession(): void

Parameters

There are no parameters.

Example

krenalis.endSession();

ready

The ready method calls a callback after the Krenalis finishes initializing. If promises are supported, it also returns a promise.

Syntax

ready(callback)

ready(callback?: () => void): Promise<void>

Parameters

Name	Type	Required	Description
`callback`	`Function`		Callback to call when Krenalis finishes initializing.

It returns a Promise that resolves or rejects when Krenalis finishes initializing. If the browser does not support promises and no polyfill has been installed, it returns undefined.

Example

krenalis.ready(() => console.log('Krenalis has been initialized'));

import Krenalis from 'krenalis-javascript-sdk';
const krenalis = new Krenalis('<write key>', '<endpoint>');
await krenalis.ready();

reset

The reset method resets the user and group identifiers, and updates or removes the Anonymous ID and traits according to the strategy (as detailed in the table below). If all is true it always resets the Anonymous ID by generating a new one, and ends the session if one exists, regardless of the strategy.

Strategy	Behavior of `reset()`
Conversion	Removes User ID, Group ID, user and group traits, and changes Anonymous ID and session.
Fusion	Removes User ID, Group ID, and user and group traits. Does not change Anonymous ID or session.
Isolation	Removes User ID, Group ID, user and group traits, and changes Anonymous ID and session.
Preservation	Removes User ID. Restores Anonymous ID, Group ID, user and group traits, and session to their state before the latest `identify` call.

Syntax

reset(all)

reset(all?: boolean): void

Parameters

Name	Type	Required	Description
`all`	`Boolean`		Indicates if the Anonymous ID and the session must be reset, regardless of the strategy.

Example

krenalis.reset();  // same as krenalis.reset(false)

Segment Compatibility

To align with Segment's reset() behavior, choose the "Conversion" or "Isolation" strategy in Krenalis. Note that reset(true) is not available in Segment.

RudderStack Compatibility

To match RudderStack's reset() behavior, choose the "Conversion" or "Isolation" strategy in Krenalis. In Krenalis, reset(true) works the same way as it does in RudderStack for all strategies.

debug

The debug method toggles debug mode.

Syntax

debug(on)

debug(on: boolean): void

Parameters

Name	Type	Required	Description
`on`	`Boolean`	✓	Indicates if the debug mode is active.

Example

krenalis.debug(true);

close

The close method closes the Krenalis instance. It tries to preserve the queue in the localStorage before returning.

Syntax

close()

close(): void

Parameters

There are no parameters.

Example

krenalis.close();

Options parameter

The options parameter allows you to override or extend event properties when calling page, screen, track, identity, or group.

Name	Type	Description
`timestamp`	`Date` or `String`	Event timestamp. If omitted, the SDK uses the current time.
`messageId`	`String`	Event message ID. If omitted, the SDK generates one.
`context`	`Object`	Context object merged deeply into the event context.
`integrations`	`Object`	Integrations.

Example

The following example sets context.ip to 255.255.255.0.

krenalis.page('Shirt', { productId: 308263 }, { context: { ip: '255.255.255.0' } }).then(() => console.log('event queued'));