GuideWhale Client Script

GuideWhale client installation using npm. The module exports a guidewhale object, which is used to reference all of our SDK methods.

The script is automatically loaded when the module is imported. Any methods that are called before the script is loaded will be queued and executed after the script finishes loading.

Installation

npm install guidewhale

User Identity Verification

In order to verify user identity and prevent impersonations, you need to sign your user_id with a secret key and provide the signature during JavaScript SDK initialization.

Your secret key can be copied from the GuideWhale dashboard environment settings or on the installation settings page. Please note that each environment has its own unique secret key.

⚠️ Warning: Never share your secret key. This operation should be performed on the server side only.

import crypto from 'crypto'

// Generate user signature using environment secret key and user_id
// IMPORTANT: Secret key should not be shared with anyone, so perform this on your server
let userSignature = crypto
  .createHmac('sha256', <secret_key>)
  .update(<user_id>)
  .digest('hex')

// Pass user signature to your client
...

User Identification

Start by importing our package by calling import gwhale from 'guidewhale', then initialize the environment and currently active user/company. Make sure to replace placeholder values with your actual environment token and user/company properties, while removing any non-required properties which you don't have/need.

⚠️ Warning: Do not name your custom properties with a leading underscore (_), as they are reserved for internally generated properties.

⚠️ Warning: If you're using server-side rendering (SSR) to display your pages, you should import our package using await import('guidewhale') on the client-side.

import gwhale from 'guidewhale';

gwhale.init("<guidewhale_environment_code>", {  // REQUIRED - string - make sure to use the correct environment code for desired application environment (e.g. 'prod-1234abcd')
    gdpr: true,                                 // OPTIONAL - true | false - enable GDPR mode to require user consent before tracking data under their user_id
    gdpr_consent: true,                         // OPTIONAL - true | false - Whether user has given consent to track their data
    signature: <user_signature>,                // REQUIRED IF USER_ID IS SET - string - user signature hash (not the secret!) to prevent unathorized initialization
    user: {
        user_id: <user_id>,                     // REQUIRED - string | null - unique user identifier (e.g. null for anonymous users, '100000356', '6099047b-660b-4f2e-a878-fb66a12c1840', '[email protected]')
        email: <user_email>,                    // RECOMMENDED - string - email is used as the key to map user data for most integrations (e.g. '[email protected]')
        image_url: <profile_image_url>,         // RECOMMENDED - string - used to display user's profile image inside GuideWhale dashboard (e.g. 'https://cdn.guidewhale.com/users/1234abcd/profile.png')
        first_name: <user_first_name>,          // RECOMMENDED - string - can be used to personalize GuideWhale content (e.g. 'John')
        last_name: <user_last_name>,            // RECOMMENDED - string - can be used to personalize GuideWhale content (e.g. 'Smith')
        date_signed_up: <user_signup_date>,     // RECOMMENDED - date - can be used to selectively show content to new users (Must be ISO8601 string - e.g. "2024-01-01T12:00:00Z")
        ...                                     // OPTIONAL - string | number | date - custom user properties (e.g. gender: 'female')
    },
    company: {
        company_id: <company_id>,               // REQUIRED - string - unique company identifier (e.g. '100000356', '6099047b-660b-4f2e-a878-fb66a12c1840')
        name: <company_name>,                   // RECOMMENDED - string - can be used to personalize GuideWhale content (e.g. 'GuideWhale Inc.')
        image_url: <logo_image_url>,            // RECOMMENDED - string - used to display logo image inside GuideWhale dashboard (e.g. 'https://cdn.guidewhale.com/companies/1234abcd/logo.png')
        plan: <company_subscription_plan>,      // RECOMMENDED - string - can be used to target users for upselling, discounts, and promotions (e.g. 'free', 'basic', 'pro')
        date_signed_up: <company_signup_date>,  // RECOMMENDED - date - can be used to selectively show content to new companies (Must be ISO8601 string - e.g. "2024-01-01T12:00:00Z")
        date_renewal: <company_renewal_date>,   // RECOMMENDED - date - can be used to encourage companies to renew their contract (Must be ISO8601 string - e.g. "2024-01-01T12:00:00Z")
        mrr: <company_mrr>,                     // RECOMMENDED - number - can be used to target companies spending more or less (e.g. 100.0, 500.0, 1000.0)
        license_count: <company_license_count>, // RECOMMENDED - number - can be used to target bigger customers (e.g. 1, 5, 10, 50)
        industry: <company_industry>,           // RECOMMENDED - string - can be used to segment companies by industries (e.g. 'Medical', 'Financial Services')
        size: <company_size>,                   // RECOMMENDED - number - can be used to segment companies by their size (e.g. 100, 250, 1000)
        ...                                     // OPTIONAL - string | number | date - custom company properties (e.g. location: 'United States')
    },
    membership: {
        is_primary: <user_is_primary_contact>,  // RECOMMENDED - boolean - whether user is the primary contact for the company (e.g. true, false)
        role: <user_company_role>,              // RECOMMENDED - string - you can target users based on their role in the company (e.g. 'admin', 'user', 'guest')
        ...                                     // OPTIONAL - string | number | date - custom user company membership properties (e.g. employee_number: 12345)
    }
});

Redirects without reloading

By default, GuideWhale client uses window.location.assign to redirect users between different pages. If you want to use a custom redirect logic, you can use the onRedirect method.

gwhale.onRedirect((url: string) => {
    //Your custom redirect logic 
});

Development

1. Install dependencies: npm install
2. Build: npm run build