Methods

A list of methods and properties available in the GuideWhale Javascript SDK.

To install the SDK, please follow the instructions in the installation section.

All methods below are called using the loaded window.gwhale instance.

init

This method needs to be called before calling any other methods below.

Used to initialize GuideWhale app environment and identify user, company and their membership.

• For single page applications (SPA) this method should only be called when page is initially loaded.
• For multipage application this method should be called on every page load

For a detailed parameter guide see the installation section.

environment_code · string · required

Code of the app environment to initialize. This can be found in our dashboard under Settings > Environments or Settings > Installation.

options · object

Initialization options, including user, company and membership properties.

Hide Options

signature · string

User verification signature generated by your backend from user_id and app environment secret key. See installation section for more details.

Only required if user.user_id is set and user has given their consent to data collection.

gdpr · boolean

If we should consider GDPR consent. Enable this if you’re dealing with users who have not given their consent for data collection.

gdpr_consent · boolean

When GDPR option is enabled, this field should be set to true if the user has given their consent for data collection. If consent has not been given, user.user_id will be anonymized for each session.

user · object

User identification properties.

Hide User Properties

user_id · string | null · required

Unique user identifier. Set to null if you’re dealing with an anonymous user.

email · string

User’s email address.

image_url · string

URL of user’s profile image.

first_name · string

User’s first name.

last_name · string

User’s last name.

date_signed_up · date

When user has signed up for your application.

... · string | number | boolean | date

Any other custom user property you want to add.

company · object

Company identification properties.

Hide Company Properties

company_id · string · required

Unique company identifier.

name · string

Company name.

image_url · string

URL of company logo image.

plan · string

Company’s subscription plan.

date_signed_up · date

When company has signed up for your application.

date_renewal · date

When company’s subscription is set to renew.

mrr · number

Company’s monthly recurring revenue.

license_count · number

Number of licenses company has purchased.

industry · string

Company industry.

size · number

Company employee count.

... · string | number | boolean | date

Any other custom company property you want to add.

membership · object

User company membership identification properties.

Hide Membership Properties

is_primary · boolean

If user is a primary contact of a company.

role · string

User’s role in a company.

... · string | number | boolean | date

Any other custom membership property you want to add.

Example

gwhale.init('prod-1234abcd', {
    gdpr: true,
    gdpr_consent: true,
    signature: '5e7001282790905aa22523e2c0c5e7cd08046b79fd8546b3bb43a5578704f683',
    user: {
        user_id: '123',
        email: '[e-mail]',
        first_name: 'John',
        last_name: 'Smith',
        date_signed_up: '2022-01-01',
        custom_property: 'value1'
    },
    company: {
        company_id: '123',
        name: 'ACME',
        plan: 'Enterprise',
        date_signed_up: '2022-01-01',
        date_renewal: '2025-01-01',
        mrr: 999,
        license_count: 10,
        industry: 'Construction',
        size: 30,
        custom_property: 'value1'
    },
    membership: {
        is_primary: true,
        role: 'user',
        custom_property: 'value1'
    }
});

track

Used to programmatically track user events that are not taggable or automatically captured by GuideWhale.

name · string · required

The name of the event to track.

properties · object

Contextual properties associated with this event.

Example

gwhale.track('item_purchased', {
    name: 'Pro Subscription',
    price: 1000.0
});

onRedirect

Used to handle redirects without a page reload when GuideWhale content wants to redirect to another page.

handler · (url: string) => void · required

Handler function to handle redirects without a page reload when GuideWhale content wants to redirect to another page.

Example

gwhale.onRedirect((url: string) => {
    navigate(url);
});

reset

Remove currently identified user and company. You will have to call the init function again to re-identify the user.

Example

gwhale.reset();

setUserProperties

Helper function to set user properties of currently identified user without having to call the identify function again.

properties · object · required

New property values.

Example: set value

gwhale.setUserProperties({
    count: 10
});

Example: add to existing property value

// NOTE: Addition is limited to numeric values
gwhale.setUserProperties({
    count: { add: 5 }
});

Example: subtract from existing property value

// NOTE: Subtraction is limited to numeric values
gwhale.setUserProperties({
    count: { subtract: 5 }
});

setCompanyProperties

Helper function to set company properties of currently identified user without having to call the identify function again.

properties · object · required

New property values.

Example: set value

gwhale.setCompanyProperties({
    plan: 'Enterprise'
});

Example: add to existing property value

// NOTE: Addition is limited to numeric values
gwhale.setCompanyProperties({
    count: { add: 5 }
});

Example: subtract from existing property value

// NOTE: Subtraction is limited to numeric values
gwhale.setCompanyProperties({
    count: { subtract: 5 }
});

setMembershipProperties

Helper function to set user company membership properties of currently identified user without having to call the identify function again.

properties · object · required

New property values.

Example: set value

gwhale.setMembershipProperties({
    position: 'Manager'
});

Example: add to existing property value

// NOTE: Addition is limited to numeric values
gwhale.setMembershipProperties({
    count: { add: 5 }
});

Example: subtract from existing property value

// NOTE: Subtraction is limited to numeric values
gwhale.setMembershipProperties({
    count: { subtract: 5 }
});