Javascript SDK Reference

NiceJob's Javascript SDK is designed to be used from the browser. Loading the SDK via a <script> tag will create a NiceJob global variable in browser. All references to NiceJob herein refer to this browser variable.

The Javascript SDK does not read data from the NiceJob platform. It strictly creates it, typically in response to a user's activity on a webpage.

Loading the NiceJob SDK

To load the NiceJob SDK, simply add the following to your webpage's HTML:

<script src="https://cdn.nicejob.co/js/sdk.min.js?id=$COMPANY_ID"></script>
  • where $COMPANY_ID is the NiceJob company ID of the company represented on the webpage

Instantiating the NiceJob SDK

Before the NiceJob SDK is used for data creation purposes, it must be instantiated using a company's SDK public key. The SDK public key must correspond to the company for whom the SDK was loaded, indicated by $COMPANY_ID above.

Call the SDK init() method with a company's SDK public key to instantiate the SDK:

NiceJob.init(PUBLIC_KEY);

SDK public key

Each NiceJob company has an SDK public key, separate from their company ID. This SDK public key is required to start using the NiceJob SDK. Your company's SDK public key can be found by navigating to the Company Profile page in the NiceJob app, at https://app.nicejob.co/settings/company/profile.

Warning: The active user must be a company Owner or Manager to view the SDK public key. It will be hidden otherwise.

Using the NiceJob SDK

After instantiating the NiceJob SDK, you are free to use its other methods. See the Methods reference below for information on and examples of each method.

Warning: Calling an SDK method before calling NiceJob.init() will result in the method call failing.

Methods

init()

The init() method instantiates the NiceJob SDK using a company's SDK public key.

Example usage

NiceJob.init(public_key);

Parameters

ParameterTypeDescription
public_keystring(#sdk-public-key)

send()

The send() method is used to send event data to the NiceJob platform. It takes two parameters: event_type, a string which identifies the event type, and event_payload (an object), which provides the data payload for the event. The shape of the event_payload object is dependent on the event type specified by event_type, though there are some commonalities across all event types.

Event payloads

The event_payload is an object with four keys comprising four distinct components of the event: the element with which the visitor interacted, and the data, metadata, and tags corresponding to the event.

PropertyType
elementhtmlelement
dataobject
metadataobject
tagsarray<string>
  • Whether element and / or data are required depends on the event type
  • The data property does not apply to some event types

Payload: element

The event element is the HTML element with which the user interacted (clicked, viewed, hovered, etc.). NiceJob will save the element's classes and text content for you, to facilitate A/B testing analysis.

Payload: data

The event data is an object providing event-specific data. For each of the event types listed below, we provide the data object field requirements.

Payload: metadata

The event metadata is a set of key-value pairs that you can freely attach to an event, useful for storing additional information about the event. metadata keys are string, while metadata values can be of types string, number, boolean, or null.

Payload: tags

The event tags are a set of string labels attached to an event, useful for classification and filtering.

Supported event types

setGlobalMetadata()

The setGlobalMetadata() method sets metadata that is appended to the metadata payload of each send call.

Example usage

/**
 * Set global metadata, which will append a `user_id` field onto
 * the payload metadata for each subsequent `NiceJob.send()` call
 */
NiceJob.setGlobalMetadata({ user_id: 'my-user-id' });

Parameters

ParameterTypeDescription
metadataobjectEvent metadata; see Payload: metadata above for format

Webform

A Webform is created in NiceJob when a visitor submits a form on a company website. The visitor will be created as a Person in NiceJob. The Webform itself can be viewed in NiceJob on the Convert Website Activity page (Convert users only), or on the Person profile page of the visitor for whom it was created.

send() parameters

ParameterValue
event_type"webform"
event_payload.elementOptional
event_payload.dataRequired
event_payload.metadataOptional
event_payload.tagsOptional

Event payload data

For Webforms, event_payload.data is extensible. Of the listed fields below, only email is required. Additional fields may be added, and will be displayed on the Webform data card in NiceJob.

  • email
    string
  • first_name
    string?
  • last_name
    string?
  • phone
    string?
The NiceJob API prefers separate first_name and last_name fields, instead of a single name field. If you send data in a name field, we will automatically split it into first_name and last_name before saving.

Example usage

NiceJob.send('webform', {
    element, // An HTMLElement
    data: {
        email: 'jane@example.com',
        first_name: 'Jane',
        last_name: 'Doe',
        phone: '555-123-4567',
    },
    metadata: {
        version: '1.0',
    },
    tags: ['landing_page', 'version_1'],
});

Minimum usage:

NiceJob.send('webform', {
    data: {
        email: 'jane@example.com',
    },
});

Custom Webform data (with fields not listed above) may also be added:

NiceJob.send('webform', {
    element,
    data: {
        email: 'jane@example.com',
        comments: 'Hello, I need help with my home.',
        location: 'Northtown',
    },
});