Skip to main content

​
GuideWhale Installation

You can follow a similar guide inside our dashboard by going to GuideWhale dashboard > Settings > Installation.
1

Step 1: Install Javascript SDK

Add this to your application environment to load our JavaScript SDK. Make sure to add this to your index.html or root layout file on every page you want to track users and display interactive content.
//Import GuideWhale package
import gwhale from 'guidewhale';

//Initialize SDK
gwhale.init(...);
2

Step 2: User Identity Verification

Before you get started with identifying a user, you need to verify their identity. In order to verify user identity and prevent impersonations, you need to sign your user’s user_id with a secret key. Make sure to never share your secret key with anyone.For user_id it important to use a unique identifier for each of your users. This can be a database id, email address, or any other unique identifier.
Please note that each environment has its own unique secret key.
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
...
3

Step 3: Initialize GuideWhale

In order to show your interactive content to a specific segment of users, you need to identify them with GuideWhale SDK using gwhale.init method.For single page applications (SPA), this only needs to be called when page is initially loaded. For multi-page applications, this needs to be called on every page load.We can now use the signature and user data from the previous step to identify a user and their company.
Please note that each app environment has its own unique code, which can be found in the GuideWhale dashboard > Settings > Installation.

//
// Initialize environment and identify application user
// IMPORTANT: Replace placeholders with actual user data
//
gwhale.init(<environment_code>, {               // REQUIRED - string - make sure to use the correct environment code for desired application environment
    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.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)
    }
});
Additionally, you can also prime our SDK by initializing it without user data. This will allow any potential guide redirects from Open Inside Application functionality from embedded slideshows or documents to be captured and executed once user has logged in.
//Initialize SDK
gwhale.init(<environment_code>);
4

Step 4: Redirect Without Reloading

As different frameworks handle routing differently, you will need to add a small snippet of code to your application to handle redirects without reloading the page.
//GuideWhale redirect without reloading the page
gwhale.onRedirect((url: string) => {
    //Your custom redirect logic
});
5

Step 5: Tracking Events (optional)

This is an optional step, but highly recommended to do while you’re performing the installation.
Any events not captured automatically by our SDK (like button clicks, form submissions, etc.) can be captured using the gwhale.track method.If you have any enabled integrations with 3rd-party analytics platforms like Amplitude, Mixpanel, or similar, these event will automatically be forwarded to them if event pushing is enabled and their SDK is present on the page.
//e.g. User verified their email address
gwhale.track("verified_email", {
    user_id: '1234abcd',
    ... // OPTIONAL - string | number | date - additional event properties
});
6

Step 6: Verify Installation

To verify your installation, you can check if your newly identified users are visible on the Users page inside our dashboard. If you have imported users, you can sort by the Last Seen At column to find the latest identified users.We also provide a status at the bottom of the installation settings page, which checks if your app had any activity in the last 7 days.
You can find more of Javascript SDK methods under the methods section.