Skip to content

Latest commit

 

History

History
203 lines (151 loc) · 10 KB

tracking.md

File metadata and controls

203 lines (151 loc) · 10 KB

Tracking Events

Track subscriber events as they happen on your website and let Hellotext report them back to your business.

Tracking events is straightforward and perhaps the simplest example is tracking a page view:

Hellotext.track('page.viewed')

In the example above only the name of the action is required.

Handling Responses

The track method returns a Promise that can be awaited using the async/await syntax. Or using .then on the returned Promise.

const response = await Hellotext.track('page.viewed')

The return of the Hellotext.track method is an instance of a Response object that ships with the package. You can check the status of the response via methods, like:

if (response.failed) {
  console.log('failed because', response.data)
}

if (response.succeeded) {
  console.log('success')
  console.log(response.data) // { status: "received" }
}

Parameters

The parameters passed to the action must be a valid set of parameters as described in Tracking Actions.

URL Parameter

The library takes care of handling the url parameter with the current URL automatically and is not required to specify it explicitly. If you want to provide another url, you can pass a url key in the params object when tracking an event.

Hellotext.track('page.viewed', {
  url: 'www.example.org',
})

Headers

You can add any custom or additional headers to the request by passing a headers object in the parameter.

Hellotext.track('page.viewed', {
  headers: {
    'X-Custom-Header': 'value',
  },
  // event related parameters
})

Errors

Failing to provide valid set of parameters will result in an error object being returned, describing the parameters that did not satisfy the rules.

const response = await Hellotext.track('app.installed', { object_parameters: { name: null } })

console.log(response.data)

yields

{
  errors: [
    {
      type: 'parameter_invalid_empty',
      parameter: 'name',
      description: 'This required parameter has an empty value. Provide a valid value for the parameter.',
    },
  ]
}

For a complete list of errors types. See Error Types

Event parameters

Every tracked event has the following parameters which you can pass to the track method:

Property Description Type Default
amount Monetary amount that represents the revenue associated to this tracked event. float 0
currency Currency for the amount given in ISO 4217 format. If not specified, the currency default to the business' configured reporting currency. currency USD
metadata Set of key-value pairs that you can attach to an event. This can be useful for storing additional information about the object in a structured format. hash {}
tracked_at Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from created_at. epoch null

Associated object parameters

Generally, most actions also require an associated object. These can be of type app, coupon, form, order, product and refund, these events require an existing object to be present in order to be tracked aside from Custom Actions, which don't require the trackable to be present.

Associated objects are represented by three possible parameters:

  • object: An ID of an existing object of the same type. For example, when tracking app events, the object must be a previously created app object.
  • object_parameters: A set of parameters for creating a new object of the same type. For example, when tracking app events, the object_parameters must be a set of parameters for creating a new app object.
  • object_type: An ID or name of an existing custom object. Only required when tracking custom objects. Lets Hellotext know which type of object is being tracked. Learn more about Objects.

You can create the associated object directly by defining its parameters in a hash:

Hellotext.track('order.placed', {
  amount: 395.0,
  currency: 'USD',
  object_parameters: {
    reference: '654321',
    source: 'myshop',
    items: [
      {
        product: 'erA2RAXE',
        quantity: 2,
      }
    ]
  },
})

If you want to reuse existing objects, you must pass the identifier of an existing associated object. For example, to track a product purchase the identifier of a previously created product object as the product. For more information about identifiers, view the Tracking API

Hellotext.track('product.purchased', {
  amount: 395.0,
  currency: 'USD',
  object: 'erA2RAXE',
})

List of actions

The following is a complete list of built-in actions and their required associated objects. Each associated action accepts a possible set of two parameters

Action Description Required Parameter
app.installed An app was installed. object or object_parameters
app.removed An app was removed. object or object_parameters
app.spent A customer spent on an app. object or object_parameters
cart.abandoned A cart was abandoned. object or object_parameters
cart.added Added an item to the cart. object or object_parameters
cart.removed Removed an item from the cart. object or object_parameters
coupon.redeemed A coupon was redeem by a customer. object or object_parameters
form.completed A form was completed by the customer. object or object_parameters
order.placed Order has been placed. object or object_parameters
order.confirmed Order has been confirmed by you. object or object_parameters
order.cancelled Order has been cancelled either by you or your customer. object or object_parameters
order.shipped Order has been shipped to your customer. object or object_parameters
order.delivered Order has been delivered to your customer. object or object_parameters
page.viewed A page was viewed by a customer. url
product.purchased A product has been purchased. object or object_parameters
product.viewed A product page has been viewed. object or object_parameters
refund.requested A customer requested a refund. object or object_parameters
refund.received A refund was issued by you to your customer. object or object_parameters

You can also create your own defined actions.

Tracking Custom Actions

Once you have created a custom action, you track it by specifying the action's name. Custom actions do not require an associated object to be present in order to be tracked. However, it's possible to track custom actions alongside existing Objects, or new objects you introduce.

// Custom Action without an associated object

Hellotext.track('appointment.booked')

// Custom Action with an existing custom object instance.

Hellotext.track('appointment.booked', {
  object_type: 'appointment',
  object: 'erA2RAXE',
})

// Custom Action with a new custom object instance.
Hellotext.track('appointment.booked', {
  object_type: 'appointment',
  object_parameters: {
    room: 'AA-101',
    booked_at: 1632313200,
  }
})

// Custom Action with a builtin object instance.

Hellotext.track('appointment.booked', {
  object_type: 'product',
  object: 'erA2RAXE',
})