Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Objects #20

Merged
merged 2 commits into from
Mar 3, 2025
Merged

Objects #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
056a914
update tracking readme
rockwellll Feb 24, 2025
a088618
update readme
rockwellll Feb 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,4 +138,4 @@ Hellotext.initialize('HELLOTEXT_BUSINESS_ID', configurationOptions)
| session | A valid Hellotext session which was stored previously. When not set, Hellotext attempts to retrieve the stored value from `document.cookie` when available, otherwise it creates a new session. | String | null |
| autoGenerateSession | Whether the library should automatically generate a session when no session is found in the query or the cookies | Boolean | true |
| forms | An object that controls how Hellotext should control the forms on the page. See [Forms](/docs/forms.md) documentation for more information. | Object | { autoMount: true, successMessage: true } |
| webchat | An object that controls how Hellotext should control the webchat on the page. See [Webchat](/docs/webchat.md) documentation for more information. | Object | { autoMount: true, successMessage: true } |
| webchat | An object that controls how Hellotext should control the webchat on the page. See [Webchat](/docs/webchat.md) documentation for more information. | Object | {} |
127 changes: 81 additions & 46 deletions docs/tracking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Hellotext.track('page.viewed', {
Failing to provide valid set of parameters will result in an error object being returned, describing the parameters that did not satisfy the rules.

```javascript
const response = await Hellotext.track('app.installed', { app_parameters: { name: 'My App' } })
const response = await Hellotext.track('app.installed', { object_parameters: { name: null } })

console.log(response.data)
```
Expand All @@ -76,31 +76,54 @@ yields
{
errors: [
{
type: 'parameter_not_unique',
type: 'parameter_invalid_empty',
parameter: 'name',
description:
'The value must be unique and it is already present in another object of the same type.',
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](https://www.hellotext.com/api#errors)

### Associated objects
### Event parameters

Generally, most actions also require an associated object. These can be of type [`app`](https://www.hellotext.com/api#apps), [`coupon`](https://www.hellotext.com/api#coupons), [`form`](https://www.hellotext.com/api#forms), [`order`](https://www.hellotext.com/api#orders), [`product`](https://www.hellotext.com/api#products) and [`refund`](https://www.hellotext.com/api#refunds).
Aside from [Custom Actions](https://www.hellotext.com/api#create_an_action), which don't require the trackable to be present.
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`](https://www.hellotext.com/api#apps), [`coupon`](https://www.hellotext.com/api#coupons), [`form`](https://www.hellotext.com/api#forms), [`order`](https://www.hellotext.com/api#orders), [`product`](https://www.hellotext.com/api#products) and [`refund`](https://www.hellotext.com/api#refunds), these events require an existing object to be present
in order to be tracked aside from [Custom Actions](https://www.hellotext.com/api#create_an_action), 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](https://www.hellotext.com/api#objects).

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

```javascript
Hellotext.track('order.placed', {
amount: 395.0,
currency: 'USD',
order_parameters: {
amount: '395.00',
object_parameters: {
reference: '654321',
source: 'myshop',
items: [
{
product: 'erA2RAXE',
quantity: 2,
}
]
},
})
```
Expand All @@ -112,57 +135,69 @@ For more information about identifiers, view the [Tracking API](https://www.hell
Hellotext.track('product.purchased', {
amount: 395.0,
currency: 'USD',
product: 'erA2RAXE',
object: 'erA2RAXE',
})
```

## List of actions

The following is a complete list of built-in actions and their required associated objects.
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. | `app` or [app_parameters](https://www.hellotext.com/api#app) |
| **app.removed** | An app was removed. | `app` or [app_parameters](https://www.hellotext.com/api#app) |
| **app.spent** | A customer spent on an app. | `app` or [app_parameters](https://www.hellotext.com/api#app) |
| **cart.abandoned** | A cart was abandoned. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
| **cart.added** | Added an item to the cart. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
| **cart.removed** | Removed an item from the cart. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
| **coupon.redeemed** | A coupon was redeem by a customer. | `coupon` or [coupon_parameters](https://www.hellotext.com/api#coupons) |
| **form.completed** | A form was completed by the customer. | `form` or [form_parameters](https://www.hellotext.com/api#forms) |
| **order.placed** | Order has been placed. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
| **order.confirmed** | Order has been confirmed by you. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
| **order.cancelled** | Order has been cancelled either by you or your customer. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
| **order.shipped** | Order has been shipped to your customer. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
| **order.delivered** | Order has been delivered to your customer. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
| --------------------- | -------------------------------------------------------- |---------------------------------------------------------------------------|
| **app.installed** | An app was installed. | `object` or [object_parameters](https://www.hellotext.com/api#app) |
| **app.removed** | An app was removed. | `object` or [object_parameters](https://www.hellotext.com/api#app) |
| **app.spent** | A customer spent on an app. | `object` or [object_parameters](https://www.hellotext.com/api#app) |
| **cart.abandoned** | A cart was abandoned. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
| **cart.added** | Added an item to the cart. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
| **cart.removed** | Removed an item from the cart. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
| **coupon.redeemed** | A coupon was redeem by a customer. | `object` or [object_parameters](https://www.hellotext.com/api#coupons) |
| **form.completed** | A form was completed by the customer. | `object` or [object_parameters](https://www.hellotext.com/api#forms) |
| **order.placed** | Order has been placed. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
| **order.confirmed** | Order has been confirmed by you. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
| **order.cancelled** | Order has been cancelled either by you or your customer. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
| **order.shipped** | Order has been shipped to your customer. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
| **order.delivered** | Order has been delivered to your customer. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
| **page.viewed** | A page was viewed by a customer. | `url` |
| **product.purchased** | A product has been purchased. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
| **product.viewed** | A product page has been viewed. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
| **refund.requested** | A customer requested a refund. | `refund` or [refund_parameters](https://www.hellotext.com/api#refunds) |
| **refund.received** | A refund was issued by you to your customer. | `refund` or [refund_parameters](https://www.hellotext.com/api#refunds) |
| **product.purchased** | A product has been purchased. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
| **product.viewed** | A product page has been viewed. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
| **refund.requested** | A customer requested a refund. | `object` or [object_parameters](https://www.hellotext.com/api#refunds) |
| **refund.received** | A refund was issued by you to your customer. | `object` or [object_parameters](https://www.hellotext.com/api#refunds) |

You can also create your **[own defined actions](https://www.hellotext.com/api#actions)**.

## Additional Properties
### Tracking Custom Actions

You can include additional attributes to the tracked event, additional properties must be included inside the `metadata` object:
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.

```javascript
Hellotext.track('product.purchased', {
amount: 0.2,
currency: 'USD',
metadata: {
myProperty: 'custom',
},
tracked_at: 1665684173,
// 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',
})
```

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

| 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. | 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` |
// Custom Action with a builtin object instance.

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