3.2.6
Initialize a new Alias
facade with a dictionary
of arguments.
Extends Facade
(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. |
(Object)
Options about what kind of Facade to create.
An alias for Alias#action.
string
:
An alias for Alias#previousId.
string
:
An alias for Alias#userId.
string
:
Initialize a new Delete
facade with a dictionary
of arguments.
Extends Facade
(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. |
(Object)
Options about what kind of Facade to create.
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.
(Object)
The object to wrap.
(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. |
Create a helper function for fetching a "plural" thing.
The generated method will take the inputted path
and append an "s" to it
and calls this.proxy
with this "pluralized" path. If that produces an
array, that will be returned. Otherwise, a one-element array containing
this.proxy(path)
will be returned.
(string)
Function
:
MyClass.prototype.birds = Facade.multi('animals.bird');
Create a helper function for getting a "singular" thing.
The generated method will take the inputted path and call
this.proxy(path)
. If a truthy thing is produced, it will be returned.
Otherwise, this.proxy(path + 's')
will be called, and if that produces an
array the first element of that array will be returned. Otherwise,
undefined
is returned.
(string)
Function
:
MyClass.prototype.bird = Facade.one('animals.bird');
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.
any
:
A property of the inputted object.
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.
(string)
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.
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 {}
.
(string)
The name of the integration to get settings
for. Casing does not matter.
(Object | undefined)
:
An alias for Facade#options.
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:
this.integrations()
has the integration set to true
, return true
.this.integrations().providers
has the integration set to true
, return true
.options.providers.all
, options.all
, or integrations.all
), then return
false.(string)
boolean
:
Check whether the user is active.
boolean
:
Get sessionId / anonymousId
.
any
:
An alias for Facade#anonymousId.
string
:
Get groupId
from context.groupId
.
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.
(Object)
A mapping from keys to the new keys they should be
transformed to.
Object
:
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
.
{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
.
{type: string}
:
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.
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.
any
:
string
Get the timestamp from context.timestamp
.
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.
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.
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.
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.
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.
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.
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.
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.
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.
string
:
Initialize a new Group
facade with a dictionary
of arguments.
Extends Facade
Return the type of facade this is. This will always return "group"
.
string
:
An alias for Group#action.
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.
string
:
Get the time of creation of the group from traits.createdAt
,
traits.created
, properties.createdAt
, or properties.created
.
Date
:
Get the group's email from traits.email
, falling back to groupId
only if
it looks like a valid email.
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.
(Object)
A mapping from keys to the new keys they should be
transformed to.
Object
:
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.
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.
string
:
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.
number
:
Get the group's properties from traits
or properties
, falling back to
simply an empty object.
Object
:
Initialize a new Identify
facade with a dictionary
of arguments.
Extends Facade
Return the type of facade this is. This will always return "identify"
.
string
:
An alias for Identify#action.
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.
(Object)
A mapping from keys to the new keys they should be
transformed to.
Object
:
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.
string
:
Get the time of creation of the user from traits.created
or
traits.createdAt
.
Date
:
Get the time of creation of the user's company from traits.company.created
or traits.company.createdAt
.
Date
:
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.
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.
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.
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.
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.
string
:
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.
string
:
Get the user's age from traits.age
, falling back to computing it from
traits.birthday
and the current time.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
object
:
Initialize a new Page
facade with a dictionary
of arguments.
Extends Facade
Return the type of facade this is. This will always return "page"
.
string
:
An alias for Page#action.
string
:
Get the page category from category
.
This should be a string, but may not be if the client isn't adhering to the spec.
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.
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.
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.
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.
string
:
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.
string
:
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.
(Object)
A mapping from keys to the new keys they should be
transformed to.
Object
:
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.
string
:
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.
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
.
(string)
The name of this page.
string
:
Convert this Page to a Track facade. The inputted name
will be
converted to the Track's event name via Page#event.
(string)
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.
Extends Page
(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. |
(Object)
Options about what kind of Facade to create.
An alias for Screen#action.
string
:
Convert this Screen to a Track facade. The inputted name
will be
converted to the Track's event name via Screen#event.
(string)
Track
:
Initialize a new Track
facade with a dictionary
of arguments.
Extends Facade
(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. |
(Object)
Options about what kind of Facade to create.
Return the type of facade this is. This will always return "track"
.
string
:
An alias for Track#action.
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.
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.
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.
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.
string
:
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.
string
:
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.
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.
string
:
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.
string
:
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.
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.
string
:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
number
:
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.
string
:
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.
string
:
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.
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.
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.
number
:
Get the products for this event from properties.products
if it's an
array, falling back to an empty array.
Array
:
Get the quantity for this event from properties.quantity
, falling back to
a quantity of one.
number
:
Get the currency for this event from properties.currency
, falling back to
"USD".
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.
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.
(string | object)
:
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.
(Object)
A mapping from keys to the new keys they should be
transformed to.
Object
:
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.
(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.
(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.
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.
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
: