Initialize a new Alias facade with a dictionary of arguments.

new Alias(dictionary: Object, opts: Object)

Extends Facade

Parameters
dictionary (Object) The object to wrap.
Name Description
dictionary.from string? The previous ID of the user.
dictionary.to string? The new ID of the user.
opts (Object) Options about what kind of Facade to create.
Instance Members
action()
type()
previousId()
from()
userId()
to()

Initialize a new Delete facade with a dictionary of arguments.

new Delete(dictionary: Object, opts: Object)

Extends Facade

Parameters
dictionary (Object) The object to wrap.
Name Description
dictionary.category string? The delete category.
dictionary.name string? The delete name.
dictionary.properties string? The delete properties.
opts (Object) Options about what kind of Facade to create.
Instance Members
type()

A Facade is an object meant for creating convience wrappers around objects. When developing integrations, you probably want to look at its subclasses, such as Track or Identify, rather than this general-purpose class.

This letructor will initialize a new Facade with an obj of arguments.

If the inputted obj doesn't have a timestamp property, one will be added with the value new Date(). Otherwise, the timestamp property will be converted to a Date using the new-date package.

By default, the inputted object will be defensively copied, and all ISO strings present in the string will be converted into Dates.

new Facade(obj: Object, opts: Object)
Parameters
obj (Object) The object to wrap.
opts (Object) Options about what kind of Facade to create.
Name Description
opts.clone boolean (default true) Whether to make defensive clones. If enabled, the inputted object will be cloned, and any objects derived from this facade will be cloned before being returned.
opts.traverse boolean (default true) Whether to perform ISODate-Traverse on the inputted object.
Static Members
proxy(field)
field(field)
multi(path)
one(path)

Get a potentially-nested field in this facade. field should be a period-separated sequence of properties.

If the first field passed in points to a function (e.g. the field passed in is a.b.c and this facade's obj.a is a function), then that function will be called, and then the deeper fields will be fetched (using obj-case) from what that function returns. If the first field isn't a function, then this function works just like obj-case.

Because this function uses obj-case, the camel- or snake-case of the input is irrelevant.

proxy(field: string): any
Parameters
field (string) A sequence of properties, joined by periods ( . ).
Returns
any: A property of the inputted object.
Example
YourClass.prototype.height = function() {
  return this.proxy('getDimensions.height') ||
    this.proxy('props.size.side_length');
}

Directly access a specific field from the underlying object. Only "top-level" fields will work with this function. "Nested" fields will not work with this function.

field(field: string): any
Parameters
field (string)
Returns
any:

Gets the underlying object this facade wraps around.

If this facade has a property type, it will be invoked as a function and will be assigned as the property type of the outputted object.

json(): Object
Returns
Object:

Get the options of a call. If an integration is passed, only the options for that integration are included. If the integration is not enabled, then undefined is returned.

Options are taken from the options property of the underlying object, falling back to the object's context or simply {}.

options(integration: string): (Object | undefined)
Parameters
integration (string) The name of the integration to get settings for. Casing does not matter.
Returns
(Object | undefined):

An alias for Facade#options.

context

Check whether an integration is enabled.

Basically, this method checks whether this integration is explicitly enabled. If it isn'texplicitly mentioned, it checks whether it has been enabled at the global level. Some integrations (e.g. Salesforce), cannot enabled by these global event settings.

More concretely, the deciding factors here are:

  1. If this.integrations() has the integration set to true, return true.
  2. If this.integrations().providers has the integration set to true, return true.
  3. If integrations are set to default-disabled via global parameters (i.e. options.providers.all, options.all, or integrations.all), then return false.
  4. If the integration is one of the special default-deny integrations (currently, only Salesforce), then return false.
  5. Else, return true.
enabled(integration: string): boolean
Parameters
integration (string)
Returns
boolean:

Check whether the user is active.

active(): boolean
Returns
boolean:

anonymousId

lib/facade.js

Get sessionId / anonymousId.

anonymousId(): any
Returns
any:

sessionId

lib/facade.js

An alias for Facade#anonymousId.

sessionId(): string
Returns
string:

Get groupId from context.groupId.

groupId(): string
Returns
string:

Get the call's "traits". All event types can pass in traits, though Identify and Group override this implementation.

Traits are gotten from options.traits, augmented with a property id with the event's userId.

The parameter aliases is meant to transform keys in options.traits into new keys. Each alias like { "xxx": "yyy" } will take whatever is at xxx in the traits, and move it to yyy. If xxx is a method of this facade, it'll be called as a function instead of treated as a key into the traits.

traits(aliases: Object): Object
Parameters
aliases (Object) A mapping from keys to the new keys they should be transformed to.
Returns
Object:
Example
let obj = { options: { traits: { foo: "bar" } }, anonymousId: "xxx" }
let facade = new Facade(obj)

facade.traits() // { "foo": "bar" }
facade.traits({ "foo": "asdf" }) // { "asdf": "bar" }
facade.traits({ "sessionId": "rofl" }) // { "rofl": "xxx" }

The library and version of the client used to produce the message.

If the library name cannot be determined, it is set to "unknown". If the version cannot be determined, it is set to null.

library(): {name: string, version: string}
Returns
{name: string, version: string}:

Return the device information, falling back to an empty object.

Interesting values of type are "ios" and "android", but other values are possible if the client is doing something unusual with context.device.

device(): {type: string}
Returns
{type: string}:

userAgent

lib/facade.js

Get the User-Agent from context.userAgent.

This should be a string, but may not be if the client isn't adhering to the spec.

userAgent(): any
Returns
any: string

Get the timezone from context.timezone.

This should be a string, but may not be if the client isn't adhering to the spec.

timezone(): any
Returns
any: string

timestamp

lib/facade.js

Get the timestamp from context.timestamp.

timestamp(): any
Returns
any: string

Get the channel from channel.

This should be a string, but may not be if the client isn't adhering to the spec.

channel(): any
Returns
any: string

Get the IP address from context.ip.

This should be a string, but may not be if the client isn't adhering to the spec.

ip(): any
Returns
any: string

Get the user ID from userId.

This should be a string, but may not be if the client isn't adhering to the spec.

userId(): any
Returns
any: string

Get the ZIP/Postal code from traits, traits.address, properties, or properties.address.

This should be a string, but may not be if the client isn't adhering to the spec.

zip(): string
Returns
string:

Get the country from traits, traits.address, properties, or properties.address.

This should be a string, but may not be if the client isn't adhering to the spec.

country(): string
Returns
string:

Get the street from traits, traits.address, properties, or properties.address.

This should be a string, but may not be if the client isn't adhering to the spec.

street(): string
Returns
string:

Get the state from traits, traits.address, properties, or properties.address.

This should be a string, but may not be if the client isn't adhering to the spec.

state(): string
Returns
string:

Get the city from traits, traits.address, properties, or properties.address.

This should be a string, but may not be if the client isn't adhering to the spec.

city(): string
Returns
string:

Get the region from traits, traits.address, properties, or properties.address.

This should be a string, but may not be if the client isn't adhering to the spec.

region(): string
Returns
string:

Initialize a new Group facade with a dictionary of arguments.

new Group(dictionary: Object, opts: Object)

Extends Facade

Parameters
dictionary (Object) The object to wrap.
Name Description
dictionary.userId string? The user to add to the group.
dictionary.groupId string? The ID of the group.
dictionary.traits Object? The traits of the group.
opts (Object) Options about what kind of Facade to create.

Return the type of facade this is. This will always return "group".

action(): string
Returns
string:

An alias for Group#action.

type(): string
Returns
string:

Get the group ID from groupId.

This should be a string, but may not be if the client isn't adhering to the spec.

groupId
Returns
string:

Get the time of creation of the group from traits.createdAt, traits.created, properties.createdAt, or properties.created.

created(): Date
Returns
Date:

Get the group's email from traits.email, falling back to groupId only if it looks like a valid email.

email(): string
Returns
string:

Get the group's traits. This is identical to how Facade#traits works, except it looks at traits.* instead of options.traits.*.

Traits are gotten from traits, augmented with a property id with the event's groupId.

The parameter aliases is meant to transform keys in traits into new keys. Each alias like { "xxx": "yyy" } will take whatever is at xxx in the traits, and move it to yyy. If xxx is a method of this facade, it'll be called as a function instead of treated as a key into the traits.

traits(aliases: Object): Object
Parameters
aliases (Object) A mapping from keys to the new keys they should be transformed to.
Returns
Object:
Example
var obj = { traits: { foo: "bar" }, anonymousId: "xxx" }
var group = new Group(obj)

group.traits() // { "foo": "bar" }
group.traits({ "foo": "asdf" }) // { "asdf": "bar" }
group.traits({ "sessionId": "rofl" }) // { "rofl": "xxx" }

Get the group's name from traits.name.

This should be a string, but may not be if the client isn't adhering to the spec.

name(): string
Returns
string:

Get the group's industry from traits.industry.

This should be a string, but may not be if the client isn't adhering to the spec.

industry(): string
Returns
string:

employees

lib/group.js

Get the group's employee count from traits.employees.

This should be a number, but may not be if the client isn't adhering to the spec.

employees(): number
Returns
number:

properties

lib/group.js

Get the group's properties from traits or properties, falling back to simply an empty object.

properties(): Object
Returns
Object:

Initialize a new Identify facade with a dictionary of arguments.

new Identify(dictionary: Object, opts: Object)

Extends Facade

Parameters
dictionary (Object) The object to wrap.
Name Description
dictionary.userId string? The ID of the user.
dictionary.anonymousId string? The anonymous ID of the user.
dictionary.traits string? The user's traits.
opts (Object) Options about what kind of Facade to create.

Return the type of facade this is. This will always return "identify".

action(): string
Returns
string:

An alias for Identify#action.

type(): string
Returns
string:

Get the user's traits. This is identical to how Facade#traits works, except it looks at traits.* instead of options.traits.*.

Traits are gotten from traits, augmented with a property id with the event's userId.

The parameter aliases is meant to transform keys in traits into new keys. Each alias like { "xxx": "yyy" } will take whatever is at xxx in the traits, and move it to yyy. If xxx is a method of this facade, it'll be called as a function instead of treated as a key into the traits.

traits(aliases: Object): Object
Parameters
aliases (Object) A mapping from keys to the new keys they should be transformed to.
Returns
Object:
Example
let obj = { traits: { foo: "bar" }, anonymousId: "xxx" }
let identify = new Identify(obj)

identify.traits() // { "foo": "bar" }
identify.traits({ "foo": "asdf" }) // { "asdf": "bar" }
identify.traits({ "sessionId": "rofl" }) // { "rofl": "xxx" }

Get the user's email from traits.email, falling back to userId only if it looks like a valid email.

This should be a string, but may not be if the client isn't adhering to the spec.

email(): string
Returns
string:

Get the time of creation of the user from traits.created or traits.createdAt.

created(): Date
Returns
Date:

companyCreated

lib/identify.js

Get the time of creation of the user's company from traits.company.created or traits.company.createdAt.

companyCreated(): Date
Returns
Date:

companyName

lib/identify.js

Get the user's company name from traits.company.name.

This should be a string, but may not be if the client isn't adhering to the spec.

companyName(): string
Returns
string:

Get the user's name traits.name, falling back to combining Identify#firstName and Identify#lastName if possible.

This should be a string, but may not be if the client isn't adhering to the spec.

name(): string
Returns
string:

Get the user's first name from traits.firstName, optionally splitting it out of a the full name if that's all that was provided.

Splitting the full name works on the assumption that the full name is of the form "FirstName LastName"; it will not work for non-Western names.

This should be a string, but may not be if the client isn't adhering to the spec.

firstName(): string
Returns
string:

Get the user's last name from traits.lastName, optionally splitting it out of a the full name if that's all that was provided.

Splitting the full name works on the assumption that the full name is of the form "FirstName LastName"; it will not work for non-Western names.

This should be a string, but may not be if the client isn't adhering to the spec.

lastName(): string
Returns
string:

Get the user's "unique id" from userId, traits.username, or traits.email.

This should be a string, but may not be if the client isn't adhering to the spec.

uid(): string
Returns
string:

description

lib/identify.js

Get the user's description from traits.description or traits.background.

This should be a string, but may not be if the client isn't adhering to the spec.

description(): string
Returns
string:

Get the user's age from traits.age, falling back to computing it from traits.birthday and the current time.

age(): number
Returns
number:

Get the URL of the user's avatar from traits.avatar, traits.photoUrl, or traits.avatarUrl.

This should be a string, but may not be if the client isn't adhering to the spec.

avatar(): string
Returns
string:

Get the user's job position from traits.position or traits.jobTitle.

This should be a string, but may not be if the client isn't adhering to the spec.

position(): string
Returns
string:

Get the user's username from traits.username.

This should be a string, but may not be if the client isn't adhering to the spec.

username(): string
Returns
string:

Get the user's website from traits.website, or if there are multiple in traits.websites, return the first one.

This should be a string, but may not be if the client isn't adhering to the spec.

website(): string
Returns
string:

Get the user's websites from traits.websites, or if there is only one in traits.website, then wrap it in an array.

This should be an array of strings, but may not be if the client isn't adhering to the spec.

websites(): array
Returns
array:

Get the user's phone number from traits.phone, or if there are multiple in traits.phones, return the first one.

This should be a string, but may not be if the client isn't adhering to the spec.

phone(): string
Returns
string:

Get the user's phone numbers from traits.phones, or if there is only one in traits.phone, then wrap it in an array.

This should be an array of strings, but may not be if the client isn't adhering to the spec.

phones(): array
Returns
array:

Get the user's address from traits.address.

This should be an object, but may not be if the client isn't adhering to the spec.

address(): object
Returns
object:

Get the user's gender from traits.gender.

This should be a string, but may not be if the client isn't adhering to the spec.

gender(): string
Returns
string:

Get the user's birthday from traits.birthday.

This should be a Date if opts.traverse was enabled (it is by default) when letructing this Identify. Otherwise, it should be a string. But it may be neither if the client isn't adhering to the spec. spec.

birthday(): object
Returns
object:

Initialize a new Page facade with a dictionary of arguments.

new Page(dictionary: Object, opts: Object)

Extends Facade

Parameters
dictionary (Object) The object to wrap.
Name Description
dictionary.category string? The page category.
dictionary.name string? The page name.
dictionary.properties string? The page properties.
opts (Object) Options about what kind of Facade to create.

Return the type of facade this is. This will always return "page".

action(): string
Returns
string:

An alias for Page#action.

type(): string
Returns
string:

category

lib/page.js

Get the page category from category.

This should be a string, but may not be if the client isn't adhering to the spec.

category
Returns
string:

Get the page name from name.

This should be a string, but may not be if the client isn't adhering to the spec.

name
Returns
string:

Get the page title from properties.title.

This should be a string, but may not be if the client isn't adhering to the spec.

title
Returns
string:

Get the page path from properties.path.

This should be a string, but may not be if the client isn't adhering to the spec.

path
Returns
string:

Get the page URL from properties.url.

This should be a string, but may not be if the client isn't adhering to the spec.

url
Returns
string:

referrer

lib/page.js

Get the HTTP referrer from context.referrer.url, context.page.referrer, or properties.referrer.

This should be a string, but may not be if the client isn't adhering to the spec.

referrer(): string
Returns
string:

properties

lib/page.js

Get the page's properties. This is identical to how Facade#traits works, except it looks at properties.* instead of options.traits.*.

Properties are gotten from properties, augmented with the page's name and category.

The parameter aliases is meant to transform keys in properties into new keys. Each alias like { "xxx": "yyy" } will take whatever is at xxx in the traits, and move it to yyy. If xxx is a method of this facade, it'll be called as a function instead of treated as a key into the traits.

properties(aliases: Object): Object
Parameters
aliases (Object) A mapping from keys to the new keys they should be transformed to.
Returns
Object:
Example
let obj = { properties: { foo: "bar" }, anonymousId: "xxx" }
let page = new Page(obj)

page.traits() // { "foo": "bar" }
page.traits({ "foo": "asdf" }) // { "asdf": "bar" }
page.traits({ "sessionId": "rofl" }) // { "rofl": "xxx" }

Get the user's email from context.traits.email or properties.email, falling back to userId if it's a valid email.

This should be a string, but may not be if the client isn't adhering to the spec.

email(): string
Returns
string:

fullName

lib/page.js

Get the page fullName. This is $category $name if both are present, and just name otherwiser.

This should be a string, but may not be if the client isn't adhering to the spec.

fullName(): string
Returns
string:

Get an event name from this page call. If name is present, this will be Viewed $name Page; otherwise, it will be Loaded a Page.

event(name: string): string
Parameters
name (string) The name of this page.
Returns
string:

Convert this Page to a Track facade. The inputted name will be converted to the Track's event name via Page#event.

track(name: string): Track
Parameters
name (string)
Returns
Track:

Initialize a new Screen facade with a dictionary of arguments.

Note that this class extends Page, so its methods are available to instances of this class as well.

new Screen(dictionary: Object, opts: Object)

Extends Page

Parameters
dictionary (Object) The object to wrap.
Name Description
dictionary.category string? The page category.
dictionary.name string? The page name.
dictionary.properties string? The page properties.
opts (Object) Options about what kind of Facade to create.
Instance Members
action()
type()
event(name)
track(name)

Initialize a new Track facade with a dictionary of arguments.

new Track(dictionary: Object, opts: Object)

Extends Facade

Parameters
dictionary (Object) The object to wrap.
Name Description
dictionary.event string? The name of the event being tracked.
dictionary.userId string? The ID of the user being tracked.
dictionary.anonymousId string? The anonymous ID of the user.
dictionary.properties string? Properties of the track event.
opts (Object) Options about what kind of Facade to create.

Return the type of facade this is. This will always return "track".

action(): string
Returns
string:

An alias for Track#action.

type(): string
Returns
string:

Get the event name from event.

This should be a string, but may not be if the client isn't adhering to the spec.

event(): string
Returns
string:

Get the event value, usually the monetary value, from properties.value.

This should be a number, but may not be if the client isn't adhering to the spec.

value(): number
Returns
number:

Get the event cateogry from properties.category.

This should be a string, but may not be if the client isn't adhering to the spec.

category(): string
Returns
string:

Get the event ID from properties.id.

This should be a string, but may not be if the client isn't adhering to the spec.

id(): string
Returns
string:

productId

lib/track.js

Get the product ID from properties.productId.

This should be a string, but may not be if the client isn't adhering to the spec.

productId(): string
Returns
string:

promotionId

lib/track.js

Get the promotion ID from properties.promotionId.

This should be a string, but may not be if the client isn't adhering to the spec.

promotionId(): string
Returns
string:

Get the cart ID from properties.cartId.

This should be a string, but may not be if the client isn't adhering to the spec.

cartId(): string
Returns
string:

checkoutId

lib/track.js

Get the checkout ID from properties.checkoutId.

This should be a string, but may not be if the client isn't adhering to the spec.

checkoutId(): string
Returns
string:

paymentId

lib/track.js

Get the payment ID from properties.paymentId.

This should be a string, but may not be if the client isn't adhering to the spec.

paymentId(): string
Returns
string:

Get the coupon ID from properties.couponId.

This should be a string, but may not be if the client isn't adhering to the spec.

couponId(): string
Returns
string:

wishlistId

lib/track.js

Get the wishlist ID from properties.wishlistId.

This should be a string, but may not be if the client isn't adhering to the spec.

wishlistId(): string
Returns
string:

Get the review ID from properties.reviewId.

This should be a string, but may not be if the client isn't adhering to the spec.

reviewId(): string
Returns
string:

Get the order ID from properties.id or properties.orderId.

This should be a string, but may not be if the client isn't adhering to the spec.

orderId(): string
Returns
string:

Get the SKU from properties.sku.

This should be a string, but may not be if the client isn't adhering to the spec.

sku(): string
Returns
string:

Get the amount of tax for this purchase from properties.tax.

This should be a number, but may not be if the client isn't adhering to the spec.

tax(): number
Returns
number:

Get the name of this event from properties.name.

This should be a string, but may not be if the client isn't adhering to the spec.

name(): string
Returns
string:

Get the price of this purchase from properties.price.

This should be a number, but may not be if the client isn't adhering to the spec.

price(): number
Returns
number:

Get the total for this purchase from properties.total.

This should be a number, but may not be if the client isn't adhering to the spec.

total(): number
Returns
number:

Whether this is a repeat purchase from properties.repeat.

This should be a boolean, but may not be if the client isn't adhering to the spec.

repeat(): boolean
Returns
boolean:

Get the coupon for this purchase from properties.coupon.

This should be a string, but may not be if the client isn't adhering to the spec.

coupon(): string
Returns
string:

Get the shipping for this purchase from properties.shipping.

This should be a number, but may not be if the client isn't adhering to the spec.

shipping(): number
Returns
number:

Get the discount for this purchase from properties.discount.

This should be a number, but may not be if the client isn't adhering to the spec.

discount(): number
Returns
number:

shippingMethod

lib/track.js

Get the shipping method for this purchase from properties.shippingMethod.

This should be a string, but may not be if the client isn't adhering to the spec.

shippingMethod(): string
Returns
string:

paymentMethod

lib/track.js

Get the payment method for this purchase from properties.paymentMethod.

This should be a string, but may not be if the client isn't adhering to the spec.

paymentMethod(): string
Returns
string:

description

lib/track.js

Get a description for this event from properties.description.

This should be a string, but may not be if the client isn't adhering to the spec.

description(): string
Returns
string:

Get a plan, as in the plan the user is on, for this event from properties.plan.

This should be a string, but may not be if the client isn't adhering to the spec.

plan(): string
Returns
string:

Get the subtotal for this purchase from properties.subtotal.

If properties.subtotal isn't available, then fall back to computing the total from properties.total or properties.revenue, and then subtracting tax, shipping, and discounts.

If neither subtotal, total, nor revenue are available, then return 0.

subtotal(): number
Returns
number:

Get the products for this event from properties.products if it's an array, falling back to an empty array.

products(): Array
Returns
Array:

Get the quantity for this event from properties.quantity, falling back to a quantity of one.

quantity(): number
Returns
number:

Get the currency for this event from properties.currency, falling back to "USD".

currency(): string
Returns
string:

Get the referrer for this event from context.referrer.url, context.page.referrer, or properties.referrer.

This should be a string, but may not be if the client isn't adhering to the spec.

referrer(): string
Returns
string:

Get the query for this event from options.query.

This should be a string, but may not be if the client isn't adhering to the spec.

query(): (string | object)
Returns
(string | object):

properties

lib/track.js

Get the page's properties. This is identical to how Facade#traits works, except it looks at properties.* instead of options.traits.*.

Properties are gotten from properties.

The parameter aliases is meant to transform keys in properties into new keys. Each alias like { "xxx": "yyy" } will take whatever is at xxx in the traits, and move it to yyy. If xxx is a method of this facade, it'll be called as a function instead of treated as a key into the traits.

properties(aliases: Object): Object
Parameters
aliases (Object) A mapping from keys to the new keys they should be transformed to.
Returns
Object:
Example
let obj = { properties: { foo: "bar" }, anonymousId: "xxx" }
let track = new Track(obj)

track.traits() // { "foo": "bar" }
track.traits({ "foo": "asdf" }) // { "asdf": "bar" }
track.traits({ "sessionId": "rofl" }) // { "rofl": "xxx" }

Get the username of the user for this event from traits.username, properties.username, userId, or anonymousId.

This should be a string, but may not be if the client isn't adhering to the spec.

username(): (string | undefined)
Returns
(string | undefined):

Get the email of the user for this event from trais.email, properties.email, or options.traits.email, falling back to userId if it looks like a valid email.

This should be a string, but may not be if the client isn't adhering to the spec.

email(): (string | undefined)
Returns
(string | undefined):

Get the revenue for this event.

If this is an "Order Completed" event, this will be the properties.total falling back to the properties.revenue. For all other events, this is simply taken from properties.revenue.

If there are dollar signs in these properties, they will be removed. The result will be parsed into a number.

revenue(): number
Returns
number:

Get the revenue for this event in "cents" -- in other words, multiply the Track#revenue by 100, or return 0 if there isn't a numerical revenue for this event.

cents(): number
Returns
number:

Convert this event into an Identify facade.

This works by taking this event's underlying object and creating an Identify from it. This event's traits, taken from options.traits, will be used as the Identify's traits.

identify(): Identify
Returns
Identify: